AppSuite:UI manifests explained

API status: In Development

Manifests

Abstract: Manifest files in the app suite declare either apps or plugins. They tell the app suite runtime which files to load when, so the code in it can take effect at the appropriate time. This document should be read by everyone that wants to either build a plugin or an app and contains a description of how to get app suite to run your code.

Declaring apps

The minimal declaration for an app looks like this:

 
    {
        title: "My App",
        path: "com.example/myapp/main"
    } 

It consists of a title for the app and the path to the main entry file, by convention always called main.js. This declaration is usually found in the file manifest.json right next to the app in question, but could theoretically be located anywhere. If the file is located in the same directory as the main entry file and the file is, as is the convention, called main.js you can leave out the path as it will be added automatically by the buildsystem, so the minimal definition then becomes:

 
    {
        title: "My App"
    }

Declaring a plugin

In turn, this is the definition of a plugin file:

 
    {
        namespace: "io.ox/contacts/view-detail",
        path: "com.example/myapp/contacts/register"
    } 

The namespace contains the name of a frontend module for which the plugin is relevant. Declaring a plugin like this has the effect, that the plugin is loaded before the file named as the namespace is loaded, so it can affect what the core file is doing, commonly by extending an extension point. The convention is to always put plugins into the file register.js, so again, the path can be omitted if the manifest.json is placed alongside the register.js containing the plugin. A plugin may be associated with more than one namespace, in that case, just use a list as the value for the namespace attribute:

 
    {
        namespace: ["io.ox/contacts/view-detail", "io.ox/contacts/edit/view-form"]
    }

Whichever module is loaded first will trigger the plugin to be loaded. Capabilities

Sometimes a plugin or an app is only available if either the backend has a certain bundle installed or the user must have a certain permission. Both permissions and backend capabilities are rolled into the concept of a "capability". If your plugin, for example, is only relevant when the user has access to the calendar module, you can add a requires attribute to the declaration:

 
    {
        namespace: "io.ox/contacts/view-detail",
        requires: "calendar"
    }

Which capabilities are available can be checked by either reading through existing manifests or by running this in the javascript console once logged into appsuite:

 
    _(ox.serverConfig.capabilities).pluck("id")

Multiple declarations in one file

If you need more than declaration in a manifest.json file, you can include them in a list:

 
    [
        {
            namespace: "io.ox/contacts/view-detail",
            path: "com.example/myapp/contacts/viewPlugin"
        },
        {
            namespace: "io.ox/contacts/view-form",
            path: "com.example/myapp/contacts/formPlugin"
        }
    ]

What happens to these files?

During a build run the buildsystem picks up these manifest files and consolidates them into a single file build/manifests/[myapp].json. This file, either by creating a symlink to a locally run backend or by installing the app package on a remote backend, winds up in the manifests directory of the backend and is processed and sent to the frontend. You can see all manifest declarations, that have been sent by the backend by looking at

  ox.serverConfig.manifests

in the javascript console.

Loading custom manifest during development

During development you can use a custom manifest file to avoid restarting the backend or, in case of a remote backend, updating it every time the manifests change. Just add customManifests=true to the URL so that the UI loads the file src/manifests.js. All manifests in that file will be added to the ones provided by the backend. The file is supposed to be an anonymous require module that returns the array of manifest entries:

 
define(function () {
  return [
    {
      path: "com.example/main",
      title: 'Hello World App'
    },
    {
      path: "com.example/contacts/register",
      namespace: "io.ox/contacts/view-detail"
    }
  ];
});

Note that the buildsystem doesn't add the path elements for this file. It's useful to have the buildsystem assemble the manifest.json files and then copy the resulting manifest entries into the array returned in the definition function. This file has to be linked into the deployed source folder:

 
rm /var/www/appsuite/src/manifests.js
ln -s /var/www/appsuite/src/manifests.js /path/to/custom/manifests.js

To tell app suite to load the custom manifest file, you have to invoke the frontend with "customManifests=true", e.g. /appsuite/#!&customManifests=true

Special namespaces

signin

Plugins that choose "signin" as (or amongst) their namespace, are loaded when the login page is shown. The code can be used to rearrange parts of the signin page or add custom behaviour to it.

core

Core plugins are loaded as soon as the frontend starts up after successfully logging in or reauthenticating with the autologin. This is useful if you need to run code very early.