Server paging

TreeGrid documentation

Server paging for root rows (Paging='3')

For basic information about paging and client paging see Paging documentation.

Server paging is expected to use for large grids with more than 10,000 root rows.
In server paging are pages downloaded on demand when they are visible by scroll.
The server script is responsible for sending data for requested page and also for sorting, filtering, grouping, searching and aggregate calculation. This means that all the required features must be done on server side by server script.

There is available TreeGrid server DLL/SO that can be used to as support library for TreeGrid server paging - if you provide to the library the whole XML data, it will generate pages to client and will also provide all requested features like sorting, filtering, grouping and aggregate calculations.
See TreeGrid.dll/so documentation.

If you are not able to do sorting, filtering or grouping on server and you still want to use server paging, you can set OnePage attribute (and AllPages=0) to do them partially in actual page.

You can mix server and client Paging, for pages that should use client paging fill their data in body response.

Paging can be set to 3 independently of ChildPaging value.
Server paging cannot be used with Gantt chart.
To use server paging of root rows set Paging to 3.
Average count of rows in page.
For client paging there are all pages created to contain this number of rows (except the last one).
For server paging it determines height of page - it is default value of <B Count> attribute.
Exact count of rows in pages can differ due to adding or deleting rows or in last incomplete page.
Every page must contain at least one row otherwise it is deleted. Exception is when grid does not contain any row, so it contains one empty page.
In TreeGrid server DLL/SO is this parameter used to set count of rows in page.
Count of all rows in root. Used to compute Count parameter of the last page when server paging used and pages have not Count attribute set.
If set to 1, sorts, filters or groups rows only in actual page. Only when AllPages = 0 (one page visible at a time).
Bit array: 1. bit (&1) sorting, 2. bit (&2) filtering, 3. bit (&4) grouping. Set to 7 for all actions done at one page only.
Use this attribute only for server paging (Paging=3) if you are not able to do sorting, filtering or grouping on server.
If permits reloading grid if not uploaded changes are pending.
0 - no (does not allow neither reloading nor server side sorting/filtering/searching/grouping)
1 - yes, save them (only when reloading as request for server side filtering/sorting/searching/grouping, for reload by Reload button always discards changes),
2 - yes, discard changes (should be used only when changes are not saved to server at all and server paging is used)
3 - show confirmation message to user
&4 - test also selected rows (values 4,5,6,7 are related to 0,1,2,3)
Which row states are restored after reloading grid body rows. Bit array.
1. bit &1 - selected rows, 2. bit &2 - expanded / collapsed rows.
The row state is saved according to the row id, so the rows must be reloaded with the same ids.
Unique ID of the page. By this ID is page identified when downloading data for this page. Used only if Rows are not set.
If set neither id nor Rows attribute, the page is identified by attribute Pos as its position inside body. But this position can change if any page is deleted.
User string to identify the page. If set, the page is identified by this string when downloading data for this page. It can for example contain a list of row ids the page contains.
It can also be used to specify different url for every page by using Page_Url with wildcard *Rows.
Page position inside body (from 0), identifies the page, if id and Rows not set.
Name of the page, displayed in right side pager. It can contain HTML code (coded).
Title of page, displayed in pager as tool tip. It can contain HTML if set <Cfg StandardTip='0'/>
There can be predefined names according to sorting. If these are set, the Name and Title are created from them.
These names specifies the first and last value on page in sorting columns.
X is boundary = 0 - both (both values are the same in this column), 1 - top, 2 - bottom. Can be used either 0 or 1+2.
Y is sorting column 0,1,2.
There are possible combinations of XY (separated by #):
For example: Name00='blue' Name11='100' Name21='154' means that page shows all blue values from 100 to 154.
Count of rows the page contains. It specifies height of the page when it does not show rows yet. It is also result of count function in formulas.
If not set, it is used <Cfg PageLength value. Or for the last page is Count computed from <Cfg RootCount> and row count in other pages.
If any fixed or space row in grid in server paging contains some aggregate function like sum or count, the server must pre-calculate and fill all the results of these functions, because TreeGrid cannot do it on client without the page data.
For more information see aggregate functions.
For example if some fixed row contains AFormula='sum()' the all the pages should contain for example Asum='123.50'

Server communication in root paging

For server Paging you must define <treegrid/bdo Page_Url/> to download the page(s) data from.

If Paging is set to 3 (Server) TreeGrid loads actual configuration from cookies, inserts it to the request for Data (to Data_Url), sends it to server and downloads prepared pages without data. This request contains sorting, grouping, filter and search settings.
Server prepares pages - calculates, sorts, filters and groups rows and distributes rows to pages. It also sets page names and results of aggregate functions for page and column.
Server Data response contains only <Body> tag with only <B> tags with attributes, but without any child <I> tags. Some pages (<B>) can contain their rows to use client paging only for them.

When any not loaded page is displayed, TreeGrid downloads data for this page by sending the request for Page (to Page_Url). The request for page (<B> tag) contains Rows attribute of page (if was set) or id attribute (if was set) and (always) Pos attribute as page index (position from 0).
The request also contains sorting, grouping, filter and search settings, the same as when pages body was downloaded.
Server Page response contains the one requested page in <B> tag with the same identification attributes (Pos, id, Rows).

When user changes sorting, grouping, filter or search, TreeGrid reloads all data from data source Data_Url with new configuration in request for Data. And repeats loading of pages.
Re-calculations after cell change are still done on client. Calculated cells are not sent to server. Therefore server must also recalculate appropriate cells if changed values are saved to server.
If you are not able to do sorting, filtering or grouping on server and you still want to use these features, you can set OnePage attribute (and AllPages=0) to do them partially in actual page.

The data of returned page can contain also defaults (<D> tags). These defaults are added to grid layout, but should be used only for data in the page they were loaded with.

Example of request for body (grid has columns named A,B,C,D,E)
<Grid>

<Cfg Sort='C,-A' Group='P' SearchExpression='new' SearchAction='Select'/>
<Filters><I id='MyFilter' C='10' CFilter='1' E='A' AFilter='10'/></Filters>

</Grid>

Example of resulted body (grid has also one foot row: <I AFormula='sum()' CFormula='sum("D")/2+A'/>)
<Grid>

<Body>

<B Count='20' Asum='123' Dsum='312' />
<B Count='20' Asum='453' Dsum='6.5' />
<B Count='20' Asum='1297' Dsum='-142.76' />
<B Count='12' Asum='145' Dsum='349.7' />

</Body>

</Grid>

Example of request for second page (grid has columns named A,B,C,D,E)
<Grid>

<Cfg Sort='C,-A' Group='P' SearchExpression='new' SearchAction='Select'/>
<Filters><I id='MyFilter' C='10' CFilter='1' E='A' AFilter='10'/></Filters>
<Body><B Pos='1'/></Body>

</Grid>

Example of resulted second page
<Grid>

<Body>

<B Pos='1'>

<I id='xa' A='10' B='20' C='10.3' D='-4.5' E='one'/>
... 18 rows ...
<I id='xu' A='3' B='12' C='4.6' D='-3.5' E='twenty'/>

</B>

</Body>

</Grid>

Root paging in very large tables

There are few advices how to use TreeGrid for grids with more then about 10 000 root rows. It is not related to huge trees, the tree can handle unlimited count of rows.
All these advices are used only to speed up rendering and using TreeGrid, they do not concern about handling of such amount of rows, TreeGrid can handle unlimited rows count.

For grids with more than 20 000 rows always use server paging (<Cfg Paging='3'/>). Your server script must provide data for grid's pages. You can use TreeGrid server component to help you with this task. The TreeGrid server can do nearly all functions required in server paging as creating pages according to sorting and filter settings. Also pre-calculates aggregate functions. Saves changes returned from client. And more.

For grids with more than 50 000 rows use Extra short format to send list of pages. The TreeGrid server does it automatically.
If possible, use all page of the same width and don't return rows count for every page, but set <Cfg PageLength and RootCount /> attributes. The TreeGrid server does it automatically.
Also increase <Cfg PageLength/> attribute according to count of columns in your grid. For 1 - 5 columns use 100, for 5-10 use 50 and for more columns use 30.
Also use <Cfg FastPages/> attribute. Set it to value about 100. Higher value speeds up initial rendering but can slow down work with the grid and vice versa.

For grids with more than 500 000 rows and all pages visible (<Cfg AllPages='1' />) use <Cfg PageLengthDiv/> attribute to reduce page size and all grid scroll height because browsers have problems with too high scroll height.
Firefox can display only tags high up to 17 895 166 pixels => 596 505 rows with 30px height. IE has limit 21M px and Chrome has limit 33M px.
Set PageLengthDiv to average_rows_count * average_row_height / 1.5e8. For 1 000 000 rows with 30px height set it to 2.

For grids with more than 2 000 000 rows display only one page at once by using <Cfg AllPages='0' />. If you use configuration menu, set <MenuCfg ShowAllPages='0'/>. Also to suppress loading defaults for AllPages use <Cfg AllPagesLap='1'/>.
If you use TreeGrid server, remember that for such amount of rows it allocates about 400 MB memory. Of course, it does not concern client browser memory consumption; it is independent on row count.
Speeds large tables with more than 40 000 root rows.
Set it to default value of 100 to speed up rendering of large tables.
Bigger value speeds up initial rendering, but can slow down TreeGrid usage and vice versa.
Page length divider for large tables with more than 500 000 root rows (plus expanded child rows) with AllPages==1 and FastPages>0.
This divides PageLength to display smaller non rendered pages.
Set this attribute to average_rows_count * average_row_height / 1.5e8. For 1 000 000 rows with 30px height set it to 2. In this case set PageLength to be enough high, for example to 100.
This attribute is used due problems in browsers with too high tags (Firefox can display only tags high up to 17 895 166 pixels => 596 505 rows with 30px height).
If used ColPaging the limit in IE / Edge is only 5 000 000 pixels => 166 000 rows with 30px height.
In TreeGrid prior 14.0 the limit in IE / Edge is only 1 342 177.28 pixels (0x8000000/100) => 44739 rows with 30px height).

