TreeGrid v6.0

Changing data from server

TreeGrid documentation index

 

 

 

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

 

To change id attribute of existing row, return it in NewId attribute.

 

<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)

2.bit (&2) – (re) calculate row. If the row or cell got changes in Formula, Calculated or CalcOrder it is recalculated always.

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.

 

<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.