Crafter Studio Plugin Examples

Crafter Studio supports several types of authoring plugins. UI widget plugins add React components to extension points in the Studio interface. Form Engine control plugins add custom input controls to content types. Form Engine data source plugins add custom data pickers that controls use to retrieve content.

This article walks through creating each type of plugin and wiring it into Studio.

Here’s a list of the plugin examples described in this article:

Plugin Type	Plugin type	Where it appears
Sidebar	sidebar	The panel on the left of Studio
Experience Builder Panel	experiencebuilder	The panel on the right of Studio, shown in Edit/Move mode
Toolbar	toolbar	The fixed bar at the top of Studio
Dashboard	dashboard	A dashlet on the project dashboard
Project Tools	project-tool	A tool under
Navigation Menu	navmenu	A tile in the Navigation Menu (Launcher)
Form Engine Control	control	A control in the Content Type Editor
Form Engine Data Source	datasource	A data source in the Content Type Editor

All the examples below use a project called My Editorial created using the Website Editorial blueprint.

---

Studio UI Widget Plugins

Creating Your Studio UI Widget Plugin

Here are the steps for creating your Studio UI widget plugin:

1. Create the folder structure

2. Create the plugin’s JavaScript file

3. Auto-wire the plugin

4. Install the plugin

5. See it in action

The steps are identical for every UI widget location. The only two things that change are the plugin type (which is also the CATEGORY directory) and the installation block that positions the widget. Both of those are provided in the Positioning the Widget in the UI section for your target location.

1. Create the folder structure.
   We’ll follow the convention listed in UI Plugin Directory Structure, {PLUGIN_DIRECTORY}/authoring/static-assets/plugins/{ID}/{CATEGORY}/{NAME}/, where CATEGORY is the plugin type for your target location and NAME is your plugin name.

   In a local folder, create the descriptor file craftercms-plugin.yaml and set plugin.id (for example, org.craftercms.plugin.exampleui), then create the directory structure. See the target location’s section below for the exact CATEGORY/NAME and a concrete tree.

2. Create the plugin’s JavaScript file.
   Follow the instructions in the plugin example here, which will generate the index.js file.

   Inside the {NAME} folder, create two empty files, index.css and script.js, and place the index.js file in it.

3. Auto-wire the plugin.
   To have the plugin automatically wired into the corresponding configuration file in Studio (for all these UI locations, that is the User Interface Configuration file) during installation, add an installation block to your craftercms-plugin.yaml descriptor file. The parentXpath and element differ by location — use the snippet from your target location’s section below.

   Note

   Remember to use the same value used in plugin.id (found at the top of the descriptor file) for the installation section plugin id.

   See here for more information on how auto-wiring works and what each field in the installation block means.

4. Install the plugin.
   After placing your plugin files and setting up auto-wiring, install the plugin for testing/debugging using the crafter-cli command copy-plugin.

   When running a crafter-cli command, the connection to CrafterCMS needs to be setup via the add-environment command. Once the connection has been established, install the plugin to the project my-editorial by running the following (adjust the --path to point at your plugin folder):

   ./crafter-cli copy-plugin -e local -s my-editorial --path /users/myuser/myplugins/<plugin-folder>
   

5. See it in action.
   Reload Studio and open the relevant part of the UI. The exact place to look, along with the resulting auto-wired configuration, is shown in your target location’s section below.

---

Positioning the Widget in the UI

Each section below provides the location-specific pieces for the process above: the plugin type, the directory structure, the installation auto-wiring block, where to see the widget in action, and the resulting section in the User Interface Configuration file after installation.

Sidebar

The Sidebar is the panel located on the left side of Studio, containing the Dashboard, path navigators such as Pages and Components, and .

For this example, the plugin type (CATEGORY) is sidebar, the NAME is react-sample, and the plugin.id is org.craftercms.plugin.examplesidebar.

Sidebar Plugin Directory Structure

<plugin-folder>/
  craftercms-plugin.yaml
  authoring/
    static-assets/
      plugins/
        org/
          craftercms/
            plugin/
              examplesidebar/
                sidebar/
                  react-sample/

Add the following installation block to your craftercms-plugin.yaml descriptor file:

craftercms-plugin.yaml

installation:
  - type: preview-app
    parentXpath: //widget[@id='craftercms.components.ToolsPanel']
    elementXpath: //plugin[@id='org.craftercms.sampleSidebarPlugin.components.reactComponent']
    element:
      name: configuration
      children:
      - name: widgets
        children:
        - name: widget
          attributes:
          - name: id
            value: org.craftercms.sampleSidebarPlugin.components.reactComponent
          children:
          - name: plugin
            attributes:
            - name: id
              value: org.craftercms.plugin.examplesidebar
            - name: type
              value: sidebar
            - name: name
              value: react-sample
            - name: file
              value: index.js

To see the plugin in action, click on the CrafterCMS logo at the top left of your browser to open the sidebar:

Here’s the auto-wired section in the configuration after installing the plugin:

<siteUi>
  <widget id="craftercms.components.ToolsPanel">
    <configuration>
    <widgets>
      <widget id="craftercms.components.ToolsPanelEmbeddedAppViewButton">
         <configuration>
            <title id="words.dashboard" defaultMessage="Dashboard"/>
            <icon id="@mui/icons-material/DashboardRounded"/>
            <widget id="craftercms.components.Dashboard"/>
         </configuration>
      </widget>
      <widget id="craftercms.components.ToolsPanelPageButton">
         <configuration>
            <title id="previewSiteExplorerPanel.title" defaultMessage="Site Explorer"/>
            <icon id="craftercms.icons.SiteExplorer"/>
         ...
      </widget>
      <widget id="craftercms.components.ToolsPanelPageButton">
         <permittedRoles>
            <role>admin</role>
            <role>developer</role>
         </permittedRoles>
         <configuration>
            <title id="siteTools.title" defaultMessage="Project Tools"/>
            <icon id="@mui/icons-material/TuneRounded"/>
            <widgets>
               <widget id="craftercms.components.SiteToolsPanel"/>
            </widgets>
         </configuration>
      </widget>
      <widget id="org.craftercms.sampleSidebarPlugin.components.reactComponent">
         <plugin id="org.craftercms.plugin.examplesidebar"
                 type="sidebar"
                 name="react-sample"
                 file="index.js"/>
      </widget>
    </widgets>
  </configuration>
</widget>
...

Experience Builder Panel

The Experience Builder panel is the panel on the right of Studio that is enabled by clicking on Edit mode (pencil icon) or Move mode (two vertical ellipsis icon) on the top right of Studio, or by hitting the e or m key on your keyboard.

For this example, the plugin type (CATEGORY) is experiencebuilder, the NAME is test-experiencebuilder, and the plugin.id is org.craftercms.plugin.exampleexperiencebuilder.

Experience Builder Plugin Directory Structure

<plugin-folder>/
  craftercms-plugin.yaml
  authoring/
    static-assets/
      plugins/
        org/
          craftercms/
            plugin/
              exampleexperiencebuilder/
                experiencebuilder/
                  test-experiencebuilder/

