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 grace to build and include embedded dizmos in one automatic step.

Manually

You can do that separately in the same way as you implement and build any other dizmo. The result can then be embedded into your dizmo by copying the .dzm file into your dizmo. The assets folder on the top level of your dizmo is the typical place to put it.

Embedding a dizmo
Embedding a dizmo

Using grace

As an alternative grace allows you to auto build and embed one or more dizmos in one automated step. In order to do so add an "embedded_projects" object to your dizmo’s project.cfg file. This object consists of an anonymous object for every embedded dizmo. The following fields may be used in these objects:

field description sample
source The source from which the code of the embedded dizmo can be loaded. This can be a path relative to your main dizmos folder on your local disk, a github url or the path to a local or remote .zip or .tgz file "source": "../MyEmbeddedDizmo/", "source": "https://github.com/dizmo/MyEmbeddedDizmo", "source": "/home/myuser/MyEmbeddedDizmo.zip"
destination The local path in your dizmo folder to which the embedded dizmo should be copied "destination": "./assets"
bundle_identifier The bundle identifier of the embedded dizmo "bundle_identifier" : "org.example.myembeddedizmo"
options This allows you to pass any options to the grace process building the embedded dizmo (see using -o in grace for more information) "options": { "credentials:username": "myuser" }

The source field can be an object providing additional information about the source of the dizmo folder to be used to build the embedded dizmo

subfield description sample
url Use this field in a source object to provide the path of the dizmo source. "source": {"url": "https://github.com/dizmo/MyEmbeddedDizmo"}
branch Use this field in a source object to specify the branch to be used if source points to a git repository (will be ignored otherwise) "source": {"url": "https://github.com/dizmo/MyEmbeddedDizmo","branch": "prod"}
type Use this field in a source object to indicate the type of source. If not specified grace will try to guess the right type automatically "source": {"url": "https://github.com/dizmo/MyEmbeddedDizmo","type": "git"}
"dizmo_settings": {
  "embedded_projects": [
    {
      "source": "../MyEmbeddedDizmo/",
      "destination": "./assets",
      "bundle_identifier": "org.example.myembeddeddizmo"
    },
    {
      "source": {
        "url": "https://example.com/dizmo_repos/MyEmbeddedDizmo",
        "type": "git"
      },
      "destination": "./assets",
      "bundle_identifier": "org.example.myembeddeddizmo",
      "options": {
        "credentials:username": "myuser"
      }
    },
    {
      "source": {
        "url": "https://github.com/dizmo/MyEmbeddedDizmo",
        "branch": "prod"
      },
      "destination": "./assets",
      "bundle_identifier": "org.example.myembeddeddizmo"
    }
  ]
}

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 Grace to embed dizmos this step will be done by the Grace build process.

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.

// 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);

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

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.