Upload changes
TreeGrid documentation
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.
upd 11.0 <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.
Since 11.0 if the Upload_Tag is set to "Debug", it does not upload the data, just prints them in debug window, if debugging print permitted.
chg 6.0 upd 13.0 <treegrid,bdo> string[ ]
Upload_Type
["Changes"]
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.
Note, uploaded files in File type are not sent in the XML, but apart like the standard <input type="file"> values.
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 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"
Since 12.1 it uploads also all selected cells of the rows with Selected=2.
Since 12.1 it uploads also all selected columns.
Resized (since 11.0)
Resized rows - rows with changed
Height. The rows are sent in <
Changes> tag.
Rows resized by a user.
The rows have filled only id and Height attributes.
Cells (Since 12.0)
Rows with some attribute changed. The rows are sent in <
Changes> tag or
since 12.1 in <
Body> tag if Upload_Type contains also "Changes".
If set, stores all original data on start for comparing. Therefore it must be set on start.
Use it with
NoEmpty Upload_Flags to list only changed rows.
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,
GanttFinish,
GanttExclude, GanttInclude.
(Since 8.0) When set Cfg DateStrings, the GanttBase and GanttFinish are uploaded also as strings in GanttBaseDate and GanttFinishDate attributes.
Calendars (since 8.0)
Uploads actual calendars in <Calendars> tag.
Resources (since 8.0)
Uploads actual resources in <Resources> tag.
Settings
Sends grid configuration similarly to Data and Page request.
Sends sort, group, search, print, export, style and other configuration settings in <Cfg>, filter setting in <Filters> and columns with Name, Width, Visible
and
(since 11.0) Spanned attributes in <LeftCols>, <Cols>, <RightCols>
and
(since 12.1) hidden fixed and space rows in HiddenRows attribute.
Config (since 13.0)
Sends grid configuration that is not related to data.
Sends print, export, style and other configuration settings in <Cfg>.
Expanded (since 6.7)
Sends ids of all expanded rows in <Cfg
Expanded/> attribute, comma separated.
Hidden (since 12.1)
Sends ids of all hidden rows in <Cfg
HiddenRows/> 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.
AutoCols (since 12.0)
Uploads actual count of all indexed columns (with
HasIndex set) in Cfg
AutoCols attribute.
Use instead of
Settings to save just column count, not their attributes.
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>, <MenuColumns>, <MenuPrint>, <MenuExport>, <Pager>, <Actions> tags, sends all attributes of these tags.
Lang
Adds <Lang> tag, sends all texts and format settings.
upd 12.0 <treegrid,bdo> string[ ]
Upload_Flags
Various flags for extended control of uploading, comma separated list of keywords. It is case insensitive.
For example
Upload_Flags="defaults,noio"
| Index | (Since 12.0) Sends row index (RowIndex) in row id attribute and uses column index (ColIndex) instead of column Name, for Upload_Type="Cells,Body,Data,All". |
| EditAttrs | (Since 12.0) Sends all EditAttrs cell attributes like if they were listed in Upload_Attrs. For Upload_Type="Changes,Cells,Body,Data,All" |
| NoEmpty | (Since 12.0) Does not send rows without any attribute set. For Upload_Type="Cells,Body,Data,All" |
| Defaults | Sends also default values (from <D> tag) in rows if the row attribute value is null, for Upload_Type="Changes,Selected,Cells,Body,Data,All" |
| AllCols | Sends all column values in rows, including calculated cells, for Upload_Type = "Changes,Selected,Cells,Body,Data,All" |
| NoGantt | (Since 12.0) Does not send the Gantt column attributes, for Upload_Type = "Cells,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. |
| NewId | (Since 9.1) Sends all changes in row id in NewId attribute. For Upload_Type="Changes" and <Cfg> FullId or IdNames set.
All attributes referring the id like Parent or Next always contain the original id, not the NewId. The NewId is set to row id attribute after the changes are accepted. |
| Accepted | Does not send deleted rows and does not send state attributes Added, Moved and Changed, for Upload_Type="Cells,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! |
upd 11.0 <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).
(Since 11.0) If the attribute name starts with '*', it is replaced by all column names to be the attribute uploaded for all cells.
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.
chg 6.0 upd 6.6 <treegrid,bdo> string
Upload_Format
["Internal"]
If set to "DTD", the uploaded XML will be in
DTD format instead of the Internal.
If set to "JSON", the uploaded data will be JSON string.
Used for uploading data or for request, input data format is always automatically recognized.
upd 8.1 <treegrid,bdo> int
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 & < >).
For
1 data are uploaded as XML without any change.
For
2 (since 8.1) are uploaded data encoded to JSON string (& and <,> are replaced by \u0026, \u003C, \u003E).
To upload data in JSON format, set Upload_Format="JSON".
<treegrid,bdo> bool
Upload_Sync
Sets synchronous upload for AJAX communication.
The grid is disabled during upload and waits for server response.
new 6.4 upd 10.0 <Cfg> int
SaveOrder
[0]
If set to
1 and uploads all changes in <Changes> tag, it uploads them in the exact order they happened.
If set to
2 (since 10.0) it also separates all changes in one row.
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, except SaveOrder is
2.
Undeleted deleted row is ignored. Deleted added row is ignored.
All changes done in row immediately deleted after (without changing other row) are ignored, except SaveOrder is
2.
All undone or redone changes are taken as new changes.
new 9.0 upd 9.2 <Cfg> type
CalculatedChanges
[0]
If set to
1, it marks as changed all changed calculated cells and rows.
(Since 9.2) If set to
2, it marks as changed also the cell calculated for first time if resulted to different value.
(Since 9.1) It can be set to comma separated list of columns to affect only these columns. Cannot be set by API to this list.
In the first cell calculation it stores the calculated value. If some next calculation returns different result the stored one, it marks the cell changed.
If the next calculation returns the same result as the first stored result, the changed flag is cleared.
It will also upload these changes to server.
chg 6.0 <Cfg> type
DateStrings
[0/1]
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.
upd 11.0 <I> int
NoUpload
[0/1]
If set to
1, ignores changes in this row and does not upload them to server. Often set with also
NoColorState.
If set to
1, it also does
not save undo for changed cells except the cell has set
Undo='1'.
(Since 11.0) If set to
2, it works like
1 and if the row contains some pending changes, they are not accepted after save.
Default value is
0 for data rows and
1 for space rows and group rows.
Filter row has always set
1.
new 11.0 <C> int
NoUpload
[0/1]
If the column or its cells will be uploaded to server.
If set to
1, it does
not upload this column cells when all cells for the row are uploaded. It is also removed from
Upload_Attrs items with *.
If set to
2, it is also
not uploaded in
Upload_Type "Settings" and "Cols".
Default value is
0 for all columns except Gantt and Panel that is
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 changes are 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.
new 6.0 API event string
OnUpload
(TGrid grid, string xml, TRow row, bool autoupdate)
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.
upd 11.0 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 or JSON according to
Source.Upload.Format,
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.
Uploaded files in File type are not sent in the XML, but apart like the standard <input type="file"> values.
<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.
NewId - it is set to new id if the row id will be changed after save. For IdNames or FullId settings changes. Set only when
Upload_Flags='NewId'
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>