Add the following installation block to your craftercms-plugin.yaml descriptor file:

craftercms-plugin.yaml

installation:
  - type: preview-app
    parentXpath: //widget[@id='craftercms.components.ICEToolsPanel']
    elementXpath: //plugin[@id='org.craftercms.sampleExperienceBuilderPlugin.components.reactComponent']
    element:
      name: configuration
      children:
      - name: widgets
        children:
        - name: widget
          attributes:
          - name: id
            value: org.craftercms.sampleExperienceBuilderPlugin.components.reactComponent
          children:
          - name: plugin
            attributes:
            - name: id
              value: org.craftercms.plugin.exampleexperiencebuilder
            - name: type
              value: experiencebuilder
            - name: name
              value: test-experiencebuilder
            - name: file
              value: index.js

To see the plugin in action, click on the pencil icon at the top right of your browser to open the Experience Builder panel:

Here’s the auto-wired section in the configuration after installing the plugin:

<siteUi>
  ...
  <widget id="craftercms.components.ICEToolsPanel">
    <configuration>
      <widgets>
        <widget id="craftercms.components.ToolsPanelPageButton">
          <configuration>
            <target id="icePanel"/>
            <title id="previewSearchPanel.title" defaultMessage="Search"/>
            <icon id="@mui/icons-material/SearchRounded"/>
            <widgets>
              <widget id="craftercms.components.PreviewSearchPanel"/>
            </widgets>
          </configuration>
        </widget>
        ...
        <widget id="org.craftercms.sampleExperienceBuilderPlugin.components.reactComponent">
          <plugin id="org.craftercms.plugin.exampleexperiencebuilder"
                  type="experiencebuilder"
                  name="test-experiencebuilder"
                  file="index.js"/>
        </widget>
       </widgets>
    </configuration>
   </widget>
   ...

Toolbar

The toolbar is a fixed element at the top of Studio. It provides contextual workflow and other options relative to the page you are looking at, content you have selected, or tool you are using.

For this example, the plugin type (CATEGORY) is toolbar, the NAME is test-toolbar, and the plugin.id is org.craftercms.plugin.exampletoolbar.

Toolbar Plugin Directory Structure

<plugin-folder>/
  craftercms-plugin.yaml
  authoring/
    static-assets/
      plugins/
        org/
          craftercms/
            plugin/
              exampletoolbar/
                toolbar/
                  test-toolbar/

Add the following installation block to your craftercms-plugin.yaml descriptor file. Note that a toolbar widget is wired into one of the toolbar’s sections (leftSection, middleSection, or rightSection); this example uses rightSection:

craftercms-plugin.yaml

installation:
  - type: preview-app
    parentXpath: //widget[@id='craftercms.components.PreviewToolbar']
    elementXpath: //plugin[@id='org.craftercms.sampleToolbarPlugin.components.reactComponent']
    element:
      name: configuration
      children:
      - name: rightSection
        children:
        - name: widgets
          children:
          - name: widget
            attributes:
            - name: id
              value: org.craftercms.sampleToolbarPlugin.components.reactComponent
            children:
            - name: plugin
              attributes:
              - name: id
                value: org.craftercms.plugin.exampletoolbar
              - name: type
                value: toolbar
              - name: name
                value: test-toolbar
              - name: file
                value: index.js

To see the plugin in action, refresh your browser:

Here’s the auto-wired section in the configuration after installing the plugin:

<siteUi>
...
  <widget id="craftercms.components.PreviewToolbar">
    <configuration>
      <leftSection>
        <widgets>
          <widget id="craftercms.components.SiteSwitcherSelect"/>
          <widget id="craftercms.components.QuickCreate"/>
        </widgets>
      </leftSection>
      <middleSection>
        <widgets>
          <widget id="craftercms.components.PreviewAddressBar"/>
        </widgets>
      </middleSection>
      <rightSection>
        <widgets>
          <widget id="craftercms.components.EditModesSwitcher"/>
          <widget id="craftercms.components.PublishingStatusButton">
            <configuration>
              <variant>icon</variant>
            </configuration>
          </widget>
          <widget id="craftercms.components.WidgetDialogIconButton">
            <configuration>
              <title id="words.search" defaultMessage="Search"/>
              <icon id="@mui/icons-material/SearchRounded"/>
              <widget id="craftercms.components.EmbeddedSearchIframe"/>
            </configuration>
          </widget>
          <widget id="org.craftercms.sampleToolbarPlugin.components.reactComponent">
            <plugin id="org.craftercms.plugin.exampletoolbar"
                    type="toolbar"
                    name="test-toolbar"
                    file="index.js"/>
          </widget>
        </widgets>
      </rightSection>
    </configuration>
  </widget>
  ...

Dashboard

The dashboard contains different dashlets that show, at a glance, all items currently in workflow, all items recently modified by the current user, etc. Dashlets shown vary depending on the user’s role. For more information on the Dashboard, see here.

For this example, the plugin type (CATEGORY) is dashboard, the NAME is test-dashboard, and the plugin.id is org.craftercms.plugin.exampledashboard.

Dashboard Plugin Directory Structure

<plugin-folder>/
  craftercms-plugin.yaml
  authoring/
    static-assets/
      plugins/
        org/
          craftercms/
            plugin/
              exampledashboard/
                dashboard/
                  test-dashboard/

Add the following installation block to your craftercms-plugin.yaml descriptor file:

craftercms-plugin.yaml

installation:
  - type: preview-app
    parentXpath: /siteUi/widget[@id='craftercms.components.Dashboard']
    elementXpath: //plugin[@id='org.craftercms.sampleDashboardPlugin.components.reactComponent']
    element:
      name: configuration
      children:
      - name: widgets
        children:
        - name: widget
          attributes:
          - name: id
            value: org.craftercms.sampleDashboardPlugin.components.reactComponent
          children:
          - name: plugin
            attributes:
            - name: id
              value: org.craftercms.plugin.exampledashboard
            - name: type
              value: dashboard
            - name: name
              value: test-dashboard
            - name: file
              value: index.js

To see the plugin in action, click on the CrafterCMS logo at the top left of your browser to open the sidebar, then click on Dashboard:

You may also open the Dashboard anywhere via the Launcher, which is opened by clicking the apps icon on the top right:

Here’s the auto-wired section in the configuration after installing the plugin:

<siteUi>
  ...
  <widget id="craftercms.components.Dashboard">
    <configuration>
      <widgets>
        <widget id="craftercms.components.AwaitingApprovalDashlet">
          <permittedRoles>
            <role>admin</role>
            <role>developer</role>
            <role>publisher</role>
          </permittedRoles>
        </widget>
        ...
        <widget id="org.craftercms.sampleDashboardPlugin.components.reactComponent">
          <plugin id="org.craftercms.plugin.exampledashboard"
                  type="dashboard"
                  name="test-dashboard"
                  file="index.js"/>
        </widget>
        ...

Project Tools

contains tools that project administrators use for daily activities. For more information on the available tools in , see Navigating Project Tools.

