TreeGrid v6.0

Upload changes

TreeGrid documentation index

 

TreeGrid can upload data to remote or local server or include the data to HTML page and submit it.

You need to set Upload_Url for background AJAX upload or Upload_Tag for whole page submit.

 

<treegrid,bdo> prefix   Upload_                                                                                                                                                     .

Data source to upload changes to server. It is called after click to Save button or for every change when is set AutoUpdate.

It can return success (<Grid><IO Result=’0’/></Grid>) or error message or XML data with changes to apply them in grid.

By default is set Upload_Method=”Form” Upload_Data=”Data” Upload_Type=”1” Upload_Format=”Internal” Upload_Xml=”0”   

Supports only AJAX or Submit communication (Upload_Url or Upload_Tag attribute). The XML changes are sent in Data parameter.

 

<treegrid,bdo> string    Upload_Url                                                                                                                                             .

Set it to URL address to send the changes XML by AJAX or AJAX SOAP. The changes are stored in parameter Data.

When used AJAX method, the changes XML is upload on background while grid is still accessible.

If server returns success XML <Grid><IO Result=’0’/></Grid> all the changes are accepted (the deleted rows are deleted, other rows are recolored to loose its flag).

If server returns error XML <Grid><IO Result=’-1’/><Grid> or the AJAX call failed at all, the changes are not accepted and can be sent again.

The server can also return message to alert it to user to inform him about success or error: <Grid><IO Result=’-1’ Message=’Save failed’/><Grid>

The server can also return some updates in <Changes> tag to do them in grid, for example mark some cell by Error to highlight it to user.

It is possible to set Upload_Sync=”1” to wait for response and disable grid while waiting for response.

 

<treegrid,bdo> string    Upload_Tag                                                                                                                                           .

Set it to <input> tag name or id where the changes XML will be stored. To use old Submit method of uploading.

This <input> tag should be placed within some <form>. This form will be automatically submitted to its action url.

After form submit, the whole page will be reloaded or redirected according to the <form> settings.

 

<treegrid,bdo> string[]  Upload_Type  [“Changes”]                                                                                                    upd 7.0 .

What parts of grid will be uploaded to server, it is an array of comma separated keywords.

It can contain more keywords to send more parts to the server. The keywords are case insensitive. The order of filled parts is not specified.

For example Upload_Type=“changes,settings,cookie”

 

Changes

Modified rows - rows with set attribute Added, Deleted, Moved or Changed (modified values). The rows are sent in <Changes> tag.

Set this keyword to get only changed rows on server to update a database according to the changes.

The rows have filled only attributes required for its state like Parent or id. To fill any other or custom attribute set Upload_Attrs.

To fill all column values or values from defaults specify Upload_Flags=”Defaults” or “AllCols”

 

Selected

Selected rows – rows with set attribute Selected. The rows are sent in <Changes> tag.

Set this keyword to get the selected rows on server to do provide action on server with these rows.

The rows can be selected by a user or by search or by API.

The rows have filled only id attribute. To fill any other or custom attribute set Upload_Attrs.

To fill all column values or values from defaults specify Upload_Flags=”Defaults” or “AllCols”

 

Body

All variable rows. The rows are uploaded as they are in pages and body, in tag <Body><B></B></Body>

Set this attribute to get the whole body to just store it on server and return it in next body request.

To fill only column values specify Upload_Flags=“AllCols”. To fill only some specified attributes set Upload_Attrs.

Setting this attribute can significantly slow data communication for larger grids. Not compatible with server paging.

 

Data

All data rows (<I Kind=’Data’/>). The data rows are all rows with no special meaning (unlike Header, Filter, Group, Search, Pager, Space, User).

The rows are uploaded as they are in pages and body, in tag <Body><B></B></Body>, <Head></Head> and <Foot></Foot>

These rows are variable (body) and can be also fixed rows.

