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:
get()
- returns an object containing the editor configurations. It takes 3 argumentsprofile
,config
andfield
.load()
- loads any required files (if any) and executes a callback functioncb()
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();
};