TreeGrid v6.0
Paging root rows
TreeGrid can automatically split root rows to pages and display them only on demand – when the page becomes visible due scroll.
The page names and links can be displayed in large vertical pager or in simple horizontal pager row.
For other possibilities of paging see paging tutorial.
See also examples in downloadable trial, for your server side script. For server paging see “Ajax table with server paging and export” example.
This paging type can page only root rows and cannot divide children of root rows to pages. So in tree this paging can become ineffective.
For paging child rows in tree use <Cfg ChildPaging/> and / or <Cfg ChildParts/>, see paging in tree.
The paging in tree is permitted by default – opposite to root paging.
<Cfg> int Paging [0] .
Method of root paging used.
This paging is done only for root rows, it is the best for plain grids or trees with many root nodes.
0 No paging
All rows are in one page, pager cannot be visible. All rows are rendered on start. This means slow start and fast use.
It is good for small grids, up to about 1000 rows in root.
1 Show all
Pages are automatically created, but all are rendered on start.
For AllPages = 1 it renders all pages on start, but asynchronously and also pager components can be shown and used.
For AllPages = 0 is the same as 2 – Client paging.
It is good for medium grids, 250 – 1000 rows in root, to let users to easy navigate between parts in grid.
It can be used also to avoid browser “Slow script” message when rendering too many rows without paging.
2 Client paging (auto – fully done by TreeGrid)
Pages are automatically created
For AllPages = 1 is page rendered only when it is visible in window by scrolling.
For AllPages = 0 is page rendered immediately, but it is visible only one page at a time and after switch to another page, the body is re-rendered.
It is good for large grids up to 10 000 rows. All functions still work offline, include sorting, filtering, grouping, searching and calculations.
The client paging does not require any server side support.
3 Server paging (load – done by server )
Pages are created by server and TreeGrid downloads only page(s) being displayed.
The server is responsible for sending data for requested page and also for sorting, filtering, grouping, searching and aggregate calculation.
Calculations are still possible offline on client, but must be prepared on server.
It is good for very large grids, with more then 10 000 rows or for grids with special relations or grids need to be online.
The server paging requires a lot of your code on server side. To simplify this task you can use TreeGrid.dll/so.
For more information see server paging.
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.
Server paging cannot be used with Gantt chart.
<Cfg> bool AllPages [1] .
Paging display mode
0 Shows one page at a time and switches to pages only by pager click or by pressing PageUp / PageDown key.
1 Shows all pages in grid at once and renders pages on demand, when they are displayed by scrolling.
<Cfg> int PageLength [20] .
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 is this parameter used to set count of rows in page.
It is also possible to change it dynamically by API, but after change must be called grid.CreatePages(); grid.Render();
<Cfg> int PageTime [200] .
How long (in ms) must be page visible (by scroll) before it loads data or renders (for AllPages=1).
<Cfg> int MaxPages [20] new 6.0 .
Maximum rendered root pages in grid, only for AllPages = ‘1’ and Paging >= 2.
When grid contains more rendered pages, the pages longer not accessed are cleared (only in HTML, pages data are not affected).
Used to not slow down the browser when too many HTML tags are displayed.
For large pages you can lower this value.
The actually displayed pages are never cleared.
Set it to 0 to disable clearing pages.
<Cfg> int PageWindowAdd [0] new 6.7 .
Increase this value to load and render the pages sooner than they are shown.
How many pixels before or after page can remain, before it is rendered or loaded.
By default (for 0) is page rendered after it is at least partially shown.
Remember, when scrolling grid, the pages are rendered after the scrolling finishes, regardless on this value.
The right side pager is defined by <Pager> tag, placed directly to <Grid>...<Pager/>...</Grid>.
<Cfg> bool NoPager [0] .
If set to 1, grid does not render pager. The pager cannot be shown by user. Also does not pre-calculate page names.
TreeGrid server does not generate page names and does not send page names to client.
<Pager> bool Visible [1] Saved to cookies, to avoid it, set <Pager VisibleLap=’1’/> .
If pager is visible. Pager can be visible only if Cfg.Paging > 0 and Cfg.NoPager = 0.
A user can select pager visibility from configuration menu (except is set CanHide=’0’).
<Pager> bool CanHide [0] .
If pager is displayed in columns menu and can be hidden or displayed by a user from this menu.
If set to 1, the pager can be also hidden automatically if there is no room for it, to preserve displaying “Too small extents” message.
This attribute does not affect displaying and hiding pager from configuration menu.
<Pager> string Caption .
Pager header caption.
<Pager> int Width [100] Saved to cookies, to avoid it, set <Pager WidthLap=’1’/> .
Pager width in pixels. A user can resize the pager by dragging its right side, unless it has CanResize=’0’.
<Pager> int MinWidth [20] .
Minimal width of pager in pixels. This restriction is applied when a user resizes the pager or the pager is resized automatically when main tag width is too small.
<Pager> bool CanResize .
If pager can be resized by a user.
If set to 1, pager can also be resized if there is no room for it, to preserver displaying “Too small extents” message.
<Pager> int MaxColumns [3] .
Maximum of sorting columns to be listed in page names, can be set to 0 – 3.
If set to 0, the pages are always named “Page” + index.
<Pager> bool Hover [1] .
If page will be highlighted under mouse cursor
<Cell> string PageNameValue .
Cell value used for creating page names in right side pager, see also OnGetPageNameValue event.
API event string OnGetPageNameValue (TGrid grid, TRow row, string col, string val) .
Called to get value used for creating page names in right side pager val is predefined value, return val or new value.
API event void OnSetPageName (TGrid grid, TRow page) .
Called when are being (re)generated page names for right side pager after sorting or grouping.
page is given page, read and set its properties page.Name (HTML, page name displayed in pager) and page.Title (text, tooltip for page item on pager).
API method void UpdatePager ( ) .
Re-renders pager
API variable object Pager .
Pager settings, from XML node <Pager>.
<Actions> ScrollPager Mouse dragging action, only for OnDragPager event new 7.0 .
Starts scrolling right side pager. Only for touchpads (e.g. on iPad).
By default is the action attached to OnDrag2Pager for scrolling with two fingers.
<Space cell> string Type = “Pager” .
Displays control buttons PagerFirst, PagerPrevious, PagerNext, PagerLast and editable cell with page number and number of pages named PagerEdit.
This cell is replaced by the mentioned buttons and the editable cell and no longer exists for API.
You can set also attributes of the new cells, for example PagerEditWidth=’100’ or PagerNextOnClick=’MyActionNext()’
Due its internal implementation, the Pager Type cell is available only in Extended API.
<Space cell> string Type = “Pages” .
Displays all page numbers as links to the pages. Displays horizontal scrollbar if required.
You can set cell attribute RelWidth=’1’ to show the cell on the whole row.
You can set also cell attribute Wrap=’1’ to not show the horizontal scrollbar.
<Space cell> int Count [0] new 7.0 .
Maximal count of page links displayed in Pages type cell.
The Pages type cell displays actual page + up to Count/2-1 links before actual page + up to Count/2 links after actual page + first page + last page + links for Step and Step2.
<Space cell> int[] Step new 7.0 .
For Pages type cell. It contains one or more comma separated values to display only some page links outside the Count range.
For example for Step=’10’ it displays pages 10, 20, 30, ...
For example for page 254 Count=’10’ Step=’10,100’ it displays pages 1, 100,200,210,220,230,240, 250,251,252,253,254,255,256,257,258,259,260, 270,280,290,300,400,500,600,...
When set cell attribute Wrap=’2’ the steps are displayed on own lines, the pager will be displayed on three lines. Otherwise the step links are separated by space.
Remember, when used Step the count of links often changes when changes active page and the pager height can change too. You should set row Height attribute to maximal expected height of the pager to avoid grid flickering.
API event string OnGetPageNumber (TGrid grid, int number) new 7.0 .
Called for Pages type for every page number to get the html displayed in the link for the page.
The number is displayed for the page. It starts from 1, so it is bigger by 1 than the related page index.
To get page object call grid.GetPage(number-1);
API method int GetPageNum (TRow page) .
Returns position of page (page index) inside body, from 0.
API method TRow GetPage (int num) .
Returns page object by page index (from 0).
API method TRow GetRowPage (TRow row) .
Returns root page inside that row is placed.
API method int GetPagePos (TRow row) .
Returns row’s position in its root page. It counts only visible rows.
In tree it counts all rows above the row inside the page.
API method TRow PagePosToRow (TRow page, int pos) .
Returns row on given position on page. It counts only visible rows. It is only for loaded pages (State>2).
In tree it counts all visible expanded rows within the tree.
API method void GoToPage (TRow page) .
Scrolls or moves to given page. To get page object by index use GetPage method.
Moves actual focus to appropriate row in the page (e.g. if the third row on the actual page was focused, the third row on the new page become focused).
API event bool OnGoToPage (TGrid grid, TRow page, int pagepos) .
Called when grid displays another page. Return true to cancel change.
page is page (<B> tag) which will be changed to, pagepos is this page position inside body, from 0.
Called from GoToPage method.
It is called when user clicks page link on pager.
It is not called when a user scrolls or focuses to new page.
API method void GoToNextPage ( ) .
Scrolls or moves to the next page. Moves actual focus to appropriate row in the page.
If you call this function from external button onclick, you should cancel the event by adding CancelEvent (event) to your handler or use StaticCursor=’1’ to preserve grid from loosing focus.
API method void GoToPrevPage ( ) .
Scrolls or moves to previous page. Moves actual focus to appropriate row in the page.
If you call this function from external button onclick, you should cancel the event by adding CancelEvent (event) to your handler or use StaticCursor=’1’ to preserve grid from loosing focus.
API method void ShowPages ( ) .
Starts loading and rendering displayed pages. Asynchronous.
Call this method if pages are not rendered automatically when you do some unusual changes in grid.
API method void CreatePages ( ) .
Re-creates pages. After call must be called Render to re-render the grid.
Useful when PageLength was changed by API.
API method TRow AddPage (string name, string xml, int count) .
Adds new page to the end of pages.
name is page name in pager, can contain HTML code.
xml is xml content for page, it can contain only rows like “<I A=’10’/><I A=’20’/>”.
For server paging (Paging=3) xml can be null and data for page will be loaded from server, in this case count is supposed count of rows on page.
API event void OnRenderPageStart (TGrid grid, TRow row) .
Called before rendering of the root page or child page started rendering.
When used child paging (<Cfg ChildPaging), this event is fired before start of rendering children when a parent row is being expanded.
API event void OnRenderPageFinish (TGrid grid, TRow row) .
Called after the root page or child page is fully rendered and ready.
When used child paging (<Cfg ChildPaging), this event is fired after children are rendered when a parent row is being expanded.
API method void RefreshPage (TRow page, bool always = 0) .
Re-renders page or row’s children. For always = 1 re-renders the page also if it is not visible due scroll or expand state.
<Actions> Repaint Not attached to any event .
Refreshes pages, when too many pages are displayed, the grid can slow down
<Actions> RenderPages Attached to event OnClickButtonRepaint new 7.0 .
Switches for Paging, ColPaging and ChildParts between value 1 and 2.
If any of the attribute is 2, it switches to 1 and renders all not yet rendered pages.
If all attributes are 1, it switches to 2 and clears all unused pages according to the MaxPages, MaxColPages and MaxChildParts settings.