October Special:  Up to 30% off on all plans for new users
Days
Hours
Minutes
Seconds
x
Skip to content
Froala Documentation

Custom Plugin

Custom Plugin

Below is the basic JS structure for creating your own plugin for Froala Editor. 
(function (FroalaEditor) {
    // Add an option for your plugin.
    FroalaEditor.DEFAULTS = Object.assign(FroalaEditor.DEFAULTS, {
      myOption: false
    });

    // Define the plugin.
    // The editor parameter is the current instance.
    FroalaEditor.PLUGINS.myPlugin = function (editor) {
      // Private variable visible only inside the plugin scope.
      var private_var = 'My awesome plugin';

      // Private method that is visible only inside plugin scope.
      function _privateMethod () {
        console.log (private_var);
      }

      // Public method that is visible in the instance scope.
      function publicMethod () {
        _privateMethod();
      }

      // The start point for your plugin.
      function _init () {
        // You can access any option from documentation or your custom options.
        console.log (editor.opts.myOption)

        // Call any method from documentation.
        // editor.methodName(params);

        // You can listen to any event from documentation.
        // editor.events.add('contentChanged', function (params) {});
      }

      // Expose public methods. If _init is not public then the plugin won't be initialized.
      // Public method can be accessed through the editor API:
      // editor.myPlugin.publicMethod();
      return {
        _init: _init,
        publicMethod: publicMethod
      }
    }
  })(FroalaEditor);

Make Your Plugin Work in Headless Mode

Starting with v5.5, the editor can run with headless: true. In this mode the editor draws no UI of its own: no toolbar, popups, or modals. Developers drive it from their own interface through the API. A well-behaved plugin follows the same rule as the built-in ones. Methods that open UI should do nothing, and methods that change content should keep working. The editor gives you five helpers for this:
Helper What it does
editor.helpers.isHeadless() Returns true when the editor runs with headless: true.
editor.helpers.guardHeadlessUI(api, methodNames) In headless mode, replaces the listed methods on your plugin’s API with methods that do nothing and return false. Use it for methods that open your own UI outside the popups and modals system.
editor.helpers.ensureHeadlessFocus() In headless mode, focuses the editor if the selection is not inside it, so the browser places a caret in the content. Call it at the start of action methods that read the selection.
editor.helpers.headlessDefault(key, value) In headless mode, sets editor.opts[key] to value unless the integrator set that option explicitly.
editor.helpers.isUserOpt(key) Returns true only when an option was passed in explicitly, rather than coming from the defaults.

Outside headless mode, guardHeadlessUI, ensureHeadlessFocus, and headlessDefault change nothing, so you can add them without affecting normal editors.

(function (FroalaEditor) {
  // An option for a status bar the plugin draws.
  FroalaEditor.DEFAULTS = Object.assign(FroalaEditor.DEFAULTS, {
    myStatusBarEnabled: true
  });

  FroalaEditor.PLUGINS.myPlugin = function (editor) {
    // Opens your own dialog. This is UI, so it should not run in headless mode.
    function openPicker () {
      var dialog = document.createElement('dialog');
      dialog.textContent = 'Pick an item';
      document.body.appendChild(dialog);
      dialog.showModal();
    }

    // Changes content. This is an action, so it should keep working in headless mode.
    function highlight () {
      // Make sure there is a caret inside the editor before reading the selection.
      editor.helpers.ensureHeadlessFocus();
      editor.format.applyStyle('background-color', 'yellow');
    }

    function _init () {
      // Off by default in headless mode, unless the integrator turned it on.
      editor.helpers.headlessDefault('myStatusBarEnabled', false);
    }

    var api = {
      _init: _init,
      openPicker: openPicker,
      highlight: highlight
    };

    // In headless mode, openPicker becomes a method that does nothing.
    editor.helpers.guardHeadlessUI(api, ['openPicker']);

    return api;
  };
})(FroalaEditor);
Custom Popup

Do you think we can improve this article? Let us know.