Set this attribute to get all the cells that can have values to just store it on server and return it in next grid request.

To fill only column values specify Upload_Flags=“AllCols”. To fill only some specified attributes set Upload_Attrs.

Setting this attribute can significantly slow data communication for larger grids. Not compatible with server paging.

 

All

All rows in grid, including all functional rows (Data, Header, Filter, Group, Search, Pager, Space).

The rows are uploaded as they are in pages and body, in tag <Body><B></B></Body>, <Head></Head> and <Foot></Foot> and <Solid></Solid>

Set this attribute to get all rows on server to store the complete XML here and return it on next request

To fill only column values specify Upload_Flags=“AllCols”. To fill only some specified attributes set Upload_Attrs.

Setting this attribute can significantly slow data communication for larger grids. Not compatible with server paging.

 

Span (since 7.0)

All rows with some cells spanned (through columns or rows), sends only attributes id, Span and RowSpan. The rows are sent in <Spanned> tag.

To send only changes in span, set rather Upload_Flags=”Spanned” Upload_Type=”Changes”.

 

Gantt (since 6.3)

Uploads actual Gantt settings in <Gantt ... /> tag.

Uploads the attributes: GanttBase, GanttExclude, GanttExcludeRepeat, GanttInclude, GanttIncludeRepeat

 

Settings

Sends grid configuration similarly to Data and Page request.

Sends sort settings in <Cfg>, filter setting in <Filters> and columns’ widths and positions in <LeftCols>, <Cols>, <RightCols>.

 

Expanded (since 6.7)

Sends ids of all expanded rows in <Cfg Expanded/> attribute, comma separated.

 

Cookie

Sends the whole configuration in <Cfg Cookie/> attribute like it is stored to cookies.

It can be used to store the configuration on server instead of client’s cookies – based on some user identification and not browser.

Return this configuration in next request for Layout in <Cfg Cookie/> to apply it.

The Cookie should not be modified on server, it should be used as black box.

 

Cfg

Adds <Cfg> tag, sends all attributes from this tag, including some runtime internal settings.

 

Def

Adds <Def>,<D>,<Root> tags, sends all defaults with all attributes in Internal format only, including some runtime internal attributes.

 

Cols

Adds <LeftCols>, <Cols>, <RightCols>, <C> tags, sends all columns’ settings, including some runtime internal attributes.

 

Other

Adds <MenuCfg>, <Pager>, <Actions> tags, sends all attributes of these tags.

 

Lang

Adds <Lang> tag, sends all texts and format settings.

 

<treegrid,bdo> string[]  Upload_Flags                                                                                                                                      upd 7.0 .

Various flags for extended control of uploading, comma separated list of keywords. It is case insensitive.

For example Upload_Flags=”defaults,noio”

 

Defaults             Sends also default values (from <D> tag) in rows if the row attribute value is null, for Upload_Type=”Changes,Selected,Body,Data,All”

AllCols               Sends all column values in rows, including calculated cells, for Upload_Type = “Changes,Selected,Body,Data,All”

Spanned             (Since 7.0) Sends also changes in colspan (Span) and rowspan (RowSpan) attributes in <Changes> tag, for Upload_Type=”Changes”

                           It must be set on grid start to store required information for the comparing changes

Accepted            Does not send deleted rows and does not send state attributes Added, Moved and Changed, for Upload_Type=”Body,Data,All”.

NoIO                 Does not send <IO> tag. The IO contains Session attribute.

NoGrid              Does not include <Grid> tag, if you need to append some other tags to XML. The XML is not valid in this case!

 

<treegrid,bdo> string [] Upload_Attrs                                                                                                                                       .

Comma separated list of names of row attributes that are uploaded. The names must be in Internal format (col+name).

 

For Upload_Type=”Changes” specifies all custom attributes to upload with the changed rows. It adds all these attribute values to all the uploaded rows.

These attributes must not interfere with standard uploaded names like id, Added or Parent.

