PageBuilder Editor: Plugins

To provide you more flexibility to position the modals (popups) such as block level plugins (another example being multi-field editables) in the Editor Preview, Editor supports docking the modal in 4 different ways: bottom-left, top-left, bottom-right, and top-right. Your last selected dock position will be stored in your local storage as your preference and will persist till you clear your cache. For example, if you dock the WYSIWYG editor (example field level plugin shown above) or Presets plugin (example block level plugin shown above) modal to bottom-right and save it, next time you edit the plugins, the modal will appear on the bottom-right.

Plugins are implemented as HTML web pages that get included as iframes in the PageBuilder Editor. Each HTML document must include a JavaScript method named initializePlugin set on the global window object. This method is responsible for setting the initial state of the plugin UI, and will be invoked by PageBuilder Editor when a user opens the proper plugin.

Block level plugins allow users to interact directly with a PageBuilder Block object. These plugins are powerful because users can create custom UIs that update one or several of the following block properties:

Chain level plugins support the following chain properties:

Users have the ability to use single or multiple plugins at both block and chain level. In case of multiple plugins, you can choose from a menu of available plugins options.

To help you get started, here is a sample use case for presets as a plugin at block level.

For complex blocks/chains with several custom fields, editorial users need a quick way to set different combinations of custom fields to experience different view or behavior. In PageBuilder Classic Admin (older version of PageBuilder), this was accomplished by using “presets” which are combinations of custom fields pre-configured by block developers to provide various options to the Editors.

Through presets, different predefined combinations of custom fields are pre-populated and automatically set to present a specific block/chain behavior. For example, presets can provide a standard or magazine look and feel to a Story Card Block. With a single click, Editors can change the appearance of a block to different preset options. They can override and/or set additional custom fields, if needed.

The following code snippet implements multiple block plugins on a simple HeaderText block. PageBuilder Editor will render plugins based on the value block developers set as the `featurePlugin` option.

class HeaderText extends Component {
  render () {
    return (
        <div className="header-text">
        <h2  dangerouslySetInnerHTML={{__html: persist_param_links_in_text(this.props.customFields.title)}} />
        </div>
    )
  }
}

HeaderText.featurePlugins = ['presets', 'second-plugin']

Block developers can also set featurePlugins to a string value which would render a single block preset in the PageBuilder Editor. For example HeaderText.featurePlugins = ‘presets’.

Field level plugin allows users to extend functionality of a specific custom field. Unlike block level plugins, block developers can only assign a single plugin per custom field. PageBuilder Editor will render plugins based on the value block developers set as the `formPlugin` option. Field level plugins are activated when a clickable plugin icon appears to the right of the custom field in PageBuilder Editor. The following code snippet implements a field level plugin (color-picker) on HeaderText’s title custom field.

class HeaderText extends Component {
  render () {
    return (
        <div className="header-text">
        <h2  dangerouslySetInnerHTML={{__html: persist_param_links_in_text(this.props.customFields.headerText)}} />
        </div>
    )
  }
}

HeaderText.propTypes = {
  customFields: PropTypes.shape({
    title: PropTypes.string
        .tag({
          name: 'Title',
          defaultValue: 'Sample Text',
          formPlugin: 'color-picker'
        })
  })
}

The initializePlugin method is required for a plugin to be able to interface with PageBuilder Editor by receiving the initial value for the block/chain or the specific field it is set on. This method must be defined on the global window object of the HTML document.

A plugin is expected to be stored and named in the following format: /resources/plugins/{pluginName}/index.html

The {pluginName} portion of the filepath must correspond exactly to the name of the plugin that is passed as the featurePlugin (block/chain level) or formPlugin (field level) value in the block.

Plugins can also have additional files and folders inside of their respective pluginName directories. This may include JavaScript, CSS or other resource dependencies of the plugin.

It is common for plugins to require a build process in order to compile higher-level JavaScript into websafe (ES5) JavaScript. In this case, it is recommended that the source code for the plugin be stored and named in the following format: /plugins/{pluginName}/*

The * portion of the filepath represents any source files needed to generate the plugin’s compiled code (including HTML).

The source code should contain some build process (typically a webpack config file) that builds a compiled version of the plugin’s code into the corresponding /resources/plugins/{pluginName} directory

Plugin Example
/*  /resources/plugins/color-picker/index.html  */

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />
  <title>Plugin</title>
</head>
<body>
  <div class="color" data-color="red"></div>
  <div class="color" data-color="white"></div>
  <div class="color" data-color="blue"></div>

  <button id="save">Save</button>
  <button id="close">Close</button>

  <script>
    window.initializePlugin = function({ field, initVal, onClose, onSave }) {
      let selectedColor = initVal || ''

      document.querySelectorAll('.color').forEach(el => {
        el.addEventListener('click', () => {
          selectedColor = el.getAttribute('data-color')
        })
      })

      document.getElementById('save').addEventListener('click', () => {
        onSave(selectedColor)
      })

      document.getElementById('close').addEventListener('click', onClose)
    }
  </script>
</body>
</html>

Because multiple plugins can exist at the block level, it’s important to understand the behavior of blocks with both a customFields(Object) and localEdits(Object) property.

For blocks using ANS content and support localEdits(Object) property, we recommend feature developers use the editableContent() hook property instead of the editableField hook. This will help to avoid scenarios where users may potentially lose localEdits made. The editableField hook property is a better option for Editor Preview content editables that are not tied to ANS content.