Server paging in tree (ChildPaging='3)

For basic information about paging in tree and client ChildPaging see Paging in tree documentation.

Server paging in tree (ChildPaging) downloads children from server on collapsed parent expand or (since 7.0) on scroll to already expanded parent.
It downloads children only if the row has not any children yet and it has Count attribute.
By default it downloads children only on the first expand, you can change it by RemoveCollapsed attribute.

The server script is responsible for sending data for requested page and also for aggregate calculation of children. This means that if grid uses aggregate functions like sum() or count() the children must be pre-calculated on server side by server script.
Opposite to server root paging, server does not need to care about the sorting and filtering, but still needs to provide grouping and searching (except Filter action).
There is available TreeGrid server DLL/SO that can be used to as support library for TreeGrid server paging - if you provide to the library the whole XML data, it will generate children to client and will also provide all requested aggregate calculations.
See TreeGrid.dll/so documentation.

You can mix server and client ChildPaging, for rows that download children on demand set Count attribute, for other rows just fill their children in data.

ChildPaging can be set to 3 independently of Paging value.

Since 14.0 it is possible to download only visible (due scroll) parts of immediate children, if there are many immediate children, if set ChildPageLength.
In this case the server must provide also sorting and filtering like in server root paging.
To use server paging in tree set ChildPaging to 3.
Only for ChildPaging=3. To download many immediate children in parts only for demand.
Set it to positive value to split many immediate children to sub pages to download only visible parts of the children.
If set and the parent row Count is higher than ChildPageLength + ChildPageDiff, it adds new hidden children to that parent row and these children will download the original children as their children.
If set, it automatically sets also <Cfg Paging='3' ChildParts='2'/>. If the Paging was 0, it also presets PageLength='100000' and NoPager='1'.
If set, the server code must be able to sort, filter, group, search data on server side.

The request to server contains the parent row id and Pos attribute from 0 as position of the page, e.g. <B id='XXX' Pos='0'/> for the first page of the XXX row.

For example by default ChildPageLength='0' and the row <I id='R1' Count='25'/> is sent to server one request as <Grid>...<Body><B id="R1"/></Body></Grid>.
For ChildPageLength='10' there are added 3 hidden sub children/pages as: <I id='R1'><I Def='SPage' Count='10'/><I Def='SPage' Count='10'/><I Def='SPage' Count='5'/></I> The 3 children have preset Expanded='3' Visible='0' AggChildren='1' as defined in SPage default.
To server are sent up to 3 requests to download the children for the sub pages, only if the individual page is visible due scroll. For the first page it is <Grid>...<Body><B id="R1" Pos="0"/></Body></Grid>. For the second page is Pos="1" and for the third page Pos="2".
Since 15.0 the returned parent row can contain pre-calculated summary function results for every child page named as col+func+pos, e.g. col1sum0="33".
How much must row's Count exceed the ChildPageLength to split the children to sub pages.
Set to negative value of ChildPageLength (e.g. ChildPageLength='10' ChildPageDiff='-10') to always split the children to pages, including creating one page.
If children are removed when parent row collapses.
Set it to 3, if you want to download children on every parent expand. But remember, all pending changes in rows will be discarded.
Called after the row is collapsed and its children are deleted from data, only if set <Cfg RemoveCollapsed='3'/>
How will behave changed rows on RemoveCollapsed or RemoveUnused.
0 - Don't remove changed rows and selected rows. If there is any such row, the removing is not done.
1 - Don't remove changed rows. If there is any such row, the removing is not done.
2 - Remove changed rows
3 - Save changes and remove rows immediately
4 - Save changes and wait for the server success response before removing rows.
Called if removing page containing some changed (or selected row for RemoveChanged==0)
For RemoveChanged==2 is called always.
Return new value for RemoveChanged to use - 1, 2, 3, 4
Count of not downloaded children rows the row contains. Used when ChildPaging is set to 3.
Must be set to > 0 if you want to download children from server.
It is set to null after the children are downloaded from server.
It also specifies height of the children after expand when downloading data. Set it to expected count of all children, including subchildren of expanded children to correctly calculate the row height.
Unique ID of the parent row. By this ID is the row identified when downloading its children. Used only if Rows are not set.
Page position inside children (from 0), identifies the child page when downloading row's children.
Sent along with id, used only if set ChildPageLength.
User string to identify the parent row. If set, the row is identified by this string when downloading its children. It can contain for example a list of children rows ids.
It can also be used to specify different url for every page by using Page_Url with wildcard *Rows.
If the parent row in server paging contains some aggregate function like sum or count, the server must pre-calculate and fill all the results of these functions, because TreeGrid cannot do it on client without the children.
For more information see aggregate functions.
For example if the row contains AFormula='sum()' the row should contain for example Asum='123.50'

Communication with server in ChildPaging

For server ChildPaging you must define <treegrid/bdo Page_Url/> to download the children data from.

If ChildPaging is set to 3 (Server), the communication for body is the same as for client or no paging, see data download documentation.

When user expands collapsed not yet loaded row with Count attribute, TreeGrid sends the request for Page to Page_Url. The requested row is set as <B> tag with row's attribute id. (For example: <Grid>...<Body><B id='r123'/></Body></Grid>).
The request also contains sorting, grouping, filter and search settings, the same as for root paging.
Server Page response contains the one requested page in <B> tag with the same identification attributes (id, Rows) and with content of the row's children. Server must return all immediate children and children of all expanded rows. Some of the downloaded children can be also collapsed with Count attribute to download their children on demand.

The parent row must have set the Count attribute to at least 1. It is better if Count is set to real count of immediate children the row contains + count of sub children of expanded children.

Example of request for children of row 'xy' (grid has columns named A,B,C,D,E):
<Grid>

<Cfg SortCols='C,A' SortTypes='0,1'/>
<Filters><I id='MyFilter' C='10' CFilter='1' E='A' AFilter='10'/></Filters>
<Body><B id='xy'/></Body>

</Grid>

XML Request for Data in server root paging

Used as request sent to data source Data when layout is already downloaded and grid configuration is known.
It contains session identification and grid configuration to sort, group, filter and search data on server. It contains also cursor position.
It is not sent if Data_Method="Get" - Get is default if no or client paging is used.

<Grid>
</Grid>

XML Download Data in server root paging

Data XML for server paging defines pages and optionally their rows.
It is sent from server to grid. It is generated by server script. It is usually generated from server database or by TreeGrid server DLL / SO.
Used when downloading grid for first time or reloading all data for the grid (function Reload) or reloading only body (function ReloadBody) or downloading new data for changed sorting, filtering, grouping or searching - in server paging these functions must be done on server side.

If the <B> tag contains some rows, the page will be filled by these rows and will not request to download its content.
If the <B> tag is empty it must contain Count attribute to set to count of expected rows. The page will be shown empty and will request to download its content by Page request when it will be visible by scroll.

It can also contain some parts from Layout XML, like fixed rows or configuration settings if they need to generate dynamically to let the rest of the layout to be in static file.
It can also contain configuration settings like sort, filter or group if you want to change them when reloading body.

<Grid>
</Grid>

XML Request for Page or children

Used as request sent to data source Page to get the content of the page or child page.
It contains the page identification by Pos, id or Rows attribute(s).
It also contains grid configuration to check if it is the same as it was in body request.

<Grid>
</Grid>

XML Download Page or children

Page XML contains one page definition with content for the requested page. If the XML contains more pages, all the others are ignored.

The <B> tag must have set Pos, id or Rows attribute to identify it on client as the requested page.

For server child paging some or all rows with children can have set Count attribute as the count of the expected children instead of the children themselves. The children will be downloaded on demand.

<Grid> (Root tag)
</Grid>

API for server paging and child paging

Returns sorting, grouping, filter and search settings for download request, without enclosing <Grid> tag.
format can be "internal" or "dtd"
Called when data for page or row's children are requested.
Returns true to suppress default downloading. If it does return true, must call function func(int result), where result<0 is error code or 0 for ok.
To catch and modify the data after they are loaded use OnDataReceive or OnDataGet event and test their source.Row attribute to get the page.
Called when page is downloaded and updated and is ready to render.
Downloads data of page or children of row. Sends to server request with page index or row id and sort, group, filter and search settings.
Alerts server message if any and permitted. Asynchronous function. After finish, calls function Func. function Func (int code).
Clears page data or row's children and reloads them from server.
Loads and processes the page data. The page will be fully loaded and prepared for render and rendered if it is visible (due scroll).
To catch the event the page is loaded use OnDataReceive event or since 14.0 pass callback func
Since 14.0 if render is true, it also renders the page, if it can be rendered.
Since 14.0 function func (int result) is called after the page is loaded or rendered.
Since 14.0 it can be used to load and render row children in server child paging.
For example you can write such code to download all root pages asynchronously on start:
Page or parent row state of loading / rendering its children.
0 - not yet loaded, 1 - children are loading, 2 - children are loaded, but not rendered, 3 - children are rendering, 4 - fully rendered.