The Attrs are ignored when set SaveOrder=’1’.

 

For Upload_Type=”Selected,Body,Data,All” specifies all attributes except id and Def.

If this attribute is omitted, fills all rows’ attributes. For large grids it can be significantly slower.

The row has always set id and Def attributes, do not include them to Attrs list.

 

<treegrid,bdo> bool      Upload_Xml                  [0]                                                                                                                    .

If the uploaded data will be send as is or will be sent with coded XML entities.

For 0 (default) are uploaded data encoded to string (& and <,> are replaced by &amp; &lt; &gt;). 

For 1 data are uploaded as XML without any change.

 

<treegrid,bdo> bool       Upload_Sync                                                                                                                                       .

Sets synchronous upload for AJAX communication.

The grid is disabled during upload and waits for server response.

 

<Cfg>                bool       SaveOrder          [0]                                                                                                                   new 6.4 .

If set to 1 and uploads all changes in <Changes> tag, it uploads them in the exact order they happened.

If row is changed more times, it can be included more times.

All changes done in one row together (without changing another row between changes) are merged together.

Undeleted deleted row is ignored. Deleted added row is ignored.

All changes done in row immediately deleted after (without changing other row) are ignored.

All undone or redone changes are taken as new changes.

 

<Cfg>                type      DateStrings      [0/1]                                                                                                                chg 6.0 .

If set to 0, Date values are uploaded as numbers (milliseconds from 1/1/1970), see also GMT attribute.

If set to 1, Date values are uploaded as strings in English format (M/d/yyyy HH:mm:ss).

If set to 2, Date values are uploaded as strings in JAVA format (yyyy-MM-dd HH:mm:ss).

If set to string, it specifies the full date format for upload

By default it is set to 0, if some date in input XML is set as number of milliseconds, otherwise is set to 1.

 

<Cfg>                bool       AutoUpdate      [0]         It is saved to and loaded from cookies                                                           .

If automatically uploads all changes immediately to server.

If set to 1, after any change in data (edit cell, add, delete, move row) it sends changed data to server like a user clicked to Save button on toolbar.

 

<I>                     bool       NoUpload           [0/1]                                                                                                                              .

If set to 1, ignores changes in this row and does not upload them to server. Often set with also NoColorState.

Default value is 0 for data rows and 1 for space rows.

Filter row has always set 1.

 

API for Upload

 

 

API event          bool       OnSave     (TGrid grid, TRow row, bool autoupdate)                                                                              .

Called before changes are uploaded or submitted to server.

It is called from Save method that is called when a user clicks Save button. It is called after validation (see <Cfg Validate>).

It is also called whenever are changes uploaded by AutoUpdate (with autoupdate parameter set to 1)

Return true to suppress saving.

The row is set if only one row was changed, this is the row to update, only with autoupdate = 1.

 

API event          void       OnAfterSave    (TGrid grid, int result, bool autoupdate)                                                                    .

Called after Save or AutoUpdate is done, the server response was received and changes accepted (if succeeded).

The result is the <IO Result/>, <0 error, >=0 success.

It is called only for AJAX communication.

 

API event          string    OnUpload           (TGrid grid, string xml, TRow row, bool autoupdate)                                new 6.0 .

Called to modify changes in XML data before they are uploaded.

The XML is the XML to upload (<Grid> ... </Grid>)

Return new XML data in string for upload or null to not change the data.

 

API method      void       Save             (Event event)                                                                                                                            .

Uploads all changes to server.

For AJAX it uploads all changes to grid.Source.Upload.Url. If server returns success, it accepts all changes.

For Submit it fills grid.Source.Upload.Tag input with all changes and submits form where the input is placed.

The event is set if the method is called from onsubmit event hander to this event. In this case it also validates data. It cancels the event if saving is canceled.

 

API method      void       UploadChanges       (TRow row, function Func)                                                                           .

