MOD Gui

The web interface definition for this plugin. It's defined by html templates for icon and settings panel, css, images and other media, that's contained in the plugin bundle.

Relates a plugin to the its MOD Graphical User Interface

A template that will be used to render the HTML icon of this plugin. The value of this property must be a URI that resolves to a Mustache template.

The syntax and guidelines for templates are the same for mod:iconTemplate and mod:settingsTemplate, so this documentation applies to both.

General guidelines

To build the interface, follow these guidelines:

• Start with a basic HTML template and use the MOD SDK to test it.
• Use the {{{ns}}} tag inside the template to access images and media inside the bundle. More explanation on this at mod:templateData.
• If you need new styles, always prefix them with the name of your project. In HTML all css classes are global, so this is necessary to avoid messing with the general interface.
• Use the mod-role attribute to mark elements that are functional for the plugin (see below).

Functionality

Some elements in your layout are just informative for the user, like the effect name, branding and background img. Others are functional, like the knobs and footswitch. A functional element is marked as so by the "mod-role" attribute, and other mod-* attributes may be used as parameters. The following functional elements may be indicated:

Bypass

MOD compatible hosts MUST implement a bypass in each plugin loaded. Two elements are responsible for this, the bypass footswitch and bypass light indicator.

The footswitch is an element identified by the mod-role="bypass" attribute. Once clicked, the effect bypass will be turned on or off, and the light indicator will be changed as so.

The light indicator is identified by mod-role="bypass-light". It will automatically receive the class on or off, so designers are expected to implement a background image for each of these classes, or equivalent.

Control buttons

Each plugin can have buttons to control plugin's parameters. Each button is identified by the attribute mod-role="input-control-port" and configured by mod-port-symbol attribute, which must hold the port's symbol, and mod-widget attribute, that defines which widget to use. The available widgets are film, select and custom-select, and each of them expects a certain HTML structure in this element.

Film widget

The film widget works like a movie film: it uses a big stripe of images and roll it to choose a scene, giving the impression of an animation. So, if you use mod-widget="film", this element is expected to have a background-image style, with one big horizontal sprite as background. User will be able to change that parameter by clicking on the control button and dragging the mouse up or down. As this is done, the background image will be moved to reflect the new state.

The minimum value of that port will be represented by the first position of the sprite and the maximum value by the last one. The number of steps will be calculated by dividing the background width by the element's width, considering the background-size style. The actual number of steps will be the minimum between the number of images in sprite and the steps limited by lv2 definition (by pprops:rangeSteps, lv2:enumeration or lv2:toggled.

For example, suppose you want to build a horizontal slider that can hold 10 different positions occupies an area of 150x30 pixels, to control the drive parameter of your plugin. For that, you could:

• Design an image of 1500x30 pixels, each piece of 150x30 representing one position of the slider;
• Save it inside the mod:resourcesDirectory directory, in your bundle, as slider.png
• Put the following code into your HTML: <div mod-role="input-control-port" mod-port-symbol="drive" style="width: 150px; height: 30px; background-image: url(/resources/slider.png{{{ns}}}">
• Suppose you wanted to use the same sprite for a half sized version of the slider, you could instead use the style "width: 75px; height: 15px; background-image: url(/resources/slider.png{{{ns}}}; background-size: auto 15px;"

Select widget

The select widget is a simple <select> html element with available options, each one representing one value for this control port. It's mainly intended to be used for ports with the lv2:enumeration property, but can be used for any case in which picking values from a limited set is desired.

So, if you use mod-widget="select", this element is expected to be a <select> and contain several options, each of them must have the value attribute reflecting the float value of this property.

Custom select widget

This widget is similar in functionality to select widget, but instead of a select html element holding options, you can choose any element types to represent the widget and the options. If you use mod-role="custom-select", this element is expected to have children elements with the attributes mod-role="enumeration-option" and mod-port-value="(float value)". The selected element will receive the selected class, and so you can define your CSS as to highlight it as desired.

In case you want a list of options to be shown when the widget is clicked, you should mark the element containing the options with mod-widget-property="hidden". When this happens, every click on the widget will toggle that element's visibility.

Control values

To allow user to see the minimum, maximum and current value of a plugin, three mod-roles are available: input-control-minimum, input-control-maximum and input-control-value. All of them expect a mod-port-symbol attribute containing the symbol of the port.

The input-control-minimum, input-control-maximum will have have it's text content set to be the formatted minimum and maximum values accepted by this control, as defined by the lv2:minimum and lv2:maximum properties respectively. The input-control-value will be dinamically changed everytime the value of the control port changes.

All values are formatted according to the units:unit's and units:render property of this port, with some considerations. First, any %f will be rendered as %.2f, otherwise interface is messed up with huge representations. Second, if lv2:integer property is declared, then any %f, %.Xf or so will be substituted by %d.

Audio ports

Each plugin has audio input and output ports. They are identified by mod-role="input-control-port" and mod-role="output-control-port" attributes respectively, and both must have a mod-port-symbol property containing the port symbol.

For implementing the connections, each output will receive a <div> element inside, representing a jack (this will be automatically inserted). This jack can be dragged by user and dropped inside an input, and so a connection will be made.

This does not apply to Settings template

Drag handle

Plugins can be dragged around the pedalboard dashboard. To define which area of the plugin can be clicked for dragging, an element with the attribute mod-role="drag-handle" can be defined.

This does not apply to Settings template

This is a URI that resolves to a directory inside the bundle. Any file inside this directory will be statically served to browser, and will be available at the /resources path.

For the webserver to properly identify where to look, any request for media inside this directory must have an ?bundle=BUNDLE&url;=EFFECT_URL parameter.

Note: using a static url with ?bundle=BUNDLE parameter in any template would be a violation of LV2 Bundle Definition guidelines. So hosts should not require the bundle parameter to load the resources. This parameter is used mostly by the SDK, since speed of reloading for testing interface is an issue there and no bundle index is made. To avoid problems here, always use the {{{ns}}} tag instead of raw urls in your templates and stylesheet, as described in mod:templateData.

An image with a real size screenshot of the rendered plugin interface. The value of this property must be a URI that resolves to an image.

A template that will be used to render the HTML settings panel of this plugin. The value of this property must be a URI that resolves to a Mustache template.

To develop this, use the same guidelines and markup as described in mod:iconTemplate. The only difference is that the audio ports here are irrelevant

A CSS file that holds all styles used for this plugin. The CSS will be automatically loaded on request. For implementation reasons, only one CSS file per effect is supported.

The stylesheet will be parsed for dynamic content, so the {{{ns}}} tag can be used to reference background images and other resources.

Remember that all class names must be preceded by the bundle's name to avoid conflicting with other plugins or general interface.

The data that will be used to render the templates defined in mod:iconTemplate and mod:settingsTemplate. The value of this property must be a URI that resolves to a json serialized object and its data can be inspected using the SDK's debug interface.

This parameter isn't strictly necessary to build a plugin layout, as the template can hold the final HTML file, but it's very useful to allow developers to customize layout using templates provided by the SDK, instead of editing HTML files.

The data in this file must be a dictionary. Two keys are automatically set: effect, ns.