List Virtualization
Description
List Virtualization is similar to the Pagination option that appears in the List Builder's Data Source Pane, except that list virtualization occurs on the client-side where data pagination appears on the server-side.
Discussion
If you are populating a List with a large amount of data, it is strongly recommended that you turn on Virtualization. With virtualization turned on, populating a List with a large amount of data is substantially faster than populating the List with virtualization turned off.
Normally, when a List control is populated, the HTML for all of the rows in the List is rendered. If the list only has a few rows (say 200 rows), there is no noticeable delay while the List is populated.
However, if the List has a lot of rows (thousands of rows), there will be a noticeable delay while the List is populated. A large amount of memory will also be consumed by the List. On a mobile device where memory is limited, the amount of memory consumed by the List could be a problem.
Whe a list is virtualized, HTML is only generated to render the visible list rows plus additional rows above and below what is shown on the screen. The number of rows rendered in the List is called the 'page' size.
When the user scrolls the List and hits a page boundary, the user can tap on a Next or Previous button (or optionally use a pull/release gesture) to populate the List with the next or previous page of data. It is important to recognize that tapping the Next or Previous button does not trigger an Ajax callback. It is simply rendering the next or previous page of data using the data that has already been loaded into the List and is in memory. Therefore, the time taken to populate the next or previous page is practically instantaneous.
The advantage of virtualizing the List is that you can dramatically reduce the time taken to load large Lists and you can reduce the memory footprint of the List.
Turning on List Virtualization
In the UX Builder open the UX Controls page.
Under the Data Controls sublist on the Controls page and scroll down to the [List] control option. Double click on the [List] control option.
The New Control dialog will open. Click OK to add the control to the component.
In the component work area double click on the new List control.
The List Builder Dialog will open. Create a Data Source for the List control.
Click on the List Properties tab. Find the List Virtualization properties.
Set the Virtualization type property shown below to 'Dynamic'.
Once you do this, several additional properties will be shown
List Virtualization Properties
Virtualization type
The options for the Virtualization type property are None and Dynamic. With 'None' all items in the list are rendered. With 'Dynamic' only a fixed number of items are rendered at any given time. Items not initially rendered will be dynamically rendered as the user scrolls them into view. Use the 'Dynamic' option if your List has a very large number of rows and you want to minimize the time taken to render the List when it is initially displayed and also minimize the amount of memory consumed by the List.
- Option
- Description
- None
Disables List virtualization.
- Dynamic
Enables List virtualization.
onNavigate event behavior
The onNavigate event's behavior is different depending on whether the list is virtualized or not. If virtualization is disabled, the onNavigate event fires when the List is scrolled. If virtualization is enabled, the onNavigate event fires when the user navigates to a new page of records.
The onNavigate event behavior property can be used to make the behavior consistent regardless of the virtualization option. The onNavigate event behavior property can be set to 'Navigate', 'Scroll' or 'Both'. When set to 'Scroll', the behavior is the same as a non-virtualized list.
- Option
- Description
- Navigate
The onNavigate event will be fired when the user navigates to a new page of records.
- Scroll
The onNavigate event will be fired when the user scrolls the List.
- Both
The onNavigate event will be fired when the user navigates to a new page of records or when the List is scrolled.
Size
The size property defines the 'page' size - the number of rows of data that should be rendered. This should typically be a multiple of the number of rows in the viewport. For example, say that your List can display 20 rows of data at a time, you might set the size to (say) 100 so that the user can scroll a fair amount before hitting the page boundary.
When you reach a page boundary (either on top or bottom of the page), there are 'Next' and 'Previous' buttons to get the next logical 'page' of data. The user can either tap on the Next/Previous button, or use a pull/release action to fetch the next page of data.
Max size
This is an advanced optional setting that can be used to specify a type of 'hybrid' virtualization. By default, this property is set to 0, which means that the number of rows that the List renders is always equal to the 'page' size. When you hit a page boundary, the current page is memory is replaced by the next page that is loaded.
However, if you set the Max size to -1 (which indicates that the max size is equal to the number of rows in the List), or some positive number that is greater than the size property, then when you are navigating forward and you hit a page boundary, the next page of data is automatically rendered (without requiring the user to tap the Next button). The number of rows in memory continues to grow as the user scrolls down in the List. In other words, the memory consumed by the List is initially very small (as only a single page of data are rendered) and the time taken to render the List is optimized (again, because only a single page of data are rendered), but as the user scrolls, the number of rendered rows in the List continue to grow and more memory is consumed. When the 'max size' is reached, then the user will then have to use the 'Next' button to continue to viewing additional records.
Offset
When you hit a page boundary, and click the Next/Previous button, the 'offset' indicates the number of rows from the page that is being discarded that should be included in the new view. If this number is less than the number of rows in the viewport, the List will appear to 'jump' when you navigate to a new page. It is recommended that this value be set to a minimum of the number or records that can be seen in the viewport at one time so that when the user taps the Next/Previous button, the scroll position of the List does not change. It is recommended that this number be no more than half of the 'page size'. The larger the number, the more rows the user can scroll backwards before hitting the Next/Previous buttons.
Navigate on pull
Allows the user to pull/release to navigate (in addition to tapping on the Next/Previous buttons).
Pull size
Number of pixels before the 'pull/release' gesture is recognized as a 'navigate' action. This property is only available if Navigate on pull is checked.
Previous button HTML
The HTML text shown on the previous button. The previous button is used to navigate to the previous page of records in the List.
Previous button classname
One or more classes applied to the HTML for the previous button. The classes can be defined in an external style sheet, in the CSS property for the UX Component, or in the local CSS for the List control.
Previous button pressed classname
One or more classes applied to the HTML for the previous button when it is pressed. The class(es) can be defined in an external style sheet, in the CSS property for the UX Component, or in the local CSS for the List control.
Next button HTML
The HTML text shown on the next button. The next button is used to navigate to the next page of records in the List.
Next button classname
One or more classes applied to the HTML for the next button. The classes can be defined in an external style sheet, in the CSS property for the UX Component, or in the local CSS for the List control.
Next button pressed classname
One or more classes applied to the HTML for the next button when it is pressed. The class(es) can be defined in an external style sheet, in the CSS property for the UX Component, or in the local CSS for the List control.
See Also