Changing data from server

TreeGrid documentation

XML structure with downloaded changes

Data sent from server to grid. It is generated by server script.
Used to change the rows and their cells one by one from server side.
Used when downloading changes done on server after uploading (from Upload source) or checking for updates (from Check source) or downloading cell (from Cell source).
Used as response from data sources Upload, Check, Cell.

Only these row attributes are supported:
Deleted, Added, Moved, Changed, Parent, Next, Prev
Def, Color, AlternateColor, Class
CanEdit, CanFocus, CanDelete, CanSelect, CanExpand
Visible, Selected, Expanded, Menu
Calculated, CalcOrder

Only these cell attributes are supported:
value
Class, Color, HtmlPrefix, HtmlPostfix, Visible
CanEdit, CanFocus
Type, Range, Format, EditFormat, ExportFormat, EditMask, ResultMask, Size
Button, ButtonText, Defaults, Suggest, SuggestType,
Enum, EditEnum, EnumKeys, IntFormat, Related Refresh, Clear,
Tip, ToolTip, Error, Selected, Formula, Menu, CopyTo

Since 12.0 also attributes set in EditAttrs are supported

To change id attribute of existing row, return it in NewId attribute.
chg 9.0 upd 13.0 <Changes> int

Update

[1]
What to update after rows are changed/added/deleted/moved. Binary array.
1.bit (&1) - accepts row changes. The row is displayed as unchanged (all the change flags are removed, Deleted rows are removed).
Since 9.0 for Update=1 it does not accept other pending changes in the row, use Update=17 to do it.
2.bit (&2) - reserved (since 9.0 it always recalculates the rows)
3.bit (&4) - filter row
4.bit (&8) - search row (only Select or Mark actions)
5.bit (&16) - accept all pending changes before processing the <Changes> tag.
Use this setting in Upload_Response to accept the old changes and create new not saved changes.
The response should return also return negative <IO Result/> to not accept changes later.
6.bit (&32) - (new 9.3) does not refresh the change cell(s). Usable for changing edited cell from server side.
7.bit (&64) - (new 12.0) searches updated row id against RowIndex instead of row id.
8.bit (&128) - (new 12.0) adds new pages due AutoPages if the updated row does not exist.
9.bit (&256) - (new 13.0) animates all changes done from server side, see Animations for server side changes.
new 9.0 <Cfg> int

ChangesUpdate

[1]
Default value for Update used if <Changes Update/> is not set.
It can be used also in JSON format, because the <Changes Update/>attribute is not available in JSON.
<I> string

id

Both letters lowercase!
Unique ID of the row to change or new ID for the added row.
<I> string

NewId

New id for the row when it is modified by <Changes> tag.
API event void

OnUpdateRow

(TGrid grid, TRow row, TRow update)
Called after the row is updated or added from server side.
The update is virtual row with the changes applied to the row. The update is a node from <Changes> tag.
Can be used to refresh changed row or provide some custom changes according to custom settings in the update.

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

<IO ... attributes ... /> (a server response)

<Changes Update='1' > (list of changed rows)
<I id='...' ... some row and cell attributes ... />
... More tags <I> ...
</Changes>
</Grid>

XML structure with request for a cell

Used as request sent to data source Cell.
It is used to download Defaults list dynamically from server (when set DefaultsServer='1'), before the list is expanded.
It is used to download cell settings dynamically from server (when set EditServer='1'), before it is edited.
It is used to download Suggest list dynamically from server (when set SuggestServer='1'), whenever cell value is changed while editing it to update the suggest list.
<treegrid,bdo> string

Cell_Url

An URL to download changes from server for given cell before defined action happens.
Used to download:
Defaults list when set DefaultsServer='1'. Called before the list is displayed on click to the Defaults button.
Suggest list when set SuggestServer='1'. Called during editing whenever user changes the input value to get new list for suggested values.
Edit settings when set EditServer='1'. Called before editing started.
The XML request has format like <Grid> ... <Body><B id='row_id' Col='column_name' Val='cell_value'/></Body></Grid>
The returned data should be like other server returns in <Changes> tag.

<Grid>

<IO ... attributes with request settings ... /> (Session attribute)
<Cfg ... attributes with grid settings read from cookies ... /> 
(Sort, Group, ReSort, ReCalc, TimeZone attributes)
(SearchAction, SearchExpression, SearchType, SearchMethod, SearchDefs, SearchCols attributes)
(Focused, FocusedCol, FocusedPos attributes)
<Filters> (list of filters)
<I ... row and cell attributes ... /> (id attribute, cell values and cell Filter attributes)
... More tags <I> if more filters are in grid ...
</Filters>

<Body>
<B ... attributes identifying the cell ... /> (id attribute, Col attribute as column name, Val attribute as the cell value)
</Body>

</Grid>

Synchronizing data with server
(periodical check / server push / long polling)

With TreeGrid you can do client data synchronization with server. When server gets some change from another source (e.g. another client), TreeGrid automatically downloads the changes and updates its data on client.

Set Check_Url to server script url that will return all changes (in <Changes> tag) done on server from the last access to the Check_Url.
You can set also other attributes with Check_ prefix (like Check_Method) to control how the communication will be done.
There are two usual methods of synchronization, periodical check and long polling.

a) Periodical checking
Set Check_Interval to some interval (in seconds) and TreeGrid will periodically download changes from Check_Url.
When no changes have been done since last call, server will just return empty response.

b) Long polling (simulates server Push technology)
This method provides immediate response, the changes on server are immediately downloaded to client.
Set Check_Interval='1' and Check_Timeout='0' and TreeGrid will periodically and immediately download changes from Check_Url.
When no changes have been done since last call, server will not return anything and let the HTTP connection open until some changes arrive.
You need to permit the long polling on your server, increase the connection timeouts.
You can also set Check_Repeat="3" to resend the request automatically when server closes the connection due its timeout.
<treegrid,bdo> string

Check_Url

If set, TreeGrid periodically checks this URL and downloads changes from server (if any) and add them to TreeGrid.
<treegrid,bdo> string

Check_Timeout

[0]
How long will the grid wait for response, in seconds.
0 means forever, use especially for long polling.
<treegrid,bdo> string

Check_Interval

[5] Saved to cookies, to not load it set CheckIntervalLap='1'
How often grid will check for updates on Check_Url. In seconds.
This value can be modified by a user from configuration menu.
<treegrid,bdo> string

Check_Repeat

[3]
What to do if server returns an error.
0 - alerts the problem to user ("Synchronizing with server failed!"), and disables the Check_Interval='0'
1 - does not alert anything to user, just disables the Check_Interval='0'
2 - alerts the problem to user ("Synchronizing with server failed! Do you want to temporary disable the checking for updates?") and let him to choose.
3 - Automatically repeats the attempt
API method void

CheckForUpdates

(function Func)
Checks for updates on server at Check_Url and downloads them if any. Calls Func after finish.