Introduction to the Data Tree (structure)
A dizmo stores data items that need to be persistent in order to preserve them for later use in the data tree. These data items are called ‘properties’ or ‘nodes’ of the data tree.
The data tree is also used to exchange data items between multiple dizmos as well as between dizmos and dizmoViewer. This happens by reading and writing data from and to particular nodes in the data tree. Every item in the data tree, that is every node, has a unique name that is used to read from and to write to it. Nodes are organized in a hierarchical way resulting in a data tree.
Paths
Nodes in the data tree are addressed using a unique ‘path’ for each of them. The virtual top node of the data tree has the path ‘/’. It is virtual because it does not contain any data but just three children or subnodes named ‘viewer’, ‘dizmos’ and ‘bundles’. So to access the viewer node you would use the path ‘/viewer’. This ‘/viewer’ node has three children or subnodes itself which are named ‘attributes’, ‘private’ and ‘public’. So, to access the ‘attributes’ node you would use the path ‘/viewer/attributes’.
Following the same principles you would access the subnode of ‘/viewer/attributes’ called ‘geometry’ using the path ‘/viewer/attributes/geometry’ and so on.
In general, a path starts with the ‘/’ denoting the root node and adds the names of all the nodes along the way down to a specific data node separating the nodes names using a ‘/’.
There are three top nodes called ‘/viewer’, ‘/dizmos’ and ‘/bundles’ in the dizmo data tree under the virtual root node.
‘/viewer’ subtree
The main purpose of the ‘viewer’ subtree is to exchange data between dizmos and dizmoViewer about settings and states of dizmoViewer itself. The ‘viewer’ subtree is also used to make data items available to all local dizmos as well as to the web in general.
‘/viewer/attributes’ subtree
The subtree of the ‘/viewer/attributes’ node provides all kinds of information about the instance of dizmoViewer currently running.
To simplify access to these attributes dizmoViewer provides specialized functions to access the attributes available. Please have a look at the chapter on Persistence.
Here are some examples of available nodes in the ‘/viewer/attributes’ subtree. For a complete list, refer to the API documentation of the dizmojs.Viewer class and take a look at the dizmo data tree.
‘/viewer/attributes’ subtree table
| path | wrt | type | range | description |
|---|---|---|---|---|
| geometry | no | node | Provides subnodes holding information about the geometry of the surface provided by dizmoViewer. Access these items using viewer.getAttribute('geometry/[info]'); |
|
| geometry/angle | yes | float | 0..360 | The rotation angle at which the surface of dizmoViewer is currently displayed |
| geometry/x | yes | integer | -3000..3000 | The x coordinate of the center of the rectangle of the dizmoViewer surface currently being displayed |
| geometry/y | yes | integer | -3000..3000 | The y coordinate of the center of the rectangle of the dizmoViewer surface currently being displayed |
| geometry/height | no | integer | 0..3000 | The height of the rectangle of the dizmoViewer surface currently visible |
| geometry/width | no | integer | 0..3000 | The width of the rectangle of the dizmoViewer surface currently visible |
| geometry/zoom | yes | float | 0.1..10 | The zoom level used to render the currently visible part of the dizmoViewer surface |
| globalSettings | no | node | Provides access to all the values read from the basic settings file of dizmoViewer (GlobalSettings.xml). Access them using viewer.getAttribute('globalSettings/[setting]'); |
|
| globalSettings/CurrentSetLanguage | no | string | An ISO 639-1 two character language code | The language currently set for the user interface |
| product | no | node | Provides all kinds of information about the instance of dizmoViewer currently running. Access them using viewer.getAttribute('product/[info]'); |
|
| product/compileDate | no | string | date and time in the format dd.mm.yy hh.mm | The date and time when the instance of dizmoViewer running was compiled e.g. ‘18.12.14 14:54' |
‘/viewer/private’ subtree
The ‘/viewer’ subtree also provides the node ‘/viewer/private’. Information stored under this node is available to all dizmos running in the local dizmoViewer. Be careful when publishing data in this subtree in order to avoid any unnecessary clutter. It should be only used if the data stored here is of interest to all or at least most local dizmos.
‘/viewer/public’ subtree
The ‘/viewer’ subtree also provides the node ‘/viewer/public’. Information stored under this node is available to all dizmos running in the local dizmoViewer and will be made available to any network device that has access to the device on which dizmoViewer is running. Be cautious when publishing data in this subtree. It should only be used if the data stored here is of interest to other network devices.
‘/dizmos’ subtree
The main purpose of the ‘dizmos’ subtree is to exchange data between dizmos and dizmoViewer about settings and states of each dizmo. This is the subtree in which a dizmo instance should store data items to make them persistent, i.e. to store and retrieve them later. There is a separate subtree for every instance of a dizmo. So for example, if there are two instances of StickyNotes dizmos, both have their own subtree to store their data completely separate from each other.
This separation is achieved by adding a subnode to the ‘/dizmos’ node for every dizmo that has been created in dizmoViewer. The name of this subnode is a ‘dizmoId’, i.e. a randomly created unique number in hexadecimal format like for example ‘hdef7bbd30649dc6c7b8622c677cb88d4’. In this documentation we use ‘[dizmoId]’ as a placeholder for this unique identification for every dizmo instance.
Like the ‘/viewer’ node ‘/dizmos’ also provides the three subnodes ‘attributes’, ‘private’ and ‘public’ for every dizmo instance. So, to access the ‘attributes’ node of a particular dizmo instance you would use the path ‘/dizmos/[dizmoId]/attributes’ where ‘[dizmoId]’ would be a ‘dizmoId’ as described above.
‘/dizmos/[dizmoId]/attributes’ subtree
The subtree of the ‘/dizmos/[dizmoId]/attributes’ node provides all kinds of information about the instance of a dizmo.
To make the access to these attributes as simple and straightforward as possible dizmoViewer provides specialized functions to access the available attributes. Please have a look at the chapter on Persistence.
The following are some of the available nodes in this subtree. For a complete list, refer to the API documentation of the dizmojs.Dizmo class and take a look at the dizmo data tree.
‘/dizmos/[dizmoId]/attributes’ subtree table
| path | wrt | type | range | description |
|---|---|---|---|---|
| lastError | no | integer | – | The last error code raised for this dizmo |
| created | no | integer | number of seconds | The time when the dizmo was created in milliseconds since midnight of January 1, 1970, according to UTC time. Use d = new Date(parseInt(dizmo.getAttribute('created'))); to get a date object representing the creation time. |
| geometry | no | node | Provides subnodes holding information about the geometry of the dizmo. Access these items using dizmo.getAttribute('geometry/[info]'); |
|
| geometry/angle | yes | float | 0..360 | The rotation at which the dizmo is displayed on the surface of dizmoViewer. A value of ‘0’ means the dizmo is drawn upright |
| geometry/x | yes | integer | -3000..3000 | The x coordinate of the dizmo. The position of a dizmo is relative to the upper right corner of the center of the dizmoViewer surface currently being displayed. If a dizmo is a child of another dizmo, coordinates and angles are relative to the parent dizmo. |
| geometry/y | yes | integer | -3000..3000 | The y coordinate of the dizmo. The position of a dizmo is relative to the upper right corner of the center of the dizmoViewer surface currently being displayed. If a dizmo is a child of another dizmo, coordinates and angles are relative to the parent dizmo. |
| geometry/height | yes | integer | 0..3000 | The height of the frame of the dizmo in pixels |
| geometry/width | yes | integer | 0..3000 | The width of the rectangle of the dizmo in pixels |
| geometry/zoom | yes | float | 0.1..10 | The zoom factor used to render the dizmo on the dizmoViewer surface. A value of 1 means the dizmo is drawn the way it has been described by the original HTML and CSS code |
‘/dizmos/[dizmoId]/private’ subtree
Data stored in nodes in the ‘/dizmos/[dizmoId]/private’ subtree can be accessed only by the dizmo itself. This allows you to hide data from other dizmos in order to keep it internal if required. You are free to use any name and any hierarchy for the nodes in this subtree.
‘/dizmos/[dizmoId]/public’ subtree
Data stored in nodes in the ‘/dizmos/[dizmoID]/public’ subtree can be accessed by all other dizmos in the same dizmoViewer. This part of the data tree also provides data for other dizmos that are docked or dragged onto yours.
You are free to use any name for the nodes in this subtree. However please note that by convention the nodes ‘/dizmos/[dizmoId]/public/schema’ and ‘/dizmos/[dizmoId]/public/stdout’ are used to provide data to docking dizmos. Please have a look at the chapter about Docking for more information.
‘/bundles’ subtree
As described in the Technology chapter, a bundle is the directory containing the source code and other items needed to instantiate new dizmos of a particular type.
The main purpose of the ‘/bundles’ subtree is to provide data about bundles available to instantiate new dizmos including settings and states for each bundle available locally.
Additionally, the ‘/bundles’ subtree allows dizmos of the same type, i.e. dizmos that have been created from the same bundle, to share data that is not available to dizmos of any other type.
Each bundle type has its own separate subtree. This separation is achieved by adding a subnode to the ‘/bundles’ node for every bundle that has been installed in dizmoViewer. The name of this subnode is a ‘bundleId’ (in reverse domain name notation) used to identify a particular bundle, for example com.dizmo.example, com.dizmo.about or com.dizmo.pad. This string is provided by the developer in the file Info.plist as the ‘BundleIdentifier’. In this documentation we use ‘[bundleId]’ as a placeholder for this unique identification for every bundle.
Like the ‘/viewer’ node ‘/bundles’ also provides the three subnodes ‘attributes’, ‘private’ and ‘public’ for every bundle available. So, to access the ‘attributes’ node of a particular bundle type you would use the path ‘/bundles/[bundleId]/attributes’ where ‘[bundleId]’ would be a ‘BundleIdentifier’ as described above.
‘/bundles/[bundleId]/attributes’ subtree
The subtree of the ‘/bundles/[bundleId]/attributes’ node provides all kinds of information about the bundle used to instantiate a dizmo.
To make the access to these attributes as simple and straightforward as possible dizmoViewer provides specialized functions to access the attributes available. Please have a look at the chapter on Persistence.
Here are some of the available nodes in this subtree. For a complete list, refer to the API documentation of the dizmojs.Bundle class and take a look at the dizmo data tree.
‘/bundles/[bundleId]/attributes’ subtree table
| path | wrt | type | range | description |
|---|---|---|---|---|
| author | no | string | – | The name of the developer who developed this bundle. |
| category | no | string | dizmo category | The category under which the developer of this bundle has published his work. This information is read from the Category parameter of the bundle’s Info.plist file. |
| description | no | string | – | The description provided by the developer who published this bundle. This information is read from the Description parameter of the bundle’s Info.plist file. |
| elementsVersion | no | string | [0..255].[0..255] | The version of the dizmoElements library this bundle uses. This information is read from the ElementsVersion parameter of the bundle’s Info.plist file. Example: ‘1.0’. |
| hidden | no | boolean | true / false | This flag is true for dizmos that will never appear in the creator because they are instantiated by other interaction elements. About and Creator are two examples of this type of dizmos. |
| tags | no | array of strings | – | An array of tags that have been associated by the developer with this bundle. |
‘/bundles/[bundleId]/private’ subtree
Data stored in nodes in the ‘/bundles/[bundleId]/private’ subtree can be accessed only by dizmos that have been created using the bundle with the id ‘bundleId’ . This allows you to share data with dizmos of the same type while hiding it from other dizmos that are based on other bundles. You are free to use any name and any hierarchy for the nodes in this subtree.
‘/bundles/[bundleId]/public’ subtree
Data stored in nodes in the ‘/bundles/[bundleID]/public’ subtree can be accessed by all other dizmos in the same dizmoViewer. Hence, though the data stored in this subtree is public, it still belongs to and is shared by dizmos of a specific bundle.