Client-Side Data Cache
For example, you might define a client-side data cache with these items:
For each item in the data cache you specify the server side query that generates the JSON data for the data item. For example, you might specify that the data for the 'customer' data item is obtained by executing a SQL SELECT command against a SQL Server database.
The data for the 'orders' data item might be obtained by executing some custom Xbasic code that returns a string of JSON data.
The data source for a data item can be:
a SQL query
- nested SQL queries
multiple nested SQL queries that return complex JSON data (with nested arrays of data). For example you might have a query for all customers in Boston, with all orders and payments for each customer as a nested array and then all order details for each order as a nested array
any Xbasic code that returns data in JSON format
a static string of data in JSON format
The data in a data-item can, optionally, be saved on the client-side so that it is available when you are running the application in disconnected mode. When you choose to save the data on the client, you have the option of storing the data in:
a file on the device (option only applies when you are running in a PhoneGap shell)
The amount of data that can be stored in local storage is limited. If you store data in a file on the device you will be able to store significantly more data than would be possible in local storage.
You can specify that the data in a data-item should be 'delayed'. This means that when the UX is initially rendered, the query for the data item is not performed and no data is initially sent to the client. Only when the user executes an explicit command to 'refresh' the data item will an Ajax callback to the server be made and then the data item query is performed and the data are sent to the client.
If you have specified that the data in a data item should be persisted to Local Storage, there is no way of knowing, at the time the query to get the data for the data item is performed, if the data that is returned to the client will actually be able to be stored in Local Storage - because there is not enough available space in Local Storage. Therefore, when you specify that a data item should be stored on the client side you can also specify an event handler that will get fired if the data could not be successfully persisted to Local Storage. This will allow you to display some UI to inform the user to enter more selective search criteria for the query that returns the data for the data item.
To define a client-side data cache, you open the Client-side Data Cache Editor. There are two ways to open the editor. You can use the dropdown menu by clicking the Menu button, as shown below:
Or, you can click the smart-field for the 'Client-side data cache' property on the Properties pane in the UX builder
The Client-side Data Cache editor, shown in the image below, shows the names of data items in the Data Cache. The dialog show summary information about each data item.
To edit an item in the Data Cache, click the 'Edit item' button, or double click on the item in the list. This will open the Data Item editor.
For each item you can specify:
- Item type
specify how the data for the data item are obtained. The choices are SQL Query, Nested SQL Query, Static Data and Xbasic
- Delay query until explicit refresh
specify if the data in the data item should only be computed after the user has issued an explicit 'refresh' command. IMPORTANT: If you want to persist the data in a data item to a file or to Local Storage, then this option must be checked.
- Security groups
specify the security groups for this data item. If the user is not logged in an a member of one of the specified security groups, the data in the data item will be empty.
- Server-side enable expression
specify a server-side expression (typically involving session variables). If this expression evaluates to false, the data in the data item will be empty.
If the Delay query until explicit refresh property has been checked, the dialog shows additional properties that allow you to specify that the data item should be stored on the device.
The options for Store where are:
- Local Storage
stored in a file on the device. This will only work if the UX is running in a PhoneGap shell. (Files are downloaded to a folder called '__AADataCache' on the device)
If the UX is running in a PhoneGap shell, the data are stored in a file on the device, otherwise, data are stored in Local Storage.
When Store data on device option is checked you can specify a Maximum payload size property. This is the maximum size (in bytes) that a query is allowed to return. If you specify the default value of -1 there is no maximum. This property is designed to allow you to protect against the user trying to download too much data to the device. When the
If any of the data items in your Client-side Data Cache are configured to store data in the file system on the device then you can set additional settings in the Other Settings tab of the Client-side Data Cache editor.
These settings control whether a progress bar is shown while the device is downloading the data from the server to be stored in files on the device.
If you are storing large amounts of data on the device you will generally want to show the user a progress bar so that they know that something is happening.
You can specify the color and width of the progress bar and you can also specify a placeholder or an explicit element id for the position of the progress indicator. Say for example, and element with an ID of 'progress1' and you want to display the progress indicator in this element, you specify the Placheholder for progress indicator as element:progress1
- Before file download begins
This event fires after the Ajax callback to get the data for the data items that are being refreshed has completed, but before the device actually starts downloading data.
The use case for the Before file download begins event is as follows:
Say you have defined a Client-side data cache with a large number of data items, (or a few data items, some of which return a large amount of data.) The Ajax callback to refresh all data items will take some time on the server to complete. While the server is busy performing the queries to get the data in the data items, the user has no indication that anything is happening. So, it is likely that you will want to display a wait.. dialog when the user clicks a button to refresh the data in the data items (which triggers the Ajax callback to the server). Once the server has obtained all of the data it sends a response back to the client telling the client to start downloading the data. At this point the progress indicator will start moving, giving feedback to the user. The Before file download begins event will allow you to dismiss the wait... dialog (since it is no longer needed -- the user can now watch the progress indicator).