Model Tree

The Model Tree is a specialized version of the tree widget used to load object models from the system. It is optimized to handle large trees which can be slow to load in one go. The Model Tree retrieves its content incrementally and on-demand when the user expands nodes for which the children are not yet loaded in the widget. All nodes retrieved from the system are also assigned a leading model class icon. These are the same icons as seen in DataStudio. If a class icon for a specific object type is not yet available a generic default icon "Generic" is show instead.

The widget-model also exposes configuration options used to add arbitrary numbers of system-object properties to the returned dataset in addition default fields which for each tree node are:

  • n: ObjectName

  • i: Numeric ObjectID

  • t: Object type code

  • c: Array of child nodes. This field will be absent if the system-object contains child nodes which have not yet been loaded. An empty array is used to indicate that the object has no child-nodes to expand.

The word "model" is used in two different contexts on this page. In reference to the content rendered by the widget, model refers to the objects managed by the system. When talking about the configuration of the widget in WebStudio, model refers to the widget properties that that are defied in the compilation and edited in the JSON editor.

Model

{
    "type": "modeltree",
    "modelRoot": {
        "depth": 1,
        "properties": [],
        "items": [
            {
                "path": "/System",
                "includeRoot": true
            }
        ]
    },
    "schemaExtension": [],
    "searchTable": {}
}

Model Root

Unlike the tree widget the modeltree does not use its dataSource to load content nor does it have a data property where the content can be statically defined, but instead relies on the modelRoot property to define what information should read from the system.

The configuration items in the modelRoot section are describe in the table below:

Name Description

depth

Optional number indicating how many levels of the object-tree should be fetched when a node is expanded. By default, the tree is only expanded one level at a time.

items

Array of one or more system-model entries to add at the "root" level in the tree.

depth

Number of levels of the tree to retrieve when a un-loaded node is expanded. This value overrides the depth specified at modelRoot level

path

system-object path to start the tree branch at.

includeRoot

This value is true by default. When set to false, the children of the system-object are loaded as the first level in the tree.

properties

Array of one or more entries indicating which object properties in addition to the default ones, to include in the returned dataset.

Extra object properties will be returned based on the content of the properties array. Each entry can be configured in one of four ways:

  • property path string: Property path relative to the object. This value is easily obtained from DataStudio by right-clicking on the property name in the property panel and copying the property path. The property name obtained in this way will have a leading dot, which can be omitted on the WebStudio side, but may also be left in place. The full property name is used as the key in the returned dataset.

  • Numeric property code: Property codes can be looked up in the online system-model properties help pages. The property code will be translated to the corresponding name, which will be used as the key in the returned dataset.

  • Key - name object: Use this format to explicitly define the key (k) to use for the property in the returned dataset. This is desirable to reduce the size of the data, since property names can be quite long and are repeated in each node with a value for the added property. The n field is used to specify the name or code of the property to return.

    {
        "n": "DecimalPlaces", // Name of the property to return
        "k": "dp"  // name for this property in the tree data
    }
  • Key - name array: An even more compact version of the "key-name" definition can be provided by using an array in which the first element is either the name or code of the system property to retrieve and the second is the key for the value in the return set. For example.

    [
        "ObjectDescription", // Name of the property to return
        "desc" // name for this property in the tree data
    ]

References to compound properties are automatically expanded down to their "leaf" value levels. The content of table properties can also be retrieved, but this option should be used with caution since it can result in a large amount of data being loaded from the system. The content of big-tables is not returned nor are password fields.

Custom properties:
The names and values of custom properties can be returned by adding the

  • "CustomOptions.CustomProperties.CustomPropertyName" and

  • "CustomOptions.CustomProperties.CustomPropertyValue"

paths to the properties list. Custom property names and their corresponding values are added to separate arrays on the node. This may not be very convenient if you are looking for a subset of properties or want the values and their name as key-value entries in the tree node.

For this purpose, a pseudo property path with the format shown below may be used to explicitly select individual custom properties to be included:

  • "CustomOptions.CustomProperties.<name>"

For example, to retrieve a custom property called "myCustomProp", add the path "CustomOptions.CustomProperties.myCustomProp" to the list.

Data Sources

The dataSource can be used to dynamically load the work model elements such as schema, schema extension, and or modelRoot. This is similar to how the tree widget works and requires that the type field, set to "modeltree", should be present in the output of the dataSource when including properties other than the schema.

Unlike the regular tree widget, node data cannot be returned by the dataSource. It is also not stored in the work model. The latter is done for performance reasons allowing modify actions to be performed without the need to copying the whole tree node structure into the action message.

Search Table

The search table only shows the nodes which are being fetched and stored in memory. Selecting a node in the search table works the same as in the tree widget. The subtree up to the selected node gets expanded and the tree scrolls and shows the selected node.