For this example, the plugin type (CATEGORY) is project-tool, the NAME is test-project-tools, and the plugin.id is org.craftercms.plugin.exampleprojecttools.

Project Tools Plugin Directory Structure

<plugin-folder>/
  craftercms-plugin.yaml
  authoring/
    static-assets/
      plugins/
        org/
          craftercms/
            plugin/
              exampleprojecttools/
                project-tool/
                  test-project-tools/

Add the following installation block to your craftercms-plugin.yaml descriptor file:

craftercms-plugin.yaml

installation:
  - type: preview-app
    parentXpath: //reference[@id='craftercms.siteTools']
    elementXpath: //plugin[@id='org.craftercms.sampleProjectToolsPlugin.components.reactComponent']
    element:
      name: tools
      children:
      - name: tool
        children:
        - name: title
          attributes:
          - name: id
            value: "test.projecttool"
          - name: defaultMessage
            value: "Test Adding Project Tool"
        - name: icon
          attributes:
          - name: id
            value: "@mui/icons-material/WidgetsOutlined"
        - name: url
          value: test
        - name: widget
          attributes:
          - name: id
            value: org.craftercms.sampleProjectToolsPlugin.components.reactComponent
          children:
          - name: plugin
            attributes:
            - name: id
              value: org.craftercms.plugin.exampleprojecttools
            - name: type
              value: project-tool
            - name: name
              value: test-project-tools
            - name: file
              value: index.js

To see the plugin in action, click on the CrafterCMS logo at the top left of your browser to open the sidebar, then click on Project Tools:

Here’s the auto-wired section in the configuration after installing the plugin:

<siteUi>
  ...
  <references>
    <reference id="craftercms.siteTools">
      <tools>
        ...
        <tool>
          <title id="PluginManagement.title" defaultMessage="Plugin Management"/>
          <icon id="@mui/icons-material/ExtensionOutlined"/>
          <url>plugins</url>
          <widget id="craftercms.components.PluginManagement"/>
        </tool>
        <tool>
          <title id="test.sitetool" defaultMessage="Test Adding Project Tool"/>
          <icon id="@mui/icons-material/WidgetsOutlined"/>
          <url>test</url>
          <widget id="org.craftercms.sampleProjectToolsPlugin.components.reactComponent">
             <plugin id="org.craftercms.plugin.exampleprojecttools"
                     type="project-tool"
                     name="test-project-tools"
                     file="index.js"/>
          </widget>
        </tool>
      </tools>
    ...

Navigation Menu

The Navigation Menu (Launcher) contains tools that are used for daily activities by users. For more information on the Navigation Menu, see here.

For this example, the plugin type (CATEGORY) is navmenu, the NAME is test-navmenu, and the plugin.id is org.craftercms.plugin.examplenavmenu.

Navigation Menu Plugin Directory Structure

<plugin-folder>/
  craftercms-plugin.yaml
  authoring/
    static-assets/
      plugins/
        org/
          craftercms/
            plugin/
              examplenavmenu/
                navmenu/
                  test-navmenu/

Add the following installation block to your craftercms-plugin.yaml descriptor file:

craftercms-plugin.yaml

installation:
  - type: preview-app
    parentXpath: //widget[@id='craftercms.components.Launcher']
    elementXpath: //plugin[@id='org.craftercms.sampleNavMenuPlugin.components.reactComponent']
    element:
      name: configuration
      children:
      - name: widgets
        children:
        - name: widget
          children:
          - name: configuration
            children:
            - name: widgets
              children:
              - name: widget
                attributes:
                - name: id
                  value: org.craftercms.sampleNavMenuPlugin.components.reactComponent
                children:
                - name: plugin
                  attributes:
                  - name: id
                    value: org.craftercms.plugin.examplenavmenu
                  - name: type
                    value: navmenu
                  - name: name
                    value: test-navmenu
                  - name: file
                    value: index.js

To see the plugin in action, click on the Navigation Menu icon on the top right:

Here’s the auto-wired section in the configuration after installing the plugin:

<siteUi>
  ...
  <widget id="craftercms.components.Launcher">
    <configuration>
      <widgets>
        <widget id="craftercms.components.LauncherSection">
          <configuration>
            <title id="launcher.siteSectionTitle">
              <defaultMessage><![CDATA[
                                     Site <muted>• {siteName}</muted>]]></defaultMessage>
            </title>
            <widgets>
              <widget id="craftercms.components.LauncherLinkTile">
                <configuration>
                  <title id="words.dashboard" defaultMessage="Dashboard"/>
                  <systemLinkId>siteDashboardDialog</systemLinkId>
                  <icon id="@mui/icons-material/DashboardRounded"/>
                </configuration>
              </widget>
              ...
              <widget id="craftercms.components.LauncherPublishingStatusTile"/>
              <widget id="org.craftercms.sampleNavMenuPlugin.components.reactComponent">
                <plugin id="org.craftercms.plugin.examplenavmenu"
                        type="navmenu"
                        name="test-navmenu"
                        file="index.js"/>
              </widget>
              ...

---

Form Engine Control and Data Source

Crafter Studio allows plugins for Form Engine controls and data sources through the getPluginFile API found here.

