Beginner’s Guide to dizmo Development

General

Writing dizmos is very similar to writing web applications for a browser. As a matter of fact, dizmos are similar to web pages of a browser, but with enhanced functionality. DizmoViewer uses Webkit as the underlaying Browser platform. You might have heard of HTML5, the combination of Javascript, HTML and CSS; most of those techniques and technologies can be used to write dizmos.

Javascript

As dizmo development is mainly done in Javascript (with HTML and CSS for the layout), it’s helpful to get yourself familiar with Javascript. Here are some good books that you can go through:

  • JavaScript: The Definitive Guide by David Flanagan
  • Eloquent JavaScript by Marijn Haverbeke
  • JavaScript Patterns by Stoyan Stefanov
  • Writing Maintainable JavaScript by Nicholas Zakas
  • JavaScript: The Good Parts by Douglas Crockford

SPA

Dizmos are single page web applications (SPA). Single Page Web Applications are served from one HTML document (as the name suggests), which contains the layout of the entire application. Thus, SPAs don’t use URLs, as there is no navigation between pages when different parts of the application are accessed. Additional data and content can be loaded on demand using AJAX. The application logic is implemented in Javascript. And compared to websites, dizmoViewer loads the initial HTML Document as well as assets locally and not from a remote server.

Build System

Our build systems DizmoGen supports you with writing, building and deploying dizmos. As the dizmos itself, dizmoGen has been built with Javascript – based on the very popular node.js runtime together with the npm package manager, which gives access to a rich ecosystem of Javascript libraries. DizmoGen relies on yeoman and gulp, both of which are well known and widely used toolkits. Apart from pure Javascript, the build system also supports CoffeeScript and TypeScript, two languages which are based on Javascript but with additional features.

Editors

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)

Dizmo concepts

To start, 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 others 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

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:

New project

yo dizmo asks you a set of questions and then generates a skeleton of a dizmo, which you then can expand on.

Build

npm run make creates a new .dzm file, which can be dropped into dizmoViewer to be installed.

Deployment

npm run deploy creates a new .dzm file and installs it. Then, reload the dizmo from the dizmo menu.

Watch

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.

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
  • Radiobutton
  • Slider
  • Selectbox
  • Switch
  • Button
  • Inputfield
  • Textarea
  • 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 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 getAttribute and setAttribute functions.

Data Tree

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.

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 viewer. 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 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.

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.