• Document Up to Date
  • Updated On 4.0.3

CrafterCMS Plugin Descriptor

The craftercms-plugin.yaml file contains information for use in CrafterCMS. This descriptor file contains information about your extension, such as the license, the versions of CrafterCMS supported, and other configurations and metadata. In this section, we’ll take a look at a plugin descriptor file.

Sample plugin descriptor file
 1# This file describes a plugin for use in CrafterCMS
 2
 3# The version of the format for this file
 4descriptorVersion: 2
 5
 6# Describe the plugin
 7plugin:
 8  type: site
 9  id: org.craftercms.plugin.test
10  name: Project Plugin Example
11  tags:
12    - test
13  version:
14    major: 3
15    minor: 0
16    patch: 1
17  description: A simple example for project plugins
18  documentation: "https://raw.githubusercontent.com/craftercms/site-plugin-example/master/readme.md"
19  website:
20    name: Plugin Example
21    url: https://github.com/craftercms/site-plugins-example
22  media:
23    screenshots:
24      - title: CrafterCMS
25        description: CrafterCMS Example Plugin
26        url: "https://raw.githubusercontent.com/craftercms/site-plugin-example/master/.crafter/screenshots/default.png"
27  developer:
28    company:
29      name: CrafterCMS
30      email: info@craftercms.com
31      url: https://craftercms.com
32  license:
33    name: MIT
34    url: https://opensource.org/licenses/MIT
35  crafterCmsVersions:
36    - major: 4
37      minor: 0
38      patch: 0
39  crafterCmsEditions:
40    - community
41    - enterprise
42  # Option auto-wiring section
43  # installation:

Here are some things to note in the descriptor file:

Descriptor file fields
Field Required Description
descriptorVersion ✓ The version of the format for this file which is currently 2
plugin.type ✓ Set the value to site
plugin.id ✓ A unique Id that is meaningful/recognizable to people who will be using the plugin
plugin.name ✓ The name displayed in the Crafter Marketplace.
Pick a unique name for your plugin. You can check in the Crafter Marketplace if
the name you picked does not exist yet. It’s also a best practice to provide a name
for your plugin that is meaningful or recognizable to users.
The name can be multiple words such as Contact Form
plugin.version ✓ The version number for the plugin
plugin.description   Contains a short description of the plugin and is displayed underneath the plugin name in
the Crafter Marketplace
plugin.documentation   Serves as the help block for the plugin. It contains a URL to the plugin’s documentation file
(must be in Markdown) containing information on how to use/configure the plugin. The documentation
will appear alongside the plugin in Crafter Studio and the Crafter Marketplace
plugin.website.url   Can be a page for more information on your plugin or for announcing updates, reporting bugs, etc.
from your user community.
plugin.media.url   The path to look for a representative image of the plugin.
CrafterCMS uses a default path for CrafterCMS to look for a default representative image of a plugin,|br| the url ../.crafter/screenshots/.
plugin.license   The license supported by the plugin
plugin.crafterCmsVersions ✓ Contains the CrafterCMS version/s that the plugin is compatible with
(look in the Release Notes section for the versions available), and you’ll need to keep
this up to date

Note

For the images to be used for the screenshots in the craftercms-plugin.yaml file, we recommend using images with approximately a 4:3 aspect ratio (width to height), such as an image sized at 1200x800

Auto-wiring

CrafterCMS supports automatically wiring your plugin to the corresponding configuration file in Studio during your plugin installation.

To setup a plugin to be automatically wired in the corresponding configuration file in Studio (for example, a form control, will be wired to the Content Type Editor Configuration file) during the installation, add the following to your craftercms-plugin.yaml descriptor file

Setup auto-wiring to Studio in descriptor file
 1installation:
 2 - type: preview-app
 3   parentXpath: //widget[@id='craftercms.components.ToolsPanel']
 4   elementXpath: //plugin[@id='org.craftercms.sampleComponentLibraryPlugin.components.reactComponent']
 5   element:
 6     name: configuration
 7     children:
 8     - name: widgets
 9       children:
10       - name: widget
11         attributes:
12         - name: id
13           value: org.craftercms.sampleComponentLibraryPlugin.components.reactComponent
14         children:
15         - name: plugin
16           attributes:
17           - name: id
18             value: org.craftercms.plugin.sidebar
19           - name: type
20             value: sidebar
21           - name: name
22             value: react-sample
23           - name: file
24             value: index.modern.js

where:

  • installation.type is the type of plugin for auto-wiring in Studio. Available values are form-control, form-datasource, preview-app, site-filter and site-context
  • installation.parentXpath is an XPath selector for the element where the plugin will be added, required when installation-type is preview-app
  • installation.elementXpath is an XPath selector to check if the plugin is already present in the configuration and used to remove the config when the plugin is uninstalled
  • installation.element.name is the element name to be wired in your project configuration file so the plugin will show up in Studio Available values are control (for form-control installation type), datasource (for form-datasource installation type) and for preview-app installation type, the start of the section the plugin needs to be inserted in, e.g. configuration, etc.
  • installation.element.children contains any number of name and children describing your plugin, such as the icon to be used by your plugin if applicable, or the plugin location, where:
    • name is the name of what’s being described, e.g. plugin or icon
    • children contains any number of name and value and can contain the class (icon), plugin id, plugin type, plugin name and plugin files/folders (plugin location) and its corresponding values

Below are examples on how to setup auto-wiring in Studio for various plugin types:

Below is a sample auto-wiring setup for a form control.

Example installation for a form-control
 1installation:
 2  - type: form-control
 3    elementXpath: //control/plugin[pluginId='org.craftercms.plugin.control']
 4    element:
 5      name: control
 6      children:
 7        - name: plugin
 8          children:
 9            - name: pluginId
10              value: org.craftercms.plugin.control
11            - name: type
12              value: control
13            - name: name
14              value: text-input
15            - name: filename
16              value: main.js
17        - name: icon
18          children:
19            - name: class
20              value: fa-pencil-square-o

See here for examples of plugins auto-wired in Studio.