You can use large data pages in your offline-enabled mobile app to improve performance. To use large data pages, you create a custom populator function, which is a JavaScript function that defines the SQL logic for loading large data page content selectively from the client store to the client clipboard. You must register a separate custom populator JavaScript function for each large data page from which a user interface control is sourced. User interface controls that support large data pages, such as dropdown lists, autocomplete, and repeating dynamic lists, use registered populator functions automatically. Do not invoke any defined JavaScript populator function manually. Instead, use the controls that use this type of populator function automatically or directly invoke the findPageAsync() method on the client cache.

You define a custom populator JavaScript function that performs some operation on the large data page by using query statements such as the following types:

• Filtering its contents
• Joining data from two separate large data pages
• Preprocessing or postprocessing the result

A custom JavaScript populator function has the following signature:

var <NAME_OF_CUSTOM_FUNCTION> = function(parametersMap, clientStore, onSuccess, onFailure)

where:

• parametersMap - Specifies the map of parameters requested by the user interface to filter the result.
• clientStore - Specifies the object that defines the runQuery() function that should be used to retrieve the data of a large data page from the client store.
• onSuccess( results ) - Specifies the callback function that is invoked as soon as the results are ready. Accepts results in the client cache format.
• onFailure( code, message ) - Specifies the callback function that is invoked when the custom populator function fails.

Within this new custom populator JavaScript function, you also have to call the clientStore.runQuery() function from the JavaScript Client Store API. This function allows you to perform a query operation on the records of the large data page. The JavaScript function has the following signature:

runQuery(query, queryParameters, targetDatapageName, onSuccess, onFailure) 

where:

• query - Specifies the SQL query using the SQLite syntax. Defines selecting records from the large data page itself or selecting from another large data page (known as "a source data page"), or joins records from several large data pages.
• queryParameters - Specifies an array of parameters in order of their appearance in the query. The types and formatting of the parameters must match the SQLite rules. The length of the array must match the number of '?' character occurrences in the query. The array will be empty if no parameters are used.
• targetDatapageName - Specifies the name of the large data page that will be populated by using this custom populator function. When you specify the target large page, the application returns the correctly formatted values as expected by the client cache. For this action to take place, all columns queried from a source data page should have their counterparts in the target data page (for example, they should be instances of the same class). Remember that both target and any source large data pages must be declared in the pyDataPageWhiteListForOffline rule, each as a separate entry.
• onSuccess( results ) - Specifies the callback function that is invoked when the query operation succeeds. The results parameter is an array of selected rows. Each row is a map where the key is a column name, and the value is the column's value for a specific row. The order is not maintained for the returned rows unless the query includes the ORDER BY clause.
• onFailure( code, message ) - Specifies a callback function that is invoked when the query operation fails.

You must correctly register the new custom populator JavaScript function with the target large data page. If the data page is sourced from other data pages, you must also provide the list of those data pages when registering. To register, use the pega.ui.ClientCache.registerLargeDatapage() JavaScript function, which has the following signature:

registerLargeDatapage(targetDatapageName, populatorFunction, sourceDatapagesList )

where:

• targetDatapageName - Specifies the name of the large data page to be populated or updated by using this custom populator function.
• populatorFunction - Specifies the name of the custom populator function to register.
• sourceDatapagesList - Specifies an array of large data page names that will be used by the custom populator function's query to construct the result. This parameter is optional and should not be specified if the target data page is the source for itself.

Sample custom populator functions

The following sample JavaScript code for a custom populator function is used to just filter a single large data page:

var myCustomPopulatorFunction = function(parametersMap, clientStore, onSuccess, onFailure) {
  var targetDatapageName = "Declare_MyDataPageName";
  var query = "SELECT * from Declare_MyDataPageName WHERE pySomething = ? AND pySomethingElse > ?"; 
  var queryParameters = [parametersMap.pySomething, parametersMap.pySomethingElse]; 
 
  clientStore.runQuery(query, queryParameters , targetDatapageName, onSuccess, onFailure); 
};
pega.u.ClientCache.registerLargeDatapage("Declare_MyDataPageName", myCustomPopulatorFunction); 

The following sample JavaScript code for a custom populator function is used to join data from two large data pages:

var myCustomPopulatorFunction = function(parametersMap, clientStore, onSuccess, onFailure) { 
  var targetDatapageName = "D_PartsForInstrument";  
  var query = "SELECT D_Part.PartNumber, D_Part.Description, D_Part.Price " + 
              "FROM D_Part, D_PartRelationship " +  
              "WHERE D_Part.PartNumber LIKE ? AND D_Part.PartNumber = D_PartRelationship.PartNumber AND D_PartRelationship.ProductCode = '?'";  
  var queryParameters = [parametersMap.pyPartNumberPattern, parametersMap.pyProductCode]; 

  clientStore.runQuery(query, queryParameters, targetDatapageName, onSuccess, onFailure);  
}; 
pega.u.ClientCache.registerLargeDatapage("D_PartsForInstrument", myCustomPopulatorFunction, ["D_Part", "D_PartRelationship"]);

The following sample JavaScript code for a custom populator function is used to preprocess parameters and postprocess the results:

var myCustomPopulatorFunction = function(parametersMap, clientStore, onSuccess, onFailure) { 
  // add pre-process work -> do something with parametersMap here. 
  var targetDatapageName = "Declare_MyDataPageName"; 
  var query = "SELECT * from Declare_MyDataPageName WHERE pySomething = ? AND pySomethingElse > ?"; 
  var queryParameters = [parametersMap.pySomething, parametersMap.pySomethingElse]; 
  var myOnSuccess = function(resultArrayOfMaps) { 
    // post-process work -> do something with resultArrayOfMaps here.  
    onSuccess(resultArrayOfMaps);  
  }; 
  clientStore.runQuery(query, queryParameters, targetDatapageName, myOnSuccess, onFailure);  
}; 
pega.u.ClientCache.registerLargeDatapage("Declare_MyDataPageName", myCustomPopulatorFunction);