Dizmo Development Guide
If you are familiar with writing Single Page Web Applications (SPAs), you will feel right at home writing dizmos, which are SPAs. Compared to websites, the initial HTML document as well as assets are served locally and not from a remote server. Dizmos are similar to web pages of a browser, but with enhanced functionalities. DizmoViewer uses WebKit as the underlying browser platform.
You can use your preferred text editor for writing dizmos, or you might prefer to use your IDE. You might even wish to integrate the build system into your editor or IDE for a faster development cycle.
To start with, it’s helpful to learn about some of the key concepts of dizmos:
One of the key concepts of dizmos is the distinction between private and public storage for persisting data. While private storage is only accessible by the dizmo that creates it, the public one is accessible by all dizmos.
As a form of visual interaction, docking is a concept where dockable dizmos are brought next to each other and then can access each other’s public data.
A dizmo can contain other dizmos and instantiate these or other dizmos.
Dizmos can form a parent/child hierarchy when they are placed on top of each other.
A parent dizmo can access and change the (relative) geometry of a child dizmo and also access its public data.
Structure of a dizmo
There are two terms that are important to distinguish when talking about dizmos; bundle and dizmo. While a bundle is a set of files that form the base of a dizmo, each dizmo is an instance of such a bundle.
The following files are the minimal base for a bundle:
- info.plist: contains the metadata of a bundle
- index.html: main document, it contains the front and back side of your dizmo in two divs
- index.js: main application code, the document event
dizmoreadyis the entry point for your own code (similar to the
document.readyevent but dizmoready is fired when all internal libraries are loaded and the dizmo is ready)
- style.css: application style sheet, contains your own style definitions
However, you don’t need to create those files manually, you can simply use dizmoGen for it.
The dizmoElements library provides a set of UI elements, which are based on standard HTML elements, but restyled to match the dizmo theme:
- Radio button
- Select box
- Input field
- Text area
The dizmoJS library provides API functions to access the bundle, dizmo and viewer functionality. While we already talked about the definition of bundle and dizmo, the viewer refers to dizmoViewer, the platform that runs dizmos.
Properties of a bundle, a dizmo and the dizmoViewer are accessed via attributes. This could be the geometry of a dizmo (e.g
geometry/x), the bundle ID of a bundle (
identifier) or the geometry of the dizmoViewer workspace (e.g
geometry/width). All attributes are accessed via the
The data tree stores key/value pairs hierarchically. Every key has a unique path and dizmoViewer, dizmos and bundle as root elements. Under each root element attributes, private and public data is stored.
You can persist and recall your own data using the data tree, and again, the data can be saved either for each dizmo, each bundle or the dizmoViewer. As noted earlier, the data can be either private or public. Similar to the attributes, data can be written or read via the
Subscriptions make it easier reacting to changes of data. Instead of polling/checking for changes frequently, a callback is called as soon as there are changes. Subscriptions are available for both attributes and data.
You can also store files using the data tree. They are stored in the internal file system of dizmoViewer and the data tree saves the path to that internal file system.
Styling & Design
A dizmo measures multiples of 80 pixels from top to bottom and left to right including a border of 10 pixels on the bottom. Since the height of all the UI elements in the dizmoElements library is 40 pixels, you can stack these elements inside the 80 pixels’ grid.
While the DizmoElements library brings its own stylesheet to style the elements, you can define your own styles in the
style.css file. With dizmoGen, you can use SASS when defining your own styles in