Understanding Custom Editors Config

Perch ships with three in-built editors: MarkItUp, SimpleMDE and Redactor. These are configured in a way that hooks them in with functionality provided by Perch such as Assets. You can, however, specify your own configuration. This is useful for adding additional toolbar plugins and so on.

To add your own configurations, firstly you need to enable custom editor configurations in your config file perch/config/config.php:

define('PERCH_CUSTOM_EDITOR_CONFIGS', true);

Then you need to add a javascript file addons/plugins/editors/config.js. This file contains any custom configurations you want to apply to any editor.

Inside the file, you define the property Perch.UserConfig.editorname for each editor you want to customise.

Perch.UserConfig.redactor = function(){
  // your redactor config
}();

Perch.UserConfig.markitup = function(){
  // your markitup config
}();

The property must be an object with two methods:

Perch.UserConfig.redactor = function(){
  var get = function (profile, config, field) {
    return config;
  };

  var load = function (cb) {
    cb();
  };

  return {
    'get': get,
    'load': load
  }
}();

get(): config

The easiest way to inspect the default configurations (at least what you have access to) is to console.log() the config object. 

var get = function (profile, config, field) {
  console.log(config);
  return config;
};

Check the editor documentation to learn what’s possible to achieve and options you can use.

In the case of the Redactor editor (as of Perch 3.1.3), the config object has an array of plugins which contains a single plugin called perchassets. So if you want to add new plugins, you would add them to the array. And if you want to remove any default plugins, you would remove them from the array.

The documentation includes an example of how you can add a plugin:

var get = function(profile, config, field) {
  // check whether the plugin 'fontcolor' is already in the array plugins
  if (config.plugins.indexOf('fontcolor') === -1) {
    // if not, add it
    config.plugins.push('fontcolor');
  }

  return config;
};

Similarly you can remove a single plugin:

var get = function(profile, config, field) {
  // if a plugin called 'someplugin' is in the array plugins, remove it
  config.plugins = config.plugins.filter(function (item) {
    return item !== 'someplugin'
  });

  return config;
};

The above is a safe way to remove a single plugin without having to define all the plugins yourself.

What else you can do add to the config object depends on the editor itself. They are third-party tools after all. So it’s always a good idea to refer to their documentation. For example, you can hide some buttons for the Redactor editor like so:

config.buttonsHide = ['link', 'bold'];

get(): profile

The profile argument holds the value of the editor-config attribute on the tag. This allows you to conditionally change the configuration based on the profile.

Let’s say in some edit forms you want to allow the user to add images while in other edit forms you want to prevent them from doing that. You can use a profile:

<perch:content id="text" type="textarea" label="Text" editor="redactor" editor-config="no images" html>

The Redactor plugin responsible for image addition and uploads is called perchassets. So we can remove it conditionally:

var get = function(profile, config, field) {
  if(profile == 'no images') {
    // remove the 'perchassets' plugin
    config.plugins = config.plugins.filter(function (item) {
      return item !== 'perchassets'
    })
  }

  return config;
};

Similarly, you can have profiles to add plugins or remove buttons.

get(): field

The field argument is the input field.

load()

Inside the load() method you can load any files you need. Plugins often require you to load a Javascript file. Inside the Perch control panel you can use jQuery, so you can easily load a file with jQuery.getScript().

var load = function (cb) {
  // load fontcolor plugin
  jQuery.getScript(Perch.path + '/addons/plugins/editors/redactor-plugins/redactor-plugins/fontcolor.js', cb);
};

load(): Perch path

Perch allows you to customise the name of the perch directory. By default it’s called perch so your file path would probably be something like:

var path = '/perch/addons/plugins/editors/your-file.js';

To make your configuration file works across multiple Perch installations without having to modify them, you can use Perch.path:

var path = Perch.path + '/addons/plugins/editors/your-file.js';

load(): callback

In the example above you may have noticed that we’re calling the function cb() as the callback function in jQuery.getScript() :

jQuery.getScript(Perch.path + '/addons/plugins/editors/redactor-plugins/redactor-plugins/fontcolor.js', cb);

The second argument in jQuery.getScript() is a callback function that is excuted if the request (to the URL specified in the first argument) succeeds. You can refer to jQuery’s documentation to learn more.

You need to call cb() after you have loaded all the files. If you don’t have any files to load, all you need to do is execute the callback function:

var load = function (cb) {
  cb();
};
link