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

---

Last update: November 22, 2021