Plugin API » Directory structure

Directory structure

Plugins are a collection of JavaScript code, templates, automated tests, and other resources, stored in a directory named after the plugin. An example_plugin might look like this:

    example_plugin
      \- plugin.json
      \- js
           \- example_plugin.js
           \- eg_reporting.js
      \- requirements.schema
      \- template
           \- details.hsvt
      \- static
           \- ui.js
           \- picture.gif
           \- style.css
      \- file
           \- form
                \- details.json
      \- i18n
           \- local
                \- en.template.json
                \- en.form.json
           \- global
      \- test
           \- test.schema
           \- test_feature1.js
      \- global.js (optional)

plugin.json

The plugin.json file describes the plugin.

js

The js directory contains the server side JavaScript code for the plugin. Files in the directory are loaded in the order specified in the plugin.json file.

JavaScript files loaded with an automatically generated wrapper:

(function(P) {
    // Contents of your JavaScript file go here
})(example_plugin);

If a locals directive is used in the plugin.json file, these are implemented as additional arguments. For example, with "locals":{"X":"exampleProperty"},

(function(P, X) {
    // Contents of your JavaScript file go here
})(example_plugin, example_plugin.exampleProperty);

requirements.schema

The requirements.schema file describes the minimum requirements the plugin has of the application schema.

The Platform uses it to alter the application’s schema when the plugin is installed or updated, and then make the various schema objects available to the plugin as readable names in the plugin’s local schema dictionaries.

template

HSVT Templates are stored in the template directory with a .hsvt file extension.

static

Files in the static directory are made available over HTTP. Use it for client side resources like scripts, stylesheets and images.

Note that CSS files are rewritten slightly.

Filenames of files in the static directory may only contain the characters a-zA-Z0-9_-, and must have an extension which may only contain a-zA-Z0-9.

To use these files in your plugin, use the std:plugin:resources() template function to include references to the files in your HTML, or the staticDirectoryUrl property on your Plugin object to form URLs.

There is no access control on the files, and they’ll be served to anyone who knows the URL.

Files are served with expiry times several years in the future. Whenever the files are updated, for example on plugin upgrade, the URL of the files is changed.

file

Files in the file directory are accessible to the plugin using your plugin’s loadFile() API.

This is intended to be used to contain bundled data used by the plugin which should not be publicly available. For example, rarely used lookup data could be stored as JSON files and loaded when required.

The file/form directory is the conventional location for files used as form definitions, loaded with the plugin form interface.

Use the static directory for files which are to be made available over HTTP and do not need access control.

i18n

Files in the i18n directory provide resources for internationalisation of this plugin. They are split into local and global directories. local provides resources for this plugin only, and global provides them to the entire application. When searching for resources, local takes priority.

All filenames start with the locale ID, for example, en.

i18n is short for ‘internationalisation’, which is a very long word.

test

Tests live in the test directory, as one JavaScript file per test. These are run on the server by the Plugin Tool.

The test/test.schema is applied before the tests are run.

global.js

The global.js file is optional, and not required by the vast majority of plugins. It’s used for initialisation which cannot be done inside the anonymous function which wraps all the other JavaScript files.

If you do use a global.js file, it must include the O.plugin() call to create your plugin object, for example,

var example_plugin = O.plugin("example_plugin");