Editor Settings
Mura's web editor, CKEditor, comes with a rich set of configuration options that make it possible to customize its appearance, features, and behavior.
Custom Configuration File
Mura utilizes a custom configuration file for setting CKEditor's configuration. Using a custom configuration file allows you to customize the various toolbars, and offers a way to control much of the way the web editor looks and functions.
The important piece to know is where you can place your custom configuration information. Mura automatically scans for specific files within your theme to use for CKEditor's configuration file. Listed below are the files Mura checks for in the specified order.
../themes/{ThemeName}/js/editor/config.js.cfm../themes/{ThemeName}/js/editor/config.js
The default theme for Mura as of v7.1, MuraBootstrap4, includes a sample file with miscellaneous configuration examples. You can find it under ../MuraBootstrap4/js/editor/config.js.cfm.txt
Since the sample file's extension ends with ".txt", Mura will ignore it. If you wish to use it, simply rename the file to remove the ".txt" file extension.
Custom Toolbar
A common question from developers centers around the ability to customize the editor toolbar. For example, if you only want the "Default" editor toolbar to display Bold, Italic, and Underline options, your configuration file could look something like the following code example.
if ( 'CKEDITOR' in window) {
CKEDITOR.editorConfig = function( config ) {
config.toolbar_Default = [
{name:'group1',items:['Bold','Italic','Underline']}
];
};
}
Using the example code above, the editor toolbars for "Content" will only display the Bold, Italic, and Underline options. However, the "Summary" toolbar will not change, as shown below.
As noted in the sample configuration file, if you wish to update the "Summary" toolbar, you'll need to explicitly define that as well. In addition, the front-end toolbar may be referenced with "QuickEdit". Below is an example that would update all three toolbars.
if ( 'CKEDITOR' in window) {
CKEDITOR.editorConfig = function( config ) {
config.toolbar_Default = [
{name:'group1',items:['Bold','Italic','Underline']}
];
config.toolbar_Summary = config.toolbar_Default;
config.toolbar_QuickEdit = config.toolbar_Default;
};
}
As you can see in the example code, we're simply using the first definition for the other toolbars. However, you could easily have different options for each toolbar definition, if you wish.
The example below displays both the Summary, and Content ("Default") toolbars.
The example below displays the "QuickEdit" toolbar used for front-end editing.
As you can see, Mura exposes CKEditor's configuration settings to allow you the ability to customize Mura's web editor quickly and easily.
Where to Learn More
All available CKEditor configuration options can be found in the CKEditor API documentation. Please refer to the CKEDITOR.config object definition for full details on each option.
Editor Styles Drop-down
Mura's web editor, CKEditor, includes a Styles drop-down list which contains styles that you can apply to editor content in order to assign semantic value to the text you are creating. The functionality is provided by the Styles Combo plugin.
Defining Styles
Mura automatically scans for specific files within your theme to apply styles to the drop-down list. Listed below are the files Mura checks for in the specified order.
../themes/{ThemeName}/js/editor/styles.js.cfm../themes/{ThemeName}/js/editor/styles.js
Using the first option with a ".cfm" file extension, allows you the ability to include dynamic code, in the event you wanted to do so.
The default theme for Mura as of v7.1, MuraBootstrap4, includes a sample file with some styles included. You can find it under ../MuraBootstrap4/js/editor/styles.js. Any styles defined here will appear in the Style drop-down list.
Where to Learn More
To learn more about CKEditor Styles, visit the Applying Styles to Editor Content section in the CKEditor documentation. Please refer to the CKEDITOR.styleSet object definition for full details on each option. The Styles section also has some useful information.
Editor Content CSS
Mura's web editor, CKEditor, can include your own CSS files to be used to apply style to the editor content. Generally, these styles should reflect the CSS used in the target pages where the content is to be displayed.
Mura automatically scans for specific files within your theme, specifically for this purpose. Listed below are the files Mura checks for in the specified order.
../themes/{ThemeName}/css/editor.css.cfm../themes/{ThemeName}/css/editor.css
Using the first option with a ".cfm" file extension, allows you the ability to include dynamic code, in the event you wanted to do so.
The default theme for Mura as of v7.1, MuraBootstrap4, includes a sample file with basic styles included. You can find it under ../MuraBootstrap4/css/editor.css. Any style definitions found in the file are applied to content entered in the editor body/content area.
For example, if you wanted to set the color of <h2> and <h3> tags to "green", you could add the following to your CSS file.
h2, h3 {
color: green;
}
The example image below illustrates the result of the <h2> tag (visible due to the Show Blocks button being enabled).
Your style definitions may also affect the styles of elements in the Paragraph Format select menu.
Where to Learn More
The CKEditor documentation has more information. The section on Applying Block-Level Text Formats contains some useful information as well.
Editor Body Templates
Mura includes the Content Templates plugin for CKEditor, which provides a dialog to offer predefined content templates - with page layout, text formatting and styles. It comes with a couple of sample templates, and theme developers may also create their own templates.
This feature only impacts the "Content/Body" area of the layout, and is separate from Mura's layout templates.
To see the sample templates in action, select a content item to edit, and locate the template button on the web editor toolbar. It's typically located on the last row, just before the Mura [m] tag button, as highlighted below.
Clicking the template button will launch the Content Templates dialog window.
The sample layouts include 2 Columns, 3 Columns, and 4 Columns. If "Replace actual contents" is enabled, all content will be deleted and replaced with the sample content. If you wish to disable this feature by default, you can add config.templates_replaceContents = false; to your editor's configuration settings.
The options on this dialog window are controlled by files located under the theme at ../themes/{ThemeName}/js/editor/templates/. Example files can be found in the default theme for Mura as of v7.1, currently MuraBootstrap4.
The images directory contains the preview images that will display in the dialog window.
The default.js file contains the code used by CKEditor for the templates.
If you open the default.js file, you'll see where the "templates" are defined.
Each template definition should include the following:
title
- This is the text used next to the image in the dialog window as the Title.
image
- This is the image file used for the example layout to be displayed in the dialog window.
description
- This text will display under the Title in the dialog window.
html
- This markup is used to populate the web editor, if the template is selected.
You may add, modify, replace, or delete, any of the examples included.
Note: The sample default.js file included with MuraBootstrap4 includes the use of Bootstrap class names. You may want to modify these to match your own framework's classes.