Configuring the Rich Text Editor

The TinyMCE distribution is now in a single location.  This is an untouched distribution from tinyme and no longer contains any percussion customizations.  This folder will be replaced on upgrade and patches with new versions if available.  All the percussion configuration is made in the sys_resources folder structure and customers should not modify these files.  The configuration mechanism documented here allows for us to deliver and update a core default configuration but still provide the customer to override and modify configurations for the whole system, or individual fields.  

Folder structure

All user configuration should be made to the following file. but may reference customer files, css, plugins added into rx_resources/tinymce or web_resources folders.

rx_resources/tinymce/config/customer_config_override.json

Most of the configuration is passed through to the tinymce editor.  Information about available configuration options can be found here https://www.tinymce.com/docs/configure/  Some tinymce options may prevent the proper functioning of the editor, or the percussion plugins.

Configuration Loading structure

Percussion will ship with default configuration for tinymce.  This configuration is delivered in sys_resources/tinymce/js/tinymce_init.js.  This file can be replaced on patch or upgrade and customer configuration should not be applied in here.

On top of the default configuration each widget can point to a configuration file for additional configuration or override the base configuration.  There are two files we ship default_config.json contains a general configuration used for most of the editors we ship including the Rich Text Asset.  simple_config.json contains a stripped down configuration that is intended to be used where very basic html is required with no relationships to other items.    Both of these files will be replaced on patch or upgrade.  These files can be referred to compare the configuration that is shipped, or to copy the list of plugins and toolbar to use as a base for the custom configuration.

If the configuration that is provided from the base, and widget need to be customized this can be done in rx_resources/tinymce/config/customer_config_override.json  This file will be created if it does not exist but will not be patched or updated.  

Current Widget default configuration

default_config.json

[{
"config_css": "../sys_resources/css/tinymce/content.css",
"menubar": "edit insert view format table tools",
"plugins": "advlist,lists,table,searchreplace,paste,directionality,fullscreen,noneditable,visualchars,nonbreaking,anchor,charmap, hr,emoticons,code,textcolor,percadvlink,percmorelink,percglobalvariables,percadvimage",
"toolbar": "undo redo | styleselect | bold italic | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | link unlink | image",
"valid_elements": "*[*]"
}]

simple_config.json

[{
"config_css": "../sys_resources/css/tinymce/content.css",
"menubar": "null",
"plugins": "-example",
"toolbar": "bold,italic,underline,undo,redo,formatselect",
"valid_elements": "*[*]"
}]Configuration file structure and format

Note the tinymce documentation defines a javascript object style,  the configuration we use is a json format file.  These are very similar but there are a few things to be aware of. 

1. Configuration file needs to be a valid json object.  There are a couple of differences to the syntax used in the tinymce documentation
2. key names need to be enclosed in double quotes. 
3. Comments cannot be used in the file
4. false and true are not strings so should not be wrapped in quotes
5. numbers should not be wrapped in quotes
6. "selector" should not be overridden in the percussion configuration

The following example style from tinymce documentation:

[{
"config_css": "../sys_resources/css/tinymce/content.css",
"menubar": "null",
"plugins": "-example",
"toolbar": "bold,italic,underline,undo,redo,formatselect",
"valid_elements": "*[*]"
}]

To use the default configuration for all the editors customer_config_override.json can simply be an empty json array.  If there are problems after patch or upgrade,  it is recommended to test whether any issues by changing back this file to this empty array (simply an open and close square bracket) to see if the issue is caused by the custom configurationShould be put into the percussion config as:

[]

The customer_config_override.json file enables the setup of multiple configuration blocks allowing a fine grained override of specific fields.  A filter mechanism is used to identify which configuration should be used every time the editor is loaded.  Currently the configurations can be filtered based upon Multiple configurations in same file

1. The Widget Asset type name ( all rich tinymce fields in editor)
2. The specific widget type name and field name  
3. The current user's available roles ( e.g. only enable code view for Admin users ) 

Multiple configurations can be added, after configurations that are not valid for the current field and user role, each configuration adds or updates the values of the previous.  In this way general configuration that applies to all fields can be added to a single configuration block, and only the exceptions for different field and role combinations need to be added to separate blocks.

Configuration Filters

Roles and fields can be used to filter configurations.  If neither of these is specified the configuration will be used for all TinyMCE fields unless a subsquent configuration in the list matches

roles 

A list of roles that will use this configuration:

"roles": ["Editor","Admin"]

fields

A list of fields that will use this configuration.  Just the asset type name can be used to use to select all rich text fields on the asset.  Currently no Percussion assets ship with more than one field so either format could be used unless using a custom widget using rich text.

"fields": ["percRichTextAsset.text", "percBlogPostAsset.postbody"]

 or:

"fields": ["percRichTextAsset"]

Current editors and fields

Customer Override Configuration Example

The following configuration is an example to demonstrate the override feature. 

This would

