Beginner’s Guide to dizmo Development
For writing a dizmo, you need at least a good text editor like Sublime Text (sublimetext.com) or Nodepad++ (notepad-plus-plus.org). You might also prefer to use an IDE, for example Atom (atom.io) or WebStorm (www.jetbrains.com/webstorm)
To start, 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 others 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
Package and install
An installable bundle can be produced by creating a zip-archive of the bundle directory and renaming it to have the extension
.dzm. Then, to install the bundle drag & Drop test.dzm into the open dizmoViewer.
While a very simple dizmo can be written and installed without any build system, we recommend dizmoGen to speed up your development workflow:
yo dizmo asks you a set of questions and then generates a skeleton of a dizmo, which you then can expand on.
npm run make creates a new
.dzm file, which can be dropped into dizmoViewer to be installed.
npm run deploy creates a new
.dzm file and installs it. Then, reload the dizmo from the dizmo menu.
npm run watch watches the source code for changes and auto builds/deploys the new version. After deployment, reload the dizmo from the dizmo menu.
The DizmoElements Library provides a set of UI elements, which are based on standard HTML elements, but restyled to match the dizmo theme:
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 viewer 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 viewer workspace (e.g
geometry/width). All attributes are accessed via the
The Data Tree stores key/value pairs hierarchically. Every key has an unique path and viewer, 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 viewer. 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 pixel 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 pixel 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