Client Data¶
Every instance of UI controls in the mobile development kit has an in-memory ClientData
object that allows you to store additional information associated to that specific instance.
An application level ClientData
is also available from version 6.1.
ClientData
will be available as long as the instance page is still in the navigation stack. When the page is closed the ClientData
will be deleted.
For application level ClientData
, it will be available as long as the app is running.
You can access and modify ClientData
object via Target Path and also the getClientData()
function of the ClientAPI
class.
ClientData
object starts as an empty JavaScript object and you can populate it with any values required.
ClientData
is typically most useful in the context of a Page
or Application
.
Using the Client Data¶
Modifying the Client Data in the Rule¶
You can retrieve ClientData
object using the ClientAPI getClientData
API.
You can also call ClientAPI.getAppClientData()
API. function to access Application ClientData
.
//Assuming this function is executed in the context of a page named: "MyListPage"
export default function UpdateClientData(context) {
let pageProxy = context.getPageProxy();
// Get existing ClientData object, it is possible that it already
// contains some data that has been set previously.
// You can also use context.getAppClientData() for application level client data
let pageClientData = pageProxy.getClientData();
// Simple value assignment.
pageClientData.CustomPropertyA = "Custom A";
// Or a more complex assignment.
pageClientData.CustomPropertyB = {
"MoreComplexProperty" : {
"Prop1" : "Prop One",
}
};
let appClientData = pageProxy.getAppClientData();
// Simple value assignment.
appClientData.CustomPropertyA = "App Custom A";
// Or a more complex assignment.
appClientData.CustomPropertyB = {
"MoreComplexProperty" : {
"Prop1" : "App Prop One",
},
"AnArray" : [
{
"NameProp" : "App A Name",
"AddressProp": "App A Address",
},
{
"NameProp" : "App B Name",
"AddressProp": "App B Address",
},
{
"NameProp" : "App C Name",
"AddressProp": "App C Address",
}
]
};
}
Warning
ClientData
exists for the duration of the page's lifecycle. As long as the page is not closed the ClientData
object will be available. If you navigate back from the page to the previous page or close the page (for modal page) and the ClientData
will also be deleted. If you navigate forward to a new page, the page's ClientData
will still be accessible in the new page because the page is still in the navigation stack.
For Application ClientData
, it will exists for the duration of the app's lifecycle. If your use case require the data to be available at any time and context, you should consider to use Application ClientData
.
Accessing the Client Data in the Rule¶
If the rule is executed in the same page's context, you can call ClientAPI.getClientData()
function or ClientAPI.getAppClientData()
for Application ClientData
.
export default function GetClientData(context) {
// Assuming this rule is executed in MyListPage's context
let pageProxy = context.getPageProxy();
// Use context.getAppClientData() for application level client data
let pageClientData = pageProxy.getClientData();
//Should alert "Custom A"
alert(pageClientData.CustomPropertyA);
//Should alert "Prop One"
alert(pageClientData.CustomPropertyB.MoreComplexProperty.Prop1);
// access Application ClientData
let appClientData = context.getAppClientData();
//Should alert "App Custom A"
alert(appClientData.CustomPropertyA);
//Should alert "App Prop One"
alert(appClientData.CustomPropertyB.MoreComplexProperty.Prop1);
}
You can also use ClientAPI.evaluateTargetPath
function with Target Path to retrieve the ClientData
of any pages that still exist in the navigation stack. This is useful if the rule is executed in a different page.
// Assuming user navigated from MyListPage to MyDetailPAge and this rule is
// executed in MyDetailPage's context
export default function GetClientData(context) {
// You can also evaluate #Application/#ClientData for application's ClientData
let myListPageClientData = context.evaluateTargetPath("#Page:MyListPage/#ClientData");
//Should alert "Custom A"
alert(myListPageClientData.CustomPropertyA);
//Should alert "Prop One"
alert(myListPageClientData.CustomPropertyB.MoreComplexProperty.Prop1);
//You can also evaluate to the client data's property path directly
alert(context.evaluateTargetPath("#Page:MyListPage/#ClientData/CustomPropertyA"));
// You can also modify the ClientData of the MyListPage
// This will add a new property to MyListPage's ClientData
myListPageClientData.CustomPropertyC = "Custom C";
// This is modifying the existing property of MyListPage's ClientData
myListPageClientData.CustomPropertyB.Prop1 = "Prop One Modified";
}
Accessing the Client Data in the Metadata Definition¶
You can retrieve the content of the ClientData
through the Target Path and bind it to the metadata definition.
The following example binds MyListPage
's ClientData.CustomPropertyA
to the caption of the Object Table's header. It also bind the array Application ClientData
's CustomPropertyB.AnArray
to the Target
definition and bound its properties to the Object Cell's properties.
// Partial excerpt of MyListPage.page
{
"_Type": "Page",
"_Name": "MyListPage",
"Controls": [{
"Sections": [{
"_Type": "Section.Type.ObjectTable",
"Header": {
"Caption": "{#Page:MyListPage/#ClientData/CustomPropertyA}"
},
"ObjectCell": {
"Title":"{NameProp}",
"Subhead":"{AddressProp}"
},
"Target": "{#Application/#ClientData/CustomPropertyB/AnArray}"
}]
}]
}