Uploads all changes to server, only if AutoUpdate is true. If row is set, uploads changes in the row only.

After finish, calls function Func: function Func (int result).

Accepts changes only if server Result is ok (>=0), if result < 0 does not accept changes.

 

API method      string    GetChanges     (TRow row = null)                                                                                                       .

Returns all changed rows in XML string to upload to server. If row is set, returns changes of this row only.

Format of the data is used according to grid.Source.Upload.Format.

 

API method      int          HasChanges    ( )                                                                                                                                  .

If the grid contains some changed (Added/Deleted/Moved/Changed) or selected (Selected) rows.

Returns &1 if grid contains some change not yet uploaded to server. Only when SaveValues is not set.

Returns &2 if grid contains some selected rows. Only when SaveSelected is not set.

 

API method      void       AcceptChanges        (TRow row = null)                                                                                          .

Accepts all changes in grid – clears all flags Changed, Added, Moved and removes rows marked as Deleted.

Displays all updates in grid.

Can be called after server accepts sent data.

If row is set, updates only this row.

 

API method      string    GetXmlData     (string type = Upload_Type+”,”+Upload_Flags, string attrs = Upload_Attrs)    .

Returns grid’s data in XML according to type and attrs, see Upload_Type and Upload_Flags.

This method is used to upload changes to server by Save and AutoUpdate.

 

<Actions>                      Save                          Attached to event OnClickButtonSave                                                                     .

Uploads all changes to server and accepts them. See Save method.

 

XML structure sent to server

 

Data sent from grid to server. Used when uploading changes to server. This format is generated by grid.

Here is described default structure used for <treegrid Upload_Type=’Changes’/>. For other settings the uploaded XML will contain other requested tags similar to Layout and Data XML.

Used as request sent to data source Upload.

 

<Grid> (Root tag, can accept any count of introduced child tags in any order)

         <IO ... attributes with client request ... />

         <Changes> (list of changed rows)

                  <I id=’...’ ... row and cell attributes ... />

                  ... More tags <I> ...

         </Changes>

</Grid>

 

The uploaded rows can have set these attributes:

id – this attribute is always set to identify uploaded row. There are many ways to set this attribute, see rows identity.

Deleted – The row has been deleted by a user. No other attribute is set.

Changed – Some cell value of the row has been changed. The row contains values of all changed cell. The row can also contain the Moved attribute.

Moved – The row has been moved to new position. The Parent and Next attributes specify new position. The row can also contain Changed attribute.

Added – The row is new row. The row contains new generated id. The Parent and Next attributes specify new position. The Def attribute specifies default values.

             The row also contains all cell values, that are not the same as default values and are not calculated.

Parent - (set for Added or Moved) - the parent row or page where the row has been moved row added. It is string for row id or number for page position.

Next - (set for Added or Moved) – the next row before it the row has been added or moved. It is string for row id.

Prev - (set for Added or Moved) – the previous row after it the row has been added or moved. It is string for row id.

Copy – (set for Added) – set only if the row is copy of another row and the source row does not have downloaded its children yet (in server child paging). 

It is string for row id.

 

When server returns HTTP error or <IO Result < 0, the TreeGrid shows message if provided and does not accept changes. The changes can be sent again.

If server return HTTP OK and <IO Result is not set or is >= 0, the TreeGrid accepts all changes – deleted rows are physically deleted and other flags are cleared.

 

Example of changed data sent to server:

<Grid>

<Changes>

<I id=’xy’ Changed=’1’ A=’12’/>

<I id=’xa’ Moved=’1’ Parent=’aa’ Next=’xc’ Prev=’xb’/>

<I id=’xz’ Added=’1’ Parent=’1’ Next=’’ Prev=’xx’ A=’3’ B=’7’ C=’5.4’ D=’-3’ E=’twenty six’/>

<I id=’xg’ Deleted=’1’/>

</Changes>

</Grid>