Dizmo Development Guide

General

As dizmo development is mainly done in Javascript (with HTML and CSS for the layout), having a solid understanding of Javascript is a prerequisite to develop dizmos.

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.

Build System

DizmoGen, our build system for dizmos uses Javascript as well as node.js and npm, which give access to a rich ecosystem of libraries. It’s based on Yeoman and gulp, which are well known and widely used toolkits. DizmoGen extends Yeoman and gulp and helps you to write, build, test and deploy dizmos. It also supports CoffeeScript and TypeScript, two languages which are based on Javascript but with additional features.

Editors

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.

Dizmo concepts

To start with, it’s helpful to learn about some of the key concepts of dizmos:

Storage

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.

Docking

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.

Instantiation

A dizmo can contain other dizmos and instantiate these or other dizmos.

Hierarchies

Dizmos can form a parent/child hierarchy when they are placed on top of each other.

Geometry

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 dizmoready is the entry point for your own code (similar to the document.ready event 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.

DizmoElements

The dizmoElements library provides a set of UI elements, which are based on standard HTML elements, but restyled to match the dizmo theme:

  • Checkbox
  • Radio button
  • Slider
  • Select box
  • Switch
  • Button
  • Input field
  • Text area
  • List
  • Notification

Dizmo objects

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.

Attributes

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 getAttribute and setAttribute functions.

Data Tree

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.

Persistence

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 getProperty and setProperty functions.

Subscription

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.

Storing files

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.

Developer tools

When you enable the development mode of dizmoViewer, you get access to the web inspector for each dizmo. This allows you to inspect the HTML Elements, CSS and debug your Javascript code.

Styling & Design

Grid System

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.

CSS

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 style.scss.