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.
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.
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
.
Using the Client Data¶
Modifying the Client Data in the Rule¶
You can retrieve ClientData
object using the ClientAPI getClientData
API.
//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
let pageClientData = pageProxy.getClientData();
// Simple value assignment.
pageClientData.CustomPropertyA = "Custom A";
// Or a more complex assignment.
pageClientData.CustomPropertyB = {
"MoreComplexProperty" : {
"Prop1" : "Prop One",
},
"AnArray" : [
{
"NameProp" : "A Name",
"AddressProp": "A Address",
},
{
"NameProp" : "B Name",
"AddressProp": "B Address",
},
{
"NameProp" : "C Name",
"AddressProp": "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.
Accessing the Client Data in the Rule¶
If the rule is executed in the same page's context, you can call ClientAPI.getClientData
function:
// Assuming this rule is executed in MyListPage's context
export default function GetClientData(context) {
let pageProxy = context.getPageProxy();
let pageClientData = pageProxy.getClientData();
//Should alert "Custom A"
alert(pageClientData.CustomPropertyA);
//Should alert "Prop One"
alert(pageClientData.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) {
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 ClientData.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": "{#Page:MyListPage/#ClientData/CustomPropertyB/AnArray}"
}]
}]
}