Form Engine controls (#4 in the image above) are UX elements that help authors capture and edit content and metadata properties. Form Engine data sources (#5) are swappable components that controls delegate to for retrieving the content authors select. Controls should be written independently of the data they capture so they can be reused across a wide range of data sets.

The process for creating and installing a Form Engine plugin is the same for controls and data sources:

1. Create the folder structure and craftercms-plugin.yaml descriptor file

2. Implement the JavaScript interface in main.js

3. Add an installation block to auto-wire the plugin

4. Install the plugin with crafter-cli copy-plugin

5. Verify the plugin in the Content Type Editor

The only differences are the JavaScript interface, directory CATEGORY (control vs datasource), installation block, and the section of site-config-tools.xml where the plugin is registered. Both are covered below.

Form Engine Control Plugin

What is a Control

A form control is a UX element to help authors capture and edit content and metadata properties. Crafter Studio form controls should be written in a way that makes them independent of the data they allow the user to select so that they can be (re)used across a wide range of data sets.

Out of the box controls are:

Control	Description
	Create a new section in the form, this is to help the content authors by segmenting a form into sections of similar concern. Details are in the Form Section Control page.
	Repeating groups are used when the form has one or several controls that repeat to capture the same data as records. For example: a list of images in a carousel, or a list of widgets on a page. Details are in the Repeating Group Control page.
	A simple textual input line. Details are in the Input Control page.
	A simple numeric input line. Details are in the Numeric Input Control page.
	A simple block of plain text. Details are in the Text Area Control page.
	A block of HTML. Details are in the Rich Text Editor Control page.
	Dropdown list of items to pick from. Details are in the Dropdown Control page.
	Date and Time field with a picker. Details are in the Date/Time Control page.
	Time field with a picker. Details are in the Time Control page.
	True/False checkbox. Details are in the Checkbox Control page.
	Several checkboxes (true/false). Details are in the Grouped Checkboxes Control page.
	Item selector from a Data Source. Details are in the Item Selector Control page.
	Image selector from a Data Source. Details are in the Image Control page.
	Video selector from a Data Source. Details are in the Video Control page.
	Transcoded Video selector from Video Transcoding Data Source. Details are in the Transcoded Video Control page.
	Displays text. Details are in the Label Control page.
	Allows changing the page order. Details are in the Page Order Control page.
	A simple text filename. Details are in the Filename Control page.
	Details are in the Auto Filename Control page.
	Details are in the Internal Name Control page.
	Details are in the Locale Selector Control page.

The anatomy of a Control Project Plugin

Form Engine Control consist of (at a minimum)

• A single JavaScript file which implements the control interface.

  • The JS file name and the control name in the configuration does not need to be the same. The JS file name can be any meaningful name, different from the control name in the configuration.

• Configuration in a Crafter Studio project to make that control available for use

Control Interface

/**
 * Constructor: Where .X is substituted with your class name
 * ID is the variable name
 * FORM is the form object
 * OWNER is the parent section/form
 * PROPERTIES is the collection of configured property values
 * CONSTRAINTS is the collection of configured constraint values
 * READONLY is a true/false flag indicating re-only mode
 */
CStudioForms.Controls.X = CStudioForms.Controls.X ||
function(id, form, owner, properties, constraints, readonly)  { }

YAHOO.extend(CStudioForms.Controls.X, CStudioForms.CStudioFormField, {

  /**
   * Return a user friendly name for the control (will show up in content type builder UX)
   */
  getLabel: function() { },

  /**
   * method is called by the engine when the value of the control is changed
   */
  _onChange: function(evt, obj) { },

  /**
   * method is called by the engine to invoke the control to render. The control is responsible for creating and managing its own HTML.
   * CONFIG is a structure containing the form definition and other control configuration
   * CONTAINER EL is the containing element the control is to render in to.
   */
  render: function(config, containerEl) { },

   /**
    * returns the current value of the control
    */
   getValue: function() { },

   /**
    * sets the value of the control
    */
   setValue: function(value) { },

   /**
    * return a string that represents the kind of control (this is the same as the file name)
    */
   getName: function() {  },

   /**
    * return a list of properties supported by the control.
    * properties is an array of objects with the following structure { label: "", name: "", type: "" }
    */
   getSupportedProperties: function() { },

   /**
    * return a list of constraints supported by the control.
    * constraints is an array of objects with the following structure { label: "", name: "", type: "" }
    */
   getSupportedConstraints: function() { }
});

Control Plugin Directory and Example

When creating control plugins, the JS file goes in the following location:

authoring/static-assets/plugins/{yourPluginId}/control/{yourPluginName}/JS_FILE.js

where {yourPluginName} is the name of the form engine control plugin and JS_FILE.js is the JavaScript file containing the control interface implementation.

Let’s take a look at an example of a control plugin. We will be adding a control named text-input to My Editorial.

For this example, the plugin.id is org.craftercms.plugin.excontrol, the CATEGORY is control, the NAME is text-input, and the JS file is main.js.

Form Engine Control Plugin Directory Structure

<plugin-folder>/
  craftercms-plugin.yaml
  authoring/
    static-assets/
      plugins/
        org/
          craftercms/
            plugin/
              excontrol/
                control/
                  text-input/
                    main.js

For our example, the <plugin-folder> is located here: /users/myuser/myplugins/form-control-plugin

In the JS file, please note that the CStudioAuthoring.Module is required and that the prefix for CStudioAuthoring.Module.moduleLoaded must be the name of the control. For our example, the prefix is text-input as shown in the example.

authoring/static-assets/plugins/org/craftercms/plugin/excontrol/control/text-input/main.js

CStudioForms.Controls.textInput = CStudioForms.Controls.textInput ||
function(id, form, owner, properties, constraints, readonly)  {
    this.owner = owner;
    this.owner.registerField(this);
    this.errors = [];
    this.properties = properties;
    this.constraints = constraints;
    this.inputEl = null;
    this.patternErrEl = null;
    this.countEl = null;
    this.required = false;
    this.value = "_not-set";
    this.form = form;
    this.id = id;
    this.readonly = readonly;

    return this;
}

YAHOO.extend(CStudioForms.Controls.textInput, CStudioForms.CStudioFormField, {

    getLabel: function() {
        return CMgs.format(langBundle, "Text Input");
    },
    .
    .
    .

    getName: function() {
            return "text-input";
    },

    getSupportedProperties: function() {
        return [
                { label: CMgs.format(langBundle, "displaySize"), name: "size", type: "int", defaultValue: "50" },
                { label: CMgs.format(langBundle, "maxLength"), name: "maxlength", type: "int",  defaultValue: "50" },
                { label: CMgs.format(langBundle, "readonly"), name: "readonly", type: "boolean" },
                { label: "Tokenize for Indexing", name: "tokenize", type: "boolean",  defaultValue: "false" }
        ];
    },

    getSupportedConstraints: function() {
        return [
                { label: CMgs.format(langBundle, "required"), name: "required", type: "boolean" },
                { label: CMgs.format(langBundle, "matchPattern"), name: "pattern", type: "string" },
        ];
    }

});

CStudioAuthoring.Module.moduleLoaded("text-input", CStudioForms.Controls.textInput);

Here’s the complete example form control plugin file for the text-input control (click on the triangle on the left to expand/collapse):

Sample form control plugin file "main.js".

CStudioForms.Controls.textInput = CStudioForms.Controls.textInput ||
    function(id, form, owner, properties, constraints, readonly)  {
        this.owner = owner;
        this.owner.registerField(this);
        this.errors = [];
        this.properties = properties;
        this.constraints = constraints;
        this.inputEl = null;
        this.patternErrEl = null;
        this.countEl = null;
        this.required = false;
        this.value = "_not-set";
        this.form = form;
        this.id = id;
        this.readonly = readonly;

        return this;
    }

    YAHOO.extend(CStudioForms.Controls.textInput, CStudioForms.CStudioFormField, {

        getLabel: function() {
            return "Text Input";
        },

        _onChange: function(evt, obj) {
            obj.value = obj.inputEl.value;
        
            // Empty error state before new validation (for a clean state)
            YAHOO.util.Dom.removeClass(obj.patternErrEl, 'on');
            obj.clearError('pattern');
        
            var validationExist = false;
            var validationResult = true;
            if (obj.required) {
              if (obj.inputEl.value == '') {
                obj.setError('required', 'Field is Required');
                validationExist = true;
                validationResult = false;
              } else {
                obj.clearError('required');
                validationExist = true;
              }
            }
        
            if ((!validationExist && obj.inputEl.value != '') || (validationExist && validationResult)) {
              for (var i = 0; i < obj.constraints.length; i++) {
                var constraint = obj.constraints[i];
                if (constraint.name == 'pattern') {
                  var regex = constraint.value;
                  if (regex != '') {
                    if (obj.inputEl.value.match(regex)) {
                      // only when there is no other validation mark it as passed
                      obj.clearError('pattern');
                      YAHOO.util.Dom.removeClass(obj.patternErrEl, 'on');
                      validationExist = true;
                    } else {
                      if (obj.inputEl.value != '') {
                        YAHOO.util.Dom.addClass(obj.patternErrEl, 'on');
                      }
                      obj.setError('pattern', 'The value entered is not allowed in this field.');
                      validationExist = true;
                      validationResult = false;
                    }
                  }
        
                  break;
                }
              }
            }
            // actual validation is checked by # of errors
            // renderValidation does not require the result being passed
            obj.renderValidation(validationExist, validationResult);
            obj.owner.notifyValidation();
            const valueToSet = obj.escapeContent ? CStudioForms.Util.escapeXml(obj.getValue()) : obj.getValue();
            obj.form.updateModel(obj.id, valueToSet);
          },
        
          _onChangeVal: function(evt, obj) {
            obj.edited = true;
            if (this._onChange) {
              this._onChange(evt, obj);
            }
          },
        
          /**
           * perform count calculation on keypress
           * @param evt event
           * @param el element
           */
          count: function(evt, countEl, el) {
            // 'this' is the input box
            el = el ? el : this;
            var text = el.value;
        
            var charCount = text.length ? text.length : el.textLength ? el.textLength : 0;
            var maxlength = el.maxlength && el.maxlength != '' ? el.maxlength : -1;
        
            if (maxlength != -1) {
              if (charCount > el.maxlength) {
                // truncate if exceeds max chars
                if (charCount > el.maxlength) {
                  this.value = text.substr(0, el.maxlength);
                  charCount = el.maxlength;
                }
        
                if (
                  evt &&
                  evt != null &&
                  evt.keyCode != 8 &&
                  evt.keyCode != 46 &&
                  evt.keyCode != 37 &&
                  evt.keyCode != 38 &&
                  evt.keyCode != 39 &&
                  evt.keyCode != 40 && // arrow keys
                  evt.keyCode != 88 &&
                  evt.keyCode != 86
                ) {
                  // allow backspace and
                  // delete key and arrow keys (37-40)
                  // 86 -ctrl-v, 90-ctrl-z,
                  if (evt) YAHOO.util.Event.stopEvent(evt);
                }
              }
            }
        
            if (maxlength != -1) {
              countEl.innerHTML = charCount + ' / ' + el.maxlength;
            } else {
              countEl.innerHTML = charCount;
            }
          },
        
          render: function(config, containerEl) {
            // we need to make the general layout of a control inherit from common
            // you should be able to override it -- but most of the time it wil be the same
            containerEl.id = this.id;
        
            var titleEl = document.createElement('span');
        
            YAHOO.util.Dom.addClass(titleEl, 'cstudio-form-field-title');
            titleEl.textContent = config.title;
        
            var controlWidgetContainerEl = document.createElement('div');
            YAHOO.util.Dom.addClass(controlWidgetContainerEl, 'cstudio-form-control-input-container');
        
            var validEl = document.createElement('span');
            YAHOO.util.Dom.addClass(validEl, 'validation-hint');
            YAHOO.util.Dom.addClass(validEl, 'cstudio-form-control-validation fa fa-check');
        
            var inputEl = document.createElement('input');
            this.inputEl = inputEl;
            YAHOO.util.Dom.addClass(inputEl, 'datum');
            YAHOO.util.Dom.addClass(inputEl, 'cstudio-form-control-input');
        
            const valueToSet = this.escapeContent ? CStudioForms.Util.unEscapeXml(this.value) : this.value;
            inputEl.value = this.value === '_not-set' ? config.defaultValue : valueToSet;
            controlWidgetContainerEl.appendChild(inputEl);
        
            YAHOO.util.Event.on(
              inputEl,
              'focus',
              function(evt, context) {
                context.form.setFocusedField(context);
              },
              this
            );
        
            YAHOO.util.Event.on(inputEl, 'change', this._onChangeVal, this);
            YAHOO.util.Event.on(inputEl, 'blur', this._onChange, this);
        
            for (var i = 0; i < config.properties.length; i++) {
              var prop = config.properties[i];
        
              if (prop.name == 'size') {
                inputEl.size = prop.value;
              }
        
              if (prop.name == 'maxlength') {
                inputEl.maxlength = prop.value;
              }
        
              if (prop.name == 'readonly' && prop.value == 'true') {
                this.readonly = true;
              }
        
              if (prop.name === 'escapeContent' && prop.value === 'true') {
                this.escapeContent = true;
              }
            }
        
            if (this.readonly == true) {
              inputEl.disabled = true;
            }
        
            var countEl = document.createElement('div');
            YAHOO.util.Dom.addClass(countEl, 'char-count');
            YAHOO.util.Dom.addClass(countEl, 'cstudio-form-control-input-count');
            controlWidgetContainerEl.appendChild(countEl);
            this.countEl = countEl;
        
            var patternErrEl = document.createElement('div');
            patternErrEl.innerHTML = 'The value entered is not allowed in this field.';
            YAHOO.util.Dom.addClass(patternErrEl, 'cstudio-form-control-input-url-err');
            controlWidgetContainerEl.appendChild(patternErrEl);
            this.patternErrEl = patternErrEl;
        
            YAHOO.util.Event.on(inputEl, 'keyup', this.count, countEl);
            YAHOO.util.Event.on(inputEl, 'keypress', this.count, countEl);
            YAHOO.util.Event.on(inputEl, 'mouseup', this.count, countEl);
        
            this.renderHelp(config, controlWidgetContainerEl);
        
            var descriptionEl = document.createElement('span');
            YAHOO.util.Dom.addClass(descriptionEl, 'description');
            YAHOO.util.Dom.addClass(descriptionEl, 'cstudio-form-field-description');
            descriptionEl.textContent = config.description;
        
            containerEl.appendChild(titleEl);
            containerEl.appendChild(validEl);
            containerEl.appendChild(controlWidgetContainerEl);
            containerEl.appendChild(descriptionEl);
          },
        
          getValue: function() {
            return this.value;
          },
        
          setValue: function(value) {
            const valueToSet = this.escapeContent ? CStudioForms.Util.unEscapeXml(value) : value;
        
            this.value = valueToSet;
            this.inputEl.value = valueToSet;
            this.count(null, this.countEl, this.inputEl);
            this._onChange(null, this);
            this.edited = false;
          },

          getName: function() {
            return "text-input";
    },

    getSupportedProperties: function() {
        return [
            { label: CMgs.format(langBundle, "displaySize"), name: "size", type: "int", defaultValue: "50" },
            { label: CMgs.format(langBundle, "maxLength"), name: "maxlength", type: "int",  defaultValue: "50" },
            { label: CMgs.format(langBundle, "readonly"), name: "readonly", type: "boolean" },
            { label: "Tokenize for Indexing", name: "tokenize", type: "boolean",  defaultValue: "false" }
        ];
    },

    getSupportedConstraints: function() {
        return [
            { label: CMgs.format(langBundle, "required"), name: "required", type: "boolean" },
            { label: CMgs.format(langBundle, "matchPattern"), name: "pattern", type: "string" },
        ];
    }

});

CStudioAuthoring.Module.moduleLoaded("text-input", CStudioForms.Controls.textInput);

Saving additional form control elements to XML

To save additional elements from your form control into the XML content, call registerDynamicField from the form when initializing the form control. When updateField is called, your element will be saved into the XML content.

this.form.registerDynamicField(this.timezoneId);

See here for an example of calling registerDynamicField in the date-time form control code.

Auto-wiring and Installing a Control Plugin

To setup our form control to be automatically wired in the corresponding configuration file in Studio (which for a form control, is the Project Config Tools Configuration file) during the installation, add the following to your craftercms-plugin.yaml descriptor file:

craftercms-plugin.yaml

installation:
 - type: form-control
   elementXpath: //control/plugin[pluginId='org.craftercms.plugin.excontrol']
   element:
     name: control
     children:
       - name: plugin
         children:
           - name: pluginId
             value: org.craftercms.plugin.excontrol
           - name: type
             value: control
           - name: name
             value: text-input
           - name: filename
             value: main.js
       - name: icon
         children:
           - name: class
             value: fa-pencil-square-o

See CrafterCMS Plugin Descriptor for more information on setting up automatic wiring of your plugin in Studio.

After placing your JS file, the plugin may now be installed for testing/debugging using the crafter-cli command copy-plugin.

When running a crafter-cli command, the connection to CrafterCMS needs to be setup via the add-environment command. Once the connection has been established, we can now install the plugin to the project my-editorial by running the following:

./crafter-cli copy-plugin -e local -s my-editorial --path /users/myuser/myplugins/form-control-plugin

Let’s take a look at the auto-wiring performed during installation of the plugin. Form controls are setup in the site-config-tools.xml file.

The items we setup in the descriptor file for auto-wiring above should now be in the Project Config Tools configuration file, which can be accessed by opening the Sidebar, then clicking on -> Configuration -> Project Config Tools

Location (In Repository) SITENAME/config/studio/administration/site-config-tools.xml

<controls>
    <control>
        <name>auto-filename</name>
        .
        .
    </control>
    .
    .
    <control>
        <plugin>
            <pluginId>org.craftercms.plugin.excontrol</pluginId>
            <type>control</type>
            <name>text-input</name>
            <filename>main.js</filename>
        </plugin>
        <icon>
            <class>fa-pencil-square-o</class>
        </icon>
    </control>
</controls>

Here’s our plugin control added to the list of controls in content types:

Form Engine Data Source Plugin

What is a Data Source

Crafter Studio form controls should be written in a way that makes them independent of the data they allow the user to select so that they can be (re)used across a wide range of data sets. To accomplish this objective we use a data source pattern where by the form control widget code is concerned with rendering and facilitating the data capture/selection process but delegates the retrieval of the content to a separate swappable component interface known as a data source.

Out of the box data sources are:

Datasource	Description
	Details are in the Components Data Source page.
	Details are in the Shared Content Data Source page.
	Details are in the Embedded Content Data Source page.
	Details are in the Image Uploaded from Desktop Data Source page.
	Details are in the Image from Repository Data Source page.
	Details are in the File Uploaded from Desktop Data Source page.
	Details are in the File Browse Data Source page.
	Details are in the File from WebDAV Repository Data Source page.
	Details are in the Image from WebDAV Repository Data Source page.
	Details are in the Video from WebDAV Repository Data Source page.
	Details are in the WebDAV File Upload Data Source page.
	Details are in the WebDAV Image Upload Data Source page.
	Details are in the WebDAV Video Upload Data Source page.
	Details are in the S3 Repository Data Source page.
	Details are in the Image from S3 Repository Data Source page.
	Details are in the Video from S3 Repository Data Source page.
	Details are in the S3 File Upload Data Source page.
	Details are in the S3 Image Upload Data Source page.
	Details are in the S3 Video Upload Data Source page.
	Details are in the Video Upload then Transcode from S3 using MediaConvert Data Source page.
	Details are in the Video Uploaded from Desktop Data Source page.
	Details are in the Video from Repository Data Source page.
	Details are in the Static Key Value Pairs Data Source page.
	Details are in the Simple Taxonomy Data Source page.
	Details are in the Audio Uploaded from Desktop Data Source page.
	Details are in the Audio from Repository Data Source page.

The anatomy of a Data Source Project Plugin

Data Sources consist of (at a minimum)

• A single JavaScript file which implements the data source interface.

  • The JS file name and the data source name in the configuration does not need to be the same. The JS file name can be any meaningful name, different from the data source name in the configuration.

• Configuration in a Crafter Studio project to make that data source available for use.

Data Source Interface

/**
 * Constructor: Where .X is substituted with your class name
 */
CStudioForms.Datasources.X = CStudioForms.Datasources.X ||
function(id, form, properties, constraints)  {
}

/**
 * Extension of the base class
 */
YAHOO.extend(CStudioForms.Datasources.X, CStudioForms.CStudioFormDatasource, {

    /**
     * Return a user friendly name for the data source (will show up in content type builder UX
     */
    getLabel: function() {  },

    /**
     * return a string that represents the type of data returned by the data source
     * This is often of type "item"
     */
    getInterface: function() { },

    /**
     * return a string that represents the kind of data source (this is the same as the file name)
     */
    getName: function() { },

    /**
     * return a list of properties supported by the data source.
     * properties is an array of objects with the following structure { label: "", name: "", type: "" }
     */
    getSupportedProperties: function() { },

    /**
     * method responsible for getting the actual values. Caller must pass callback which meets interface:
     * { success: function(list) {}, failure: function(exception) }
     */
    getList: function(cb) { }
});

Data Source Plugin Directory and Example

When creating data source plugins, the JS file goes in the following location:

authoring/static-assets/plugins/{yourPluginId}/datasource/{yourPluginName}/JS_FILE.js

where {yourPluginName} is the name of the form engine data source plugin and JS_FILE.js is the JavaScript file containing the data source interface implementation.

Let’s take a look at an example of a data source plugin. We will be adding a data source named parent-content.

For this example, the plugin.id is org.craftercms.plugin.examples, the CATEGORY is datasource, the NAME is parent-content, and the JS file is main.js.

Form Engine Data Source Plugin Directory Structure

<plugin-folder>/
  craftercms-plugin.yaml
  authoring/
    static-assets/
      plugins/
        org/
          craftercms/
            plugin/
              examples/
                datasource/
                  parent-content/
                    main.js

For our example, the <plugin-folder> is located here: /users/myuser/myplugins/form-datasource-plugin

In the JS file, please note that the CStudioAuthoring.Module is required and that the prefix for CStudioAuthoring.Module.moduleLoaded must be the name of the data source. For our example, the prefix is parent-content as shown in the example.

authoring/static-assets/plugins/org/craftercms/plugin/examples/datasource/parent-content/main.js

CStudioForms.Datasources.ParentContent= CStudioForms.Datasources.ParentContent ||
function(id, form, properties, constraints)  {
    this.id = id;
    this.form = form;
    this.properties = properties;
    this.constraints = constraints;
    this.selectItemsCount = -1;
    this.type = "";
    this.defaultEnableCreateNew = true;
    this.defaultEnableBrowseExisting = true;
    this.countOptions = 0;

    for(var i=0; i<properties.length; i++) {
            if(properties[i].name == "repoPath") {
                    this.repoPath = properties[i].value;
            }
            if(properties[i].name == "browsePath") {
                    this.browsePath = properties[i].value;
            }

            if(properties[i].name == "type"){
                    this.type = (Array.isArray(properties[i].value))?"":properties[i].value;
            }

        if(properties[i].name === "enableCreateNew"){
            this.enableCreateNew = properties[i].value === "true" ? true : false;
            this.defaultEnableCreateNew = false;
            properties[i].value === "true" ? this.countOptions ++ : null;
        }

        if(properties[i].name === "enableBrowseExisting"){
            this.enableBrowseExisting = properties[i].value === "true" ? true : false;
            this.defaultEnableBrowseExisting = false;
            properties[i].value === "true" ? this.countOptions ++ : null;
        }
    }

    if(this.defaultEnableCreateNew){
        this.countOptions ++;
    }
    if(this.defaultEnableBrowseExisting){
        this.countOptions ++;
    }

    return this;
}

YAHOO.extend(CStudioForms.Datasources.ParentContent, CStudioForms.CStudioFormDatasource, {
    .
    .
    .
    getName: function() {
            return "parent-content";
    },

    getSupportedProperties: function() {
            return [
            { label: CMgs.format(langBundle, "Enable Create New"), name: "enableCreateNew", type: "boolean", defaultValue: "true"  },
            { label: CMgs.format(langBundle, "Enable Browse Existing"), name: "enableBrowseExisting", type: "boolean", defaultValue: "true" },
                    { label: CMgs.format(langBundle, "repositoryPath"), name: "repoPath", type: "string" },
                    { label: CMgs.format(langBundle, "browsePath"), name: "browsePath", type: "string" },
                    { label: CMgs.format(langBundle, "defaultType"), name: "type", type: "string" }
            ];
    },

    getSupportedConstraints: function() {
            return [
            ];
    }

});

CStudioAuthoring.Module.moduleLoaded("parent-content", CStudioForms.Datasources.ParentContent);

Here’s the complete example form data source plugin file for the parent-content data source (click on the triangle on the left to expand/collapse):

Sample form data source plugin file "main.js".

/*
 * Copyright (C) 2007-2021 Crafter Software Corporation. All Rights Reserved.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 3 as published by
 * the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

CStudioForms.Datasources.ParentContent = function(id, form, properties, constraints) {
    this.id = id;
    this.form = form;
    this.properties = properties;
    this.constraints = constraints;
    this.selectItemsCount = -1;
    this.type = '';
    this.defaultEnableCreateNew = true;
    this.defaultEnableBrowseExisting = true;
    this.countOptions = 0;
    //const i18n = CrafterCMSNext.i18n;
    //this.formatMessage = i18n.intl.formatMessage;
    //this.parentContentDSMessages = i18n.messages.parentContentDSMessages;
  
    for (var i = 0; i < properties.length; i++) {
      if (properties[i].name == 'repoPath') {
        this.repoPath = properties[i].value;
      }
      if (properties[i].name == 'browsePath') {
        this.browsePath = properties[i].value;
      }
  
      if (properties[i].name == 'type') {
        this.type = Array.isArray(properties[i].value) ? '' : properties[i].value;
      }
  
      if (properties[i].name === 'enableCreateNew') {
        this.enableCreateNew = properties[i].value === 'true' ? true : false;
        this.defaultEnableCreateNew = false;
        properties[i].value === 'true' ? this.countOptions++ : null;
      }
  
      if (properties[i].name === 'enableBrowseExisting') {
        this.enableBrowseExisting = properties[i].value === 'true' ? true : false;
        this.defaultEnableBrowseExisting = false;
        properties[i].value === 'true' ? this.countOptions++ : null;
      }
    }
  
    if (this.defaultEnableCreateNew) {
      this.countOptions++;
    }
    if (this.defaultEnableBrowseExisting) {
      this.countOptions++;
    }
  
    return this;
  };
  
  YAHOO.extend(CStudioForms.Datasources.ParentContent, CStudioForms.CStudioFormDatasource, {
    itemsAreContentReferences: true,
  
    createElementAction: function(control, _self, addContainerEl) {
      if (this.countOptions > 1) {
        control.addContainerEl = null;
        control.containerEl.removeChild(addContainerEl);
      }
      if (_self.type === '') {
        CStudioAuthoring.Operations.createNewContent(
          CStudioAuthoringContext.site,
          _self.processPathsForMacros(_self.repoPath),
          false,
          {
            success: function(formName, name, value) {
              control.insertItem(value, formName.item.internalName, null, null, _self.id);
              control._renderItems();
            },
            failure: function() {}
          },
          true
        );
      } else {
        CStudioAuthoring.Operations.openContentWebForm(
          _self.type,
          null,
          null,
          _self.processPathsForMacros(_self.repoPath),
          false,
          false,
          {
            success: function(contentTO, editorId, name, value) {
              control.insertItem(name, value, null, null, _self.id);
              control._renderItems();
              CStudioAuthoring.InContextEdit.unstackDialog(editorId);
            },
            failure: function() {}
          },
          [{ name: 'childForm', value: 'true' }]
        );
      }
    },
  
    browseExistingElementAction: function(control, _self, addContainerEl) {
      if (this.countOptions > 1) {
        control.addContainerEl = null;
        control.containerEl.removeChild(addContainerEl);
      }
      // if the browsePath property is set, use the property instead of the repoPath property
      // otherwise continue to use the repoPath for both cases for backward compatibility
      var browsePath = _self.repoPath;
      if (_self.browsePath != undefined && _self.browsePath != '') {
        browsePath = _self.browsePath;
      }
      CStudioAuthoring.Operations.openBrowse(
        '',
        _self.processPathsForMacros(browsePath),
        _self.selectItemsCount,
        'select',
        true,
        {
          success: function(searchId, selectedTOs) {
            for (var i = 0; i < selectedTOs.length; i++) {
              var item = selectedTOs[i];
              var value = item.internalName && item.internalName != '' ? item.internalName : item.uri;
              control.insertItem(item.uri, value, null, null, _self.id);
              control._renderItems();
            }
          },
          failure: function() {}
        }
      );
    },
  
    add: function(control, onlyAppend) {
      var CMgs = CStudioAuthoring.Messages;
      var langBundle = CMgs.getBundle('contentTypes', CStudioAuthoringContext.lang);
  
      var _self = this;
  
      var addContainerEl = control.addContainerEl ? control.addContainerEl : null;
  
      var datasourceDef = this.form.definition.datasources,
        newElTitle = '';
  
      for (var x = 0; x < datasourceDef.length; x++) {
        if (datasourceDef[x].id === this.id) {
          newElTitle = datasourceDef[x].title;
        }
      }
  
      if (!addContainerEl && (this.countOptions > 1 || onlyAppend)) {
        addContainerEl = document.createElement('div');
        control.containerEl.appendChild(addContainerEl);
        YAHOO.util.Dom.addClass(addContainerEl, 'cstudio-form-control-node-selector-add-container');
        control.addContainerEl = addContainerEl;
        control.addContainerEl.style.left = control.addButtonEl.offsetLeft + 'px';
        control.addContainerEl.style.top = control.addButtonEl.offsetTop + 22 + 'px';
      }
  
      if (this.enableCreateNew || this.defaultEnableCreateNew) {
        if (this.countOptions > 1 || onlyAppend) {
          addContainerEl.create = document.createElement('div');
          addContainerEl.appendChild(addContainerEl.create);
          YAHOO.util.Dom.addClass(addContainerEl.create, 'cstudio-form-controls-create-element');
  
          var createEl = document.createElement('div');
          YAHOO.util.Dom.addClass(createEl, 'cstudio-form-control-node-selector-add-container-item');
          createEl.textContent = CMgs.format(langBundle, 'createNew') + ' - ' + newElTitle;
          control.addContainerEl.create.appendChild(createEl);
          var addContainerEl = control.addContainerEl;
          YAHOO.util.Event.on(
            createEl,
            'click',
            function() {
              _self.createElementAction(control, _self, addContainerEl);
            },
            createEl
          );
        } else {
          _self.createElementAction(control, _self);
        }
      }
  
      if (this.enableBrowseExisting || this.defaultEnableBrowseExisting) {
        if (this.countOptions > 1 || onlyAppend) {
          addContainerEl.browse = document.createElement('div');
          addContainerEl.appendChild(addContainerEl.browse);
          YAHOO.util.Dom.addClass(addContainerEl.browse, 'cstudio-form-controls-browse-element');
  
          var browseEl = document.createElement('div');
          browseEl.textContent = CMgs.format(langBundle, 'browseExisting') + ' - ' + newElTitle;
          YAHOO.util.Dom.addClass(browseEl, 'cstudio-form-control-node-selector-add-container-item');
          control.addContainerEl.browse.appendChild(browseEl);
          var addContainerEl = control.addContainerEl;
          YAHOO.util.Event.on(
            browseEl,
            'click',
            function() {
              _self.browseExistingElementAction(control, _self, addContainerEl);
            },
            browseEl
          );
        } else {
          _self.browseExistingElementAction(control, _self);
        }
      }
    },
  
    edit: function(key, control) {
      var _self = this;
      CStudioAuthoring.Service.lookupContentItem(CStudioAuthoringContext.site, key, {
        success: function(contentTO) {
          CStudioAuthoring.Operations.editContent(
            contentTO.item.contentType,
            CStudioAuthoringContext.siteId,
            contentTO.item.mimeType,
            contentTO.item.nodeRef,
            contentTO.item.uri,
            false,
            {
              success: function(contentTO, editorId, name, value) {
                if (control) {
                  control.updateEditedItem(value, _self.id);
                  CStudioAuthoring.InContextEdit.unstackDialog(editorId);
                }
              }
            }
          );
        },
        failure: function() {}
      });
    },
  
    updateItem: function(item, control) {
      if (item.key && item.key.match(/\.xml$/)) {
        var getContentItemCb = {
          success: function(contentTO) {
            item.value = contentTO.item.internalName || item.value;
            control._renderItems();
          },
          failure: function() {}
        };
  
        CStudioAuthoring.Service.lookupContentItem(CStudioAuthoringContext.site, item.key, getContentItemCb);
      }
    },
  
    getLabel: function() {
      //return this.formatMessage(this.parentContentDSMessages.parentContent);
      return "Parent Content";
    },
  
    getInterface: function() {
      return 'item';
    },
  
    getName: function() {
      return 'parent-content';
    },
  
    getSupportedProperties: function() {
      return [
        {
          label: CMgs.format(langBundle, 'Enable Create New'),
          name: 'enableCreateNew',
          type: 'boolean',
          defaultValue: 'true'
        },
        {
          label: CMgs.format(langBundle, 'Enable Browse Existing'),
          name: 'enableBrowseExisting',
          type: 'boolean',
          defaultValue: 'true'
        },
        { label: CMgs.format(langBundle, 'repositoryPath'), name: 'repoPath', type: 'string' },
        { label: CMgs.format(langBundle, 'browsePath'), name: 'browsePath', type: 'string' },
        { label: CMgs.format(langBundle, 'defaultType'), name: 'type', type: 'string' }
      ];
    },
  
    getSupportedConstraints: function() {
      return [];
    }
  });
  
  CStudioAuthoring.Module.moduleLoaded('parent-content', CStudioForms.Datasources.ParentContent);
  

Auto-wiring and Installing a Data Source Plugin

To setup our form data source to be automatically wired in the corresponding configuration file in Studio (which for a form data source, is the Project Config Tools Configuration file) during the installation, add the following to your craftercms-plugin.yaml descriptor file:

craftercms-plugin.yaml

installation:
 - type: form-datasource
   elementXpath: //datasource/plugin[pluginId='org.craftercms.plugin.examples']
   element:
     name: datasource
     children:
       - name: plugin
         children:
           - name: pluginId
             value: org.craftercms.plugin.examples
           - name: type
             value: datasource
           - name: name
             value: parent-content
           - name: filename
             value: main.js
       - name: icon
         children:
           - name: class
             value: fa-pencil-square-o

See CrafterCMS Plugin Descriptor for more information on setting up automatic wiring of your plugin in Studio.

After placing your JS file, the plugin may now be installed for testing/debugging using the crafter-cli command copy-plugin.

When running a crafter-cli command, the connection to CrafterCMS needs to be setup via the add-environment command. Once the connection has been established, we can now install the plugin to the project my-editorial by running the following:

./crafter-cli copy-plugin -e local -s my-editorial --path /users/myuser/myplugins/form-datasource-plugin

Let’s take a look at the auto-wiring performed during installation of the plugin. Form data sources are setup in the site-config-tools.xml file.

The items we setup in the descriptor file for auto-wiring above should now be in the Project Config Tools configuration file, which can be accessed by opening the Sidebar, then clicking on -> Configuration -> Project Config Tools

Location (In Repository) SITENAME/config/studio/administration/site-config-tools.xml

<datasources>
    <datasource>
        <name>img-desktop-upload</name>
        .
        .
    </datasource>
    .
    .
    <datasource>
        <plugin>
            <pluginId>org.craftercms.plugin.examples</pluginId>
            <type>datasource</type>
            <name>parent-content</name>
            <filename>main.js</filename>
        </plugin>
        <icon>
            <class>fa-users</class>
        </icon>
    </datasource>
</datasources>

Here’s our plugin data source added to the list of data sources in content types: