Creating Plugins
Plugins are a great way to extend Respond to meet the needs of your users. In Respond 7, plugins are managed globally and distributed to sites when you create the site or when you update the plugins from the advanced menu.
Updating Plugins
You can find the source code for the existing plugins in the /resources/plugins/ folder. When you create your site with Respond, the sites theme folder will be copied over to your installation folder (/public/sites/site-name) and then the /resources/plugins folder will be copied over to the site.
To update the plugins, you simply update the code in this folder and then create a new site or update the plugins from the advanced menu "Advanced > Update Plugins".
Referencing Plugins in Code
The respond-plugin attribute is used to tell the system that the code contained within an element is generated by a plugin.
<div respond-plugin type="form" form="contact-us"></div>
In the above example, the plugin is set to a type of form. This tells Respond to pull the code from public/sites/site-name/plugins/form.html.
Enabling Plugins in the Respond Editor
You can enable the Respond visual editor to show your plugin by adding the following JSON to /resources/plugins/data/plugins.json. The file is copied to public/sites/site-name/data/plugins.json when the site is created. Once again, changing this file will not affect existing sites until you update the plugins from the advanced menu.
{
"selector": "[respond-plugin][type=form]",
"title": "Form",
"display": "<i class=\"material-icons\">check_box</i>",
"view": "<div class=\"respond-plugin\"><i class=\"material-icons\">check_box</i><span>Form</span></div>",
"html": "<div respond-plugin type=\"form\" form=\"contact-us\"></div>",
"attributes": [
{
"attr": "form",
"label": "Form",
"type": "select",
"values": ["respond.forms"]
}
],
"assets": ["plugins/form.html"]
}
| Setting | Description |
|---|---|
| action | A unique identifier for your plugin. |
| selector | The CSS selector by which your plugin can be accessed by the editor. Typically, this will be [respond-plugin][type=plugin] where plugin is the name of your plugin. |
| title | The title of the plugin. Shown when the icon is hovered over. |
| display | The HTML display of the icon shown in the toolbar in the Respond editor. |
| view (optional) | Specifies "default" HTML that is replaced by the editor. This is recommended when the plugin contains dynamic data that should not be edited by the user. |
| attributes | The attributes allow you to configure the configure modal for the plugin. Each configurable item is mapped to an attribute on the plugin HTML. For example, in the form plugin, the form attribute sets the form attribute in the plugin HTML. |
More on Attributes
Attributes are the primary means to pass data from the user to the plugin. They can pass plain text or specify the name of the form, gallery, or page to be used by the plugin.
| Setting | Description |
|---|---|
| attr | The name of the HTML attribute to be set on the plugin. |
| label | The label for the field shown in the configure element modal |
| type | This can be set to text or select to show a text field or select field. |
| values (if select is set as type) | An array of values to be added on the select list. This can be a simple array of strings (e.g. ['Option 1','Option 2','Option 3']) or can be set as ['respond.forms'], ['respond.galleries'], ['respond.routes'], or ['respond.pages']. These special values automatically populate the select box with items created in Respond. |
Plugin Structure
Plugins can be a simple as creating plain HTML. In fact, you can just specify the HTML in the plugins.json file. However, to get the full power of accessing Respond data, you need to use TWIG templates. The Twig templates allow you to access data in the system. An example of the form plugin is shown below.
{% spaceless %}
{% for form in forms %}
{% if form.id == attributes.form %}
<form id="{{ form.id }}" action="{{ site.api }}" data-site="{{ site.id }}" respond-form>
{% for field in form.fields %}
<div class="form-group" data-id="{{ field.id }}" data-label="{{ field.label }}" data-type="{{ field.type }}" data-required="{{ field.required }}">
<label for="{{ field.id }}" class="control-label">{{ field.label }}</label>
{% if field.type == 'text' %}
<input id="{{ field.id }}" name="{{ field.id }}" type="text" placeholder="{{ field.placeholder }}" class="form-control">
{% endif %}
{% if field.type == 'textarea' %}
<textarea id="{{ field.id }}" name="{{ field.id }}" placeholder="{{ field.placeholder }}" class="form-control"></textarea>
{% endif %}
{% if field.type == 'select' %}
{% set options = field.options|split(',') %}
<select id="{{ field.id }}" name="{{ field.id }}" class="form-control">
{% for option in options %}
<option value="{{ option }}">{{ option }}</option>
{% endfor %}
</select>
{% endif %}
{% if field.type == 'checkboxlist' %}
{% set options = field.options|split(',') %}
<span class="radio list">
{% for option in options %}
<label class="radio"><input name="{{ field.id }}" type="checkbox" value="{{ option }}"><span>{{ option }}</span></label>
{% endfor %}
</span>
{% endif %}
{% if field.type == 'radiolist' %}
{% set options = field.options|split(',') %}
<span class="checkbox list">
{% for option in options %}
<label class="checkbox"><input name="{{ field.id }}" type="radio" value="{{ option }}"><span>{{ option }}</span></label>
{% endfor %}
</span>
{% endif %}
{% if field.helperText != '' %}
<span class="help-block">{{ field.helperText }}</span>
{% endif %}
</div>
{% endfor %}
{% endif %}
{% endfor %}
<button type="submit" class="btn btn-primary">Submit</button>
<span class="loading">
<!-- ack: https://github.com/jxnblk/loading -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><g><path opacity=".25" d="M16 0 A16 16 0 0 0 16 32 A16 16 0 0 0 16 0 M16 4 A12 12 0 0 1 16 28 A12 12 0 0 1 16 4"/><path d="M16 0 A16 16 0 0 1 32 16 L28 16 A12 12 0 0 0 16 4z"><animateTransform attributeName="transform" type="rotate" from="0 16 16" to="360 16 16" dur="0.8s" repeatCount="indefinite" /></path></g></svg>
</span>
<span class="success">Form submitted successfully</span>
<span class="error">There was an error submitting your form</span>
</form>
{% endspaceless %}
Form Data
Forms are created in the Forms UI in Respond. The following data is passed into the forms array passed to your plugin.
| Setting | Description |
|---|---|
| id | The ID of the created form. |
| name | The name of the form. |
| cssClass | This CSS class of the form. |
| fields | An array of fields created on the form. |
Fields contain the following information.
| Setting | Description |
|---|---|
| id | The ID of field |
| label | The label of the field. |
| type | This type of the field (text, textarea, select, checkboxlist, radiolist) |
| required | Set to "true" or "false" if the field is required. |
| options | A comma separated list of options available to the select, checkboxlist or radiolist types. |
| helperText | Any helper text set on the form field. |
| placeholder | The placeholder text set on text fields. |
| cssClass | The CSS class for the field. |
Gallery Data
Galleries are created in the Galleries UI in Respond. The following data is passed into the galleries array passed to your plugin.
| Setting | Description |
|---|---|
| id | The ID of the created gallery. |
| name | The name of the gallery. |
| images | An array of images created on the gallery. |
Images contain the following information.
| Setting | Description |
|---|---|
| id | The generated id for the image. |
| name | The filename of the image. |
| url | The relative URL to the image. |
| thumb | The relative URL to the thumb of the image. |
| caption | A user-specified caption for the image. |
Menu Data
Menus are created in the Menus UI in Respond. The following data is passed into the menus array passed to your plugin.
| Setting | Description |
|---|---|
| id | The ID of the created menu. |
| name | The name of the menu. |
| items | An array of menu items created on the menu. |
The items contain the following information.
| Setting | Description |
|---|---|
| cssClass | The css class for the menu item |
| isNested | Set to "true" or "false" as to whether the menu item is nested in the parent. |
| html | The HTML to be displayed in the menu item label. |
| url | The relative URL to which the menu item is linked. |
Pages Data
Pages are created in the Pages UI in Respond. The following data is passed into the pages array passed to your plugin.
| Setting | Description |
|---|---|
| title | The title of the page. |
| description | The description of the page. |
| text | Plain text for the main content in the page. |
| html | The HTML for the main content in the page. |
| keywords | Keywords for the page. |
| callout | Callout text for the page. |
| url | The relative URL of the page. |
| photo | The relative photo URL for the first image in the main content of the page. |
| thumb | The relative thumb URL for the first image in the main content of the page. |
| language | The language of the page. |
| direction | The direction (rtl or ltr) of text on the page. |
| firstName | The first name of the last user to modify the page. |
| lastName | The last name of the last user to modify the page. |
| lastModifiedBy | The email of the last user to modify the page. |
| lastModifiedDate | The date of the last modification to the page (e.g. 2016-06-09T19:49:27.0Z). |
Current Page Data
The following data is passed into the page array passed to your plugin. It contains information about the current page.
| Setting | Description |
|---|---|
| title | The title of the page. |
| description | The description of the page. |
| keywords | Keywords for the page. |
| callout | Callout text for the page. |
| url | The relative URL of the page. |
| photo | The relative photo URL for the first image in the main content of the page. |
| thumb | The relative thumb URL for the first image in the main content of the page. |
| language | The language of the page. |
| direction | The direction (rtl or ltr) of text on the page. |
| firstName | The first name of the last user to modify the page. |
| lastName | The last name of the last user to modify the page. |
| lastModifiedBy | The email of the last user to modify the page. |
| lastModifiedDate | The date of the last modification to the page (e.g. 2016-06-09T19:49:27.0Z). |
Products Data
Products are created in the Products UI in Respond. The following data is passed into the products array passed to your plugin.
| Setting | Description |
|---|---|
| id | The ID of the created product. |
| name | The name of the product. |
| url | The url of the product. |
| description | The description of the product. |
| shipped | Whether the product is shipped (true or false). |
| subscription | Whether the product is a subscription (true or false). |
| price | The price of the product |
| images | The images of the product (attributes: id, name, url, thumb, caption) |
Current Site Data
The following data is passed into the site array passed to your plugin. It contains information about the current site.
| Setting | Description |
|---|---|
| id | The unique id (also the folder name) for the site. |
| name | The name of the site (when created). |
| The primary email of the site. | |
| api | The URL to the API for the app. |