Embedding and Installing dizmos

You can install and instantiate one dizmo from another one using the viewer and bundle objects. You can even embed one or more bundles in your dizmo and install it from there. After that, you may instantiate your embedded dizmo as many times as you like.

Embedding a dizmo

To embed a dizmo in yours, you need to create the embedded dizmo first. You may do that manually or using dizmoGen.

After implementing and building the embedded dizmo, you need to copy the .dzm file into your dizmo. The assets folder on the top level of your dizmo is the standard place to put it.

├── LICENSE
├── README.md
├── assets
│   ├── Icon-dark.svg
│   ├── Icon.svg
│   ├── Preview.png
│   ├── embedded
│   │   └── my_embedded_dizmo_v0.1.2.dzm.dzm
│   └── locales
├── build
│   ├── my_dizmo
│   └── my_dizmo-0.0.1.dzm
├── gulp
│   ├── miscellanea
│   ├── package.js
│   ├── scripts
│   └── tasks
├── gulpfile.js
├── help
│   └── en
├── package.json
└── src
    ├── index.html
    ├── index.js
    ├── lib
    ├── style
    └── tests

Indicating embedded dizmos

To use your embedded dizmos, you need to indicate their presence to dizmoViewer by including their bundleIDs in the Info.plist file. To do this, integrate the following section in your Info.plist file. Without this, dizmoViewer does not install or instantiate your embedded dizmos.

<key>EmbeddedBundles</key>
  <array>
    <string>com.example.myembeddeddizmo</string>
    <string>com.example.otherdizmo</string>
  </array>

Note: if you are using dizmoGen to embed dizmos, this step will be done by the build process if you put the bundleIDs into the package.json.

"dizmo": {
    "settings": {
       ...
       "embedded-bundles": [
            "com.dizmo.my_embedded_dizmo"
      ]
    }
  }

If your main dizmo bundle is deinstalled by dizmoViewer, dizmoViewer uses this list to uninstall any of your embedded dizmos.

Note that all embedded dizmos must use the same domain prefix as your main dizmo. Otherwise, they are not installed.

Installing an embedded dizmo

To instantiate your embedded dizmo later, you must first install the bundle from within your main dizmo. Use viewer.installBundle to do this. The installation is done asynchronously. Thus, the rest of the environment does not have to wait for the procedure to be finished.

To be notified of the installation, you may specify a callback function that is executed once the installation is complete. For example, this allows you to instantiate a dizmo from your bundle as soon as it becomes available.

// instantiate the embedded dizmo from its bundle
function startDizmo(bundleid,error) {
    var newBundle = viewer.getBundleById(bundleid);
    var newDizmo = newBundle.instantiateDizmo();
}

// install a dizmo that is located inside of my own bundle in the assets directory
viewer.installBundle("bundle://assets/my_embedded_dizmo_v0.1.2.dzm", startDizmo);

To check if your bundle has been installed before, you may request a list of bundles installed with viewer.getBundles. Check if the embedded dizmo is part of this list. If so, close all of these dizmo instances before uninstalling the bundle.

Uninstalling an embedded dizmo

If your main dizmo bundle is deinstalled by dizmoViewer, dizmoViewer uses the list in EmbeddedBundles to uninstall any of your embedded dizmos.