Populating Cascading DropdownBox Controls Using the Client-side Data Cache
Description
Individual DropdownBox controls can be populated using the Client-side Data Cache easily using the client-side-data-cache:cacheItemName(displayDataColumn,storedValueColumn) directive. However, this method does not work for cascading DropdownBoxes.
Overview
A cascading DropdownBox is a DropdownBox that is filtered based on the selected value in a parent DropdownBox control. For example, filtering a DropdownBox of cities based on a selected state. In connected applications, this is easily accomplished by configuring the child control (the DropdownBox whose choices are filtered based on the value of another control) to use a dynamic data source with Cascading choices.
In an offline application, however, this approach doesn't work because the child DropdownBox is populated by making an Ajax Callback to the application server to generate the list of choices. DropdownBoxes in offline applications can be populated from the Client-side Data Cache. The Client-side Data Cache can include items that are dynamically populated from a data source. The data is stored locally, allowing for offline access. You can also recompute the Client-side Data Cache item when a connection is available. This gives you the ability to update lists that may change over time.
To populate a DropDownBox using the Client-side Data Cache, the following directive is used:
client-side-data-cache:cacheItemName(displayDataColumn,storedValueColumn)
While this option allows you to populate the control offline, it doesn't support the filtering required to create cascading DropdownBoxes.
Implementing Cascading DropdownBoxes with the Client-side Data Cache
To create cascading DropdownBoxes in an offline application, the Client-side Data Cache can be used in combination with some JavaScript. This is done as follows:
Define your Client-side Data Cache items.
Create two or more DropdownBoxes with temporary static data values.
Implement JavaScript functions that will populate the DropDownBoxes.
Call the JavaScript function to populate the child DropDownBox to the onChange event for the DropDownBox that contains the filter value.
In the example of a city control filtered on the value in a state, two functions are created: one to populate the state control, a second to populate the city. The function to populate the state control is shown below. The function reads the data from a Client-side Data Cache item called "country" that is populated from a SQL Database. This function is called in the onRenderComplete client-side event for the UX Component to populate the control:
function populateCountry() {
var _onOffline = function() { };
var _onServerNotAvailable = function() { ;};
var _onSuccess = function(data) {
var arr = [''];
for(var i = 0; i < data.length; i++) {
arr.push(data[i].Country);
}
{dialog.Object}.populateDropdownBox('COUNTRY',arr,true);
};
var _onFail = function() { ;};
var _filter = '';
var _order = '';
{dialog.object}.getFromDataCache('country',_onSuccess,_onFail,_filter,_order,_onOffline,_onServerNotAvailable);
}A second function is defined to populate the city field. This function takes a parameter - country - that is used to filter the list of options. The function reads the data from a Client-side Data Cache item called "city" that is also populated from a SQL Database. Cities are only added to the list of options if the country passed to the function matches the country in the Client-side Data Cache item "city". This function is called from the onChange event for the state DropDownBox control:
function populateCity(country) {
var _onOffline = function() { };
var _onServerNotAvailable = function() { ;};
var _onSuccess = function(data) {
var arr = [''];
for(var i = 0; i < data.length; i++) {
if(data[i].Country == country) {
arr.push(data[i].City);
}
}
{dialog.Object}.populateDropdownBox('CITY',arr,true);
};
var _onFail = function() { ;};
var _filter = '';
/*
NOTE: we could have set the filter here as follows:
_filter = 'data.Country == "' + country + '"';
if we did this, then we would not have had to filter the data in the _onSuccess function
*/
var _order = '';
{dialog.object}.getFromDataCache('city',_onSuccess,_onFail,_filter,_order,_onOffline,_onServerNotAvailable);
}By using this approach, cascading DropdownBoxes can be added to any offline-enabled application.
Videos
For a full details on how this is done, watch the video and example component below.
Cascading DropdownBoxes Using the Client-side Data Cache
Cascading dropdown boxes allow you to dynamically change the choices in a child dropdown box based on the selection in the parent DropdownBox. The UX component makes it very easy to define cascading DropdownBoxes. However, in applications that are designed to work offline, you cannot use the standard way of creating cascading DropdownBoxes because if you are offline you cannot make the Ajax callback to populate the child DropdownBoxes when the parent DropdownBox value is changed. However, you can still implement cascading dropdown boxes in offline applications by populating the DropdownBoxes from data in the client-side data cache.
In this video we show how data in the client-side data cache is used to create cascading DropdownBoxes.