1. Add a custom css file to be used for all editors
2. Add fullscreen button to the Rich Text Widget and remove the code menu option from the Rich Text Widget for users not in Admin role.
3. If the widget is the Rich Text widget and the user is in the  Admin role the fullscreen button would show AND the code view is available.

More general configuration blocks should go first as the last valid configuration for the field and roles is selected.  If multiple blocks are not filtered for the current user roles and field subsequent valid blocks will override previous blocks. In this example If the user is an Admin user and using the Rich Text editor they would still get the same content_css configuration specified in the first block unless a different value was applied.  Each block only needs to specify the configuration that is different than the preceding ones that are applied.  Someone editing the Simple Text widget would get the default configuration for that with the content_css value in this file as that is the only one that is not filtered out.

[{
 "content_css": "../web_resources/themes/mythemes/bodystyles.css"
}, {
 "fields": ["percRichTextAsset"],
 "plugins": "advlist,lists,table,searchreplace,paste,directionality,fullscreen,noneditable,visualchars,nonbreaking,anchor,charmap, hr,emoticons,textcolor,percadvlink,percmorelink,percglobalvariables,percadvimage",
 "toolbar": "undo redo | styleselect | bold italic | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | link unlink | image | fullscreen"
}, {
 "fields": ["percRichTextAsset"],
 "roles": ["Admin"],
 "plugins": "advlist,lists,table,searchreplace,paste,directionality,fullscreen,noneditable,visualchars,nonbreaking,anchor,charmap, hr,emoticons,code,textcolor,percadvlink,percmorelink,percglobalvariables,percadvimage",
 "toolbar": "undo redo | styleselect | bold italic | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent | link unlink | image | fullscreen"
}]

custom behavior of tinymce configurations

content_css: 

This is a tinymce property that allows adding a css stylesheet that will be used with the tinymce body.  If config_css is specified in the custom configuration unlike other properties it will not replace the underlying value but will add to the comma separated list of css files.  by default this is "../sys_resources/css/tinymce/content.css".  Customer css could be placed in a directory under rx_resources if the same file is not going to be used on the published website e.g. installdir/rx_resources/tinymce/css/mytinymce.css or uploaded into web_resources from the CM1 UI

external_plugins

We currently ship 4 percussion plugins percadvimage, percadvink, percglobalvariables and percmorelink. 

If additional third party custom plugins are required they should be placed in rx_resources/tinymce/plugins and referenced with the external_plugins tinymce configuration.  The code will automatically append the percussion plugins.  This defines the location of the plugins, to use them you would configure in "plugins" configuration and others based upon the specific plugin.

style_formats: 

For backwards compatibility by default style_formats are configured from rx_resources\css\PercRichTextCustomStyles.properties.  This is a global configuration and this file may no longer be used in the future so it is advised to instead add any required custom styles to the the customer_config_override.json file

By defining the "style_formats" configuration in the custom configuration file, you will replace the styles defined in PercRichTextCustomStyles.properties and have the choice of appending formats to the base TinyMCE formats or replacing all the style formats.  See the tinymce documentaion on style_formats and style_formats_merge.  If stye_formats_merge is set to false then the default tinymce style list will not be added.  Below is an example explicitly specifying all the styles

This example only adds the Custom Styles menu but keeps the default options.

valid_elements

the editor is by default configured with this value set as "*[*]" Which will allow all elements and all attributes.  It is advised not to override this as it may filter out attributes and elements required for the related images and links to be processed correctly.

width:

The default width is now set as 100% to fill the full width of the editor when it resizes

height

The default height is set from the widget asset configuration, this can be modified in the custom configuration if required.  The user can now increase the size of the asset editor dialog to full screen as long as the fullscreen plugin is enabled.  Also the editor itself can be expanded the full size of the dialog with the FullScreen option  (Ctrl-Shift-F) from the view menu.  A button can be added to the toolbar by adding the "fullscreen" option to the "toolbar" configuration

Tinymce configurations that should not be changed

These options should not be modified as doing so may break the editor and prevent it working.  This is not an exhausted list.  If you find problems with a particular configuration option remove it and check with Percussion.

editor_selector

mode

init_instance_callback

file_browser_callback

convert_urls

autosave_restore_when_empty

Spell Checking

The default behavior for Spell Checking in the editor is to use the browsers native spell checker.  

When creating a custom editor configuration it is important to make sure that native browser spell checking is turned on with the following setting:

"browser_spellcheck": true

This is a top level property similar to plugins or toolbar in the configuration.

Debugging Configuration

If the json file is not syntactically correct a dialog will appear with the error and line number.  Common problems include missing commas between configurations, an extra comma on the last line of a configuration,  mismatched braces or square brackets. key not enclosed in double quotes.  You can use a editor that validates json, a browser plugin that edits json, or use an online validator e.g. https://jsonlint.com/. Turning on the Developer Tools in the browser should enable you to see the javascript console.  When the editor loads the final configuration sent to tinymce after all the configuration files are merged will be displayed in the console to help with debugging.  It is also possible that changes are not being picked up if they are being cached by the browser and the browser cache should be flushed.