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}"
    }]
  }]
}

---

Last update: August 12, 2020