{dialog.object}refreshListData Method
Syntax
Arguments
- UXListName
The Id of the List control or a comma delimited list of List Ids to refresh.
- options
Optional. A JSON object with the following optional properties:
- Option
- Description
- keepFocusOnCurrentSelection
A true/false value. After the List is refreshed, should the current row still have focus, or should focus be on the first row fo the List. Default value is true.
- setFocusToValue
Specify the value in the List that you want to have focus.
- refreshDependentLists
A true/false value. If the List has child Lists, defines whether the child Lists should also be refreshed.
- onlyRefreshDependentLists
A true/false value. If the List has child Lists, defines whether only the children Lists should be refreshed (and not refreshing this List.)
- mode
Specifies the type of refresh. Can be 'incremental' or 'full'.
Description
Refreshes data in a List control.
Discussion
Refreshes a List control. If the List is based on a SQL query, a callback is made to re-execute the query. Contrast this with the <listObject>.refresh() method, which simply redraws the List using the existing List data.
If you want to refresh multiple Lists on a single Ajax callback, you can pass a comma delimited list of List Ids.
{dialog.object}.refreshListData('MYLIST1');
//refresh multiple lists in the same ajax callback
{dialog.object}.refreshListData('MYLIST1,MYLIST2');
//refresh a List and set focus to a particular value in the List
var options = {};
options.setFocusToValue = 'ALFKI';
{dialog.object}.refreshListData('MYLIST1',options);Incremental Refresh Option
The .refreshListData() method makes an Ajax callback to refresh the data shown in a List control. By default, the Ajax callback computes a new set of data to show in the List, sends that data back to the client, completely repopulating the List.
If the List has any unsynchronized edits you should not execute the .refreshListData() method to perform a full refresh, or else your unsynchronized edits will be lost. Performing an incremental refresh will preserve unsynchronized edits.
To test if a list has unsynchronized edits you can use the List's .listIsDirty() method. For example:
var lObj = {dialog.object}.getControl('list1');
var flagDirty = lObj.listIsDirty();
if(!flagDirty) {
{dialog.object}.refreshListData();
}You can specify that you want to perform an 'incremental' refresh, rather than a 'full' refresh. The syntax is:
{dialog.object}.refreshListData(listId,{mode: 'incremental'});
{dialog.object}.refreshListData(listId,{mode: 'full'});If the optional second argument is omitted, a full refresh is assumed.
In the case of an 'incremental' refresh, only data for rows that have been edited or added to the database since the time the List was initially populated are sent to the client. In addition, a list of keys that have been deleted is also sent to the client. This may result in a substantially smaller payload being sent back to the client - especially if only a few rows have been edited or added. The size of the payload is important in mobile applications.
The main benefit of this option is the reduction on the response payload. There is a small cost in terms of the load placed on the server, as the server has to determine which records have changed.
Also, the payload of the initial request from the client to the server to request a refresh is slightly larger because a list of primary keys and their CRC values has to be sent to the server.