Explore… the Data Model Structure

Within CommonTime Infinity, a structure called the Data Model is used to hold all data relating to an app. This includes details about the app (e.g. platform it is running on), settings required for features within the app (e.g. API details, Azure configuration, Push Notification settings) and any data captured from the user (e.g. text, photos, choices).

The Data Model is a key resource used when referencing data within the application. This is important in a range of scenarios, such as pre-populating fields, storing input and displaying images. Where possible, CommonTime Infinity provides a ‘Model Browser’ which can be used to quickly locate items within the model based on the type of data and the name of the item it is stored against.

Topics covered in this article

1. Data Model Structure
2. View the Data Model
3. Manipulate the Data Model

1. Data Model Structure

Each app has a predefined Data Model structure, with additional objects and properties added when a new page or item is included within the application. Note that items will only be listed in the model if they capture/store any data. Therefore items such as areas, buttons and titles will not appear.

The Data Model is represented by a JSON object, with all of the data held in a root-level object called ‘cti‘. Within this object there are two main objects called store and utils which contain additional properties and tools for use within the app.

1a. Store

The ‘cti.store‘ object is used to store data which is either required for the app to function or captured by an item in the app. Any data held within this section of the Data Model can be updated/referenced whilst the app is running, and persists when the app is closed and reopened.

When referencing values held in the store, the cti.store reference is normally shortened to $store. The exact method used to reference to a value depends on the item where the reference will be used. For more details, please see this documentation.

Within the store there is a wide variety of pre-populated objects which hold/capture data used in the application. Some of the most noteworthy objects include the ones noted below:

Page & Item Data

Each time a new page is added to the app, a new object is registered within the ‘pages‘ section of the Data Model. The name of this object corresponds to the name of the page, and is used to hold data which relates to items on that page within the app.

When a new item is added to a page, the corresponding object/properties will also be added to the Data Model. These are registered against the ‘Name’ of the item, with the item’s type determining what properties are added to the Data Model.

For example, where an item only stores a single value (e.g. the string entered into a ‘Text’ question), a single property is inserted into the Data Model against the name of the item. Where an item needs to store multiple values (e.g. the ‘choice’ and ‘label’ associated with a ‘Select’ item), the item’s name will be used as an object which holds a property for each required value.

cti.store.pages.PageName.ItemName
cti.store.pages.PageName.ItemName.PropertyName

Note that an item will only appear in the model if it is used to store data, and will not appear in the Data Model until any data is recorded against them.

Variable Data

The ‘variables‘ section of the store contains a property for each variable which has been added via the App Config screen.

cti.store.variables.VariableName

Media Data

Items which are used to capture media (photos, audio) store their data in a special ‘media‘ section of the Data Model. An individual item is used for each media-based item, which each containing an ‘images’ or ‘audio’ array with references to the data.

cti.store.media.ItemName.images
cti.store.media.ItemName.audio

Environment Data

The ‘env’ sections contains details of the application’s environment, such as the type of platform used to display the application. This is useful for producing different behaviour based on whether the application is being used on a desktop or mobile device.

cti.store.env.PropertyName

1b. Utils

The ‘cti.utils’ section of the Data Model contains a number of utility functions which can be called within the app. These allow you to programatically carry out a range of tasks, such as executing actions and clearing data.

Some of the functions have an equivalent option within the Studio, whereas others are only available as a utility function. To use one of the utility functions, simply reference it within JavaScript in the application (e.g. within an inline function), or type the reference into the debug console.

callAction

CommonTime Infinity provides a list of Actions which can be called within an app to carry out a range of functionality. These are normally added to the app by dragging the corresponding action from the Toolbox and dropped it into an Actionflow or the ‘Actions’ tab of an item.

Further documentation on how to use the ‘callAction‘ function will be coming soon.

destroyAllData

The ‘destroyAllData’ function can be used to clear all data from the Data Model and return the model to its initial state. This will affect all data relating to pages, media, APIs, XMPP etc.

cti.utils.destroyAllData();

destroyPageData

Data which is captured via a page in the application (e.g. text field, signature) can be cleared from the model using the ‘destoryPageData‘ function. This can either specify a particular page to clear, or be left blank to destroy all page related data within the model.

cti.utils.destroyPageData('PageName');
cti.utils.destroyPageData();

Note that this will not actually ‘destroy’ the page item within the model. Instead all values within that page (which have previously been set) will be changed to undefined.

getMetadataItem

Each app is able to store multiple metadata values which are configured via the app’s settings. The value of each metadata item can be obtained programatically using the ‘getMetadataItem‘ utility function.

cti.utils.getMetadataItem('MetadataItemName');

stopAllRecording

As the name suggests, the ‘stopAllRecording‘ function can be used to stop all recordings which are currently being used to capture data within the application.

cti.utils.stopAllRecording();

updatePage

The ‘updatePage‘ function will reload the current page to ensure that the latest data is obtained from the Data Model.

cti.utils.updatePage();

2. View the Data Model

Whilst the Data Model exists for all applications, it is not visible for an end user when using the app. However, using the debug console it is possible to display and explore the model to find out what data it has captured, and what objects you can reference.

On a desktop version of the Studio the console can be displayed by selecting Debug > Developer Tools in the top menu of the Studio. The console is also available for Android devices using the Chrome Inspector. Once open, type cti into the console to display the full Data Model.

 

Note that the console does not auto-update to show the latest data in the model. If you make a change within the app it will be necessary to re-enter ‘cti‘ to reflect the model in its current state.

As the model is represented by a JSON object it is possible to append values to cti to explore a specific part of the model. For example, the string below can be used simply to return the value of a Text item called ‘firstname’ which resides on the ‘Details’ page:

cti.store.pages.Details.firstname

 

3. Manipulate the Data Model

Whilst an application is running it is possible to both obtain data from, and set data within the Data Model. There are multiple ways to achieve this, with different styles used depending on the type of item used to reference the data.

Further details of these processes can be found on the ‘How to manipulate the Data Model‘ page.