Embedding and Installing dizmos

Using the viewer and bundle objects, you can install and instantiate one dizmo from another one. 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 typical 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

In order to use your embedded dizmos you will 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 will not install / 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, it will use this list to uninstall any of your embedded dizmos.

Note: Please note that all embedded dizmos must use the same domain prefix as your main dizmo. Otherwise they will not be installed.

Installing an embedded dizmo

In order 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 so the rest of the environment does not have to wait for procedure to be finished.

To get notified you may specify a callback function that will be executed one the installation is complete. For example this allows 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 = new dizmojs.Bundle(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 (viewer.getBundles) and 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, it will use the list in EmbeddedBundles to uninstall any of your embedded dizmos.