TinyMCE Editor and Alfresco
TinyMCE is a platform independent; web based WYSIWYG editor that Alfresco uses as a rich text editor in Share. It is released as Open Source under LGPL by Moxiecode Systems AB.
TinyMCE is straight forward to integrate into web applications and it is the default WYSIWYG editor of the Alfresco ECM. A few examples of TinyMCE being used in Alfresco ECM are as follows;
· Adding a comment to documents
· Creating a new blog
· Editing an existing blog
· Replying to a blog by adding a comment
· Creating a new discussion
· Editing a discussion
· Replying to a discussion
The purpose of this blog is to show how the TinyMCE editor can be customised for Share.
Alfresco Comment Box
The alfresco comment box uses a very minimal version of TinyMCE with very limited features. The comment box is implemented as a single component for adding comments to documents and also to reply to blogs. Recently one of our customers pointed out some of the constraints of the comment box which made it not very user friendly and these were as follows;
· The Editor is not consistent for all Alfresco Share functions (For example TinyMCE for Comment box is different from Discussion editor)
· Very limited set of the TinyMCE functions available. TinyMCE supports many formatting options which are not made available by default.
· The comment box is not resizable (From Alfresco 4.xxx onwards)
· When copying and pasting into the comment box while using Internet Explorer 9 and Alfresco 4.1.1, TinyMCE adds double spacing between new lines, whereas for other browsers and versions it uses single spacing.
Customising the Alfresco Comment Box
The normal way to customise TinyMCE is to make configuration changes within the tinyMCE.init () JavaScript call. This call is usually made from outside TinyMCE. But as TinyMCE is configured in many places in Alfresco, configuration is injected via javascript that is created by webscripts for each instance of TinyMCE.
Depending on the context we are in, Alfresco renders the TinyMCE editor based on a Freemarker file that is associated via the webscript that renders the TinyMCE instance . When a page containing a comment box is rendered in Alfresco Share, the page options (.setOptions ()) are usually set through the embedded JavaScript in the Freemarker file and one of the options which has to be set is the one for the editor (editorConfig: {}).
So in order to customise TinyMCE for Alfresco Share Comment Box, the comment-list.get.html.ftl needs to be modified. The comment-list.get.html.ftl freemarker file is located at $Alfresco_Home/tomcat/webapps/share/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/comments
It is recommended to copy the comment-list.get.html.ftl freemarker file to the extension directory ($Alfresco_Home/tomcat/shared/classes/alfresco/web-extension/site-webscripts/org/alfresco/components/comments) and make any changes there.
Now that we know which file we need to modify, let us have a look at what we want to change.
Adding More Features or Buttons to TinyMCE
In order to add more buttons to the editor, we need to use the TinyMCE Advanced Themes. A complete list of all the Advanced Themes can be found on http://www.tinymce.com/wiki.php/Configuration:Advanced_theme .
Let’s have a look at the default TinyMCE configs in comment-list.get.html.ftl
editorConfig:
{
inline_styles: false,
convert_fonts_to_spans: false,
theme: “advanced”,
theme_advanced_buttons1: “bold,italic,underline,|,bullist,numlist,|,forecolor,|,undo,redo,removeformat”,
theme_advanced_toolbar_location: “top”,
theme_advanced_toolbar_align: “left”,
theme_advanced_resizing: true,
theme_advanced_buttons2: null,
theme_advanced_buttons3: null,
theme_advanced_path: false,
language: “${locale?substring(0, 2)?js_string}”
}
The configs shown above renders the comment box as follows.
If we examine the configs above, we can see theme_advanced_buttons1: “bold, italic, underline,|, bullist, numlist,|, forecolor,|, undo, redo, removeformat” but theme_advanced_buttons2: null and theme_advanced_buttons3: null. This shows that each theme_advanced_buttons (n) is an actual row in the editor which can be populated with functions we require.
For example changing the line
theme_advanced_buttons2: null to theme_advanced_buttons2:”|,justifyleft,justifycenter,justifyright,justifyfull,|” would result in the following comment box.
TinyMCE’s functionality can be extended by using Plugins. A list of all available plugins in the standard TinyMCE package can be found on http://www.tinymce.com/wiki.php/Plugins. We first need to tell TinyMCE which Plugin we want to use and then add in which function of that plugin we want to show on the editor user interface.
For example, we can provide a button on the editor to allow a user to make the comment box go fullscreen. We achieved this by adding plugins:”fullscreen”, to the editor config in comment-list.get.html.ftl, and then changing theme_advanced_buttons2:”|,justifyleft,justifycenter,justifyright,justifyfull,|fullscreen”
As it can be seen above there’s an extra blue button added and by clicking on that the user can use the comment box in full screen.
Hence we can add more plugins and consequently have more functions available to use in the editor.
Making the comment box resizable
The comment box used to be resizable in Alfresco prior to the 4.xxx versions. Recently we did an upgrade from Alfresco 3.4.7 to 4.1.1 for one of our customers and they needed to have resize functionality available. We queried Alfresco Support in this regard and they responded that the resizing functionality was scrapped as a fix to this jira https://issues.alfresco.com/jira/browse/ALF-1258 where the resizing of the comment box on 3.4.x was broken as one could extend it across the right-hand column but could not then resize it back.
So besides the Fullscreen option described previously, the comment box can be customised to have a resizable height and a fixed width to tackle the issue mentioned in https://issues.alfresco.com/jira/browse/ALF-1258.
By adding theme_advanced_statusbar_location: “bottom”to the editor config in comment-list.get.html.ftl, we make the comment box window resizable through a notch which can be dragged. Then in order to make only the comment box height resizable and the width fix, we need to add theme_advanced_resizing_max_width: 700to the editor config in comment-list.get.html.ftl.
The screenshot below shows the customised comment box we implemented for our client.
Internet Explorer 9 and TinyMCE
Although Alfresco states IE9 as a supported browser, for some reasons TinyMCE adds an extra <p>nbsp</p> to every newline while copying and pasting from MS Word. The solution to this issue is to replace <p>nbsp</p> by <br>. This can be accomplished by adding the following lines to the editor config in comment-list.get.html.ftl.
forced_root_block : false,
force_br_newlines : true,
force_p_newlines : false,
TinyMCE in Alfresco Share Blogs and Discussions
TinyMCE is not rendered in the same way for Blogs and Discussions in Alfresco share. For example if someone replies to a discussion, a different editor is rendered compared to the one used while replying to a blog (A comment box is used to reply to a blog).
As mentioned previously, Alfresco Share renders the TinyMCE editor based on the associated Freemarker file, so in order to make the editor more consistent across Alfresco Share, each associated freemarker files for the editor needs to be modified.
Standardising how TinyMCE works across all of Share requires updating the configurations for the editor for Document Comments, Blogs and Discussions. The files that need to be changed are shown below:
Blogs
There are 3 freemarker files associated with Blogs and TinyMCE in Alfresco Share and these are as follows;
createcomment.get.html.ftl located at
$Alfresco_Home/tomcat/webapps/share/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/blog and used to create new blog post.
postedit.get.html located at
$Alfresco_Home/tomcat/webapps/share/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/blog and used to edit a blog post.
comment-list.get.html.ftl located at
$Alfresco_Home/tomcat/webapps/share/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/comments and used to add or edit comment.
Discussions
There are 2 freemarker files associated with Discussions and TinyMCE in Alfresco Share and these are as follows;
createtopic.get.html.ftl located at
$Alfresco_Home/tomcat/webapps/share/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/discussionsand used to create new discussion topics.
replies.get.html.ftl located at
$Alfresco_Home/tomcat/webapps/share/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/discussionsand used to reply discussion topics.
Once the required customisations have been decided, we recommend copying all these files to the Alfresco Share extension directory ($Alfresco_Home/tomcat/shared/classes/alfresco/web-extension/site-webscripts/org/alfresco/components) and then make the required changes there.
