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