August 22, 2013

Customized multifield richtext editor – Part 1

 

I came across a requirement in which I had to build a multifield richtext field with some customizations. As such it was not very complex but I thought if I can gather all the pieces and put it in one place this could be helpful to other people in community so here you go.

Note:

  1. I am using CRXDE Lite and CQ 5.6.1 for this article
  2. Save your work as often as you make ANY change.
  3. Please refer to “Configure the rich text editor” for more information on list of plugins and features available in CQ.

 

List of Customizations:

I have divided this article into 2 part series. Below is the list of items that will be covered in each part.

PART -1 (these topics are covered in this post)

  1. Create a multi richText field,
  2. Common rte configuration – build once use often
  3. Customize default plugins
    • remove default plugins
    • restrict features in default plugins
  4. Activate a (non-default) Plugin,
    • adding your own special character,
    • Adding default (OOB) special characters back.

PART -2 (these topics will be covered in my next post)

5.  Use css styles in your rte(strikethrough),
- Using externalStyleSheet with rte,
6.  Add formatting (for H4),
7.  Remove default p tag in rte (limited scope),
8.  Make “plaintext” as default Paste Mode (strip extra HTML on paste)

1. Creating a multi richText field

a. Create a component with a simple text field (title in my example).
Screen Shot 2013-08-20 at 1.54.14 PM

 

b. Change the xtype from ‘textfield’ to ‘multifield’ and you have your simple text multifield.
Screen Shot 2013-08-20 at 1.55.43 PM
above: setting the xtype as multifield

Screen Shot 2013-08-20 at 1.57.11 PM
above: screen shot of the simple text multifield

c. Now this is where I feel the power of CQ lies (where magic happens). Create a new node ‘fieldConfig’ of type ‘nt:unstructured’ under ‘title’ (your multifield) node. Add a property ‘xtype’ with value as ‘richtext’. Boom, you now have your multifield rich text editor with default plugins.

Screen Shot 2013-08-20 at 3.33.38 PM

above: setting the xtype as richtext

Screen Shot 2013-08-20 at 3.33.51 PM

above: a view of multifield richtext with default plugins and features

 

2. Common rte configuration – build once use often

Before we start customizing our rich text editor I would like show you a way to create a ‘reference node’ for your rich text editor. The benefit that you get out of this ‘reference node’ is that you make all your changes for adding and configuring plugins and their properties at one place (this reference node) and it can be applied to all components which refer to this

1. Create a component to store the configuration that will be referred by other components.

Screen Shot 2013-08-21 at 2.10.52 PM

2. Create a new node called ‘rtePlugins’ of type ‘nt:unstructured’ under ‘rteconfig’ (your component) node. We will create all nodes for configuring the rte (plugins and fetures) under this node.

Screen Shot 2013-08-21 at 2.21.12 PM

3. Now we will link our demo component’s rich text field to this common config field. To do this create a new node called ‘rtePlugins’ of type ‘cq:Widget’ under ‘fieldConfig’ node.

Screen Shot 2013-08-21 at 2.25.08 PM

4. Next we will create 2 properties for this ‘rtePlugins’ node (/apps/blog/components/content/demo/dialog/items/items/title/items/title/fieldConfig/rtePlugins)

Property 1:

name: xtype, value: cqinclude

Property 2:

name: path, value: /apps/blog/components/content/rteconfig/rtePlugins.infinity.json

Note: the value in property 2 points to the path for the config node that you created followed by .infinity.json

Screen Shot 2013-08-21 at 4.37.57 PM

 

From here onwards we will do all changes to the rteconfig node and it will be reflected in our demo component which references rteconfig for rich text editor configurations.

3. Customize default plugins

 a). remove default plugins

For our sample we will remove the ‘justify’ plugin and all of the features that come with it.

Please refer to “Configure the rich text editor” for more information on list of plugins and features available in CQ.

Screen Shot 2013-08-21 at 5.07.46 PM

1. Traverse to your rteconfig/rtePlugins node (/apps/blog/components/content/rteconfig/rtePlugins) and create a child node of type ‘nt:unstructured’ and name it ‘justify’.

2. Create a property called ‘features’ of type String[] (multi) under ‘justify’ node. Leave the value as empty/blank for ‘features’ property.

Screen Shot 2013-08-21 at 5.18.32 PM

3. Now go back to your content page and refresh it. You should not see any of the features from the’ justify’ plugin.

Screen Shot 2013-08-21 at 5.22.28 PM

You have now changed the default plugins to make your on list. If you need to remove other plugins you can create nodes similar to ‘justify’ for the specific plugin that you want to remove and create/copy the features property in that node.

Another IMPORTANT thing is that we made all these changes in the config node so now you can reuse this configuration as often as needed.

b). restrict features in default plugins (activating specific features for a plugin)

Please refer to “Configure the rich text editor” for more information on list of plugins and features available in CQ.

Now we will look at an example in which we will restrict features one of the default plugins. Each plugin node can have a features property configured to activate, or deactivate, one or more features.

The ‘links’ plugin is used to create hyperlinks in your rte. It has 3 features- ‘modifylink’, ‘unlink’ and ‘anchor’. In the following example we will remove the ‘anchor’ feature from the ‘links’ plugin.

Screen Shot 2013-08-21 at 5.35.42 PM

1. Traverse to your rteconfig/rtePlugins node (/apps/blog/components/content/rteconfig/rtePlugins) and create a child node of type ‘nt:unstructured’ and name it ‘links’.

2. To restrict a particular ‘feature’ in any of the plugins you have to create an array (String[]) for features and add the specific features that you need in the array list. Create a property called ‘features’ of type String[] (multi) under ‘links’ node.

3.  Now, to remove the ‘anchor’ feature, we will add only the two required features (out of the 3 available options)- ‘modifylink’ and ‘unlink’.

Screen Shot 2013-08-21 at 5.54.15 PM

4. Now go back to your content page and refresh it. You should see restricted list of features (‘modifylink’, ‘unlink’) from the’ links’ plugin.

Screen Shot 2013-08-21 at 6.02.59 PM

 

 

4. Activate a (non-default) Plugin

In this section we will Activate the Miscellaneous tools (‘misctools’) Plugin. We will also look at whats different when activating all features for a new plugin vs. activating specific features for a plugin that I explained in section 3.(b) above.

Miscellaneous tools allowing you to enter special characters or edit the HTML source both of which are pretty commonly used with the rich text editor.

First we will add this plugin (the process for which is exactly similar to default plugins) and then we will enable ALL its features- special characters and edit the HTML source code. Lets begin.

1. Traverse to your rteconfig/rtePlugins node (/apps/blog/components/content/rteconfig/rtePlugins) and create a child node of type ‘nt:unstructured’ and name it ‘misctools’.

2. Create a property called ‘features’ of type String under ‘misctools’. Please note the type for the ‘features’ property in this scenario is just String as compared to Sting[] (multi) that we used while activating specific features for a plugin in section 3.(b).

3. To enable ALL  features for the ‘misctools’ enter the value as “*” for the ‘features’ property.

Screen Shot 2013-08-21 at 6.24.43 PM

4. Now go back to your content page and refresh it. You should see ALL features (‘specialchars’, ‘sourceedit’) from the ‘misctools’ plugin.

Screen Shot 2013-08-21 at 6.26.11 PM

 

a). Adding your own special characters:

When the ‘misctools’ plugin is enabled  a default list of special characters is immediately available for use; for example, the copyright and trademark symbols.

Screen Shot 2013-08-21 at 6.35.21 PM

You can configure the RTE to make your own selection of characters which I will show in the example below.

NOTE: Adding your own special characters will override the default OOB special characters. If you need them you will have to add those in.

1. Traverse to your rteconfig/rtePlugins/misctools node (/apps/blog/components/content/rteconfig/rtePlugins/misctools).

2. Create a child node under ‘misctools’ of type ‘nt:unstructured’ and name it ‘specialCharsConfig’.

3. Create a child node under ‘specialCharsConfig’ of type ‘nt:unstructured’ and name it ‘chars’. This ‘chars’ node will hold the list of characters.

Screen Shot 2013-08-21 at 6.43.28 PM

4. Under ‘chars’ add a new node to hold an individual character definition. The type for this child node is ‘nt:unstructured’ again. The name for this child node should reflect the character; for example, pound.

Screen Shot 2013-08-21 at 6.48.18 PM

5. To the ‘pound’ node add a property with name as ‘entity’, type as String and value as the HTML representation of the required character; for example, £ for pound.

Screen Shot 2013-08-21 at 6.52.32 PM

6. Now go back to your content page and refresh it. You should see pound sign in the list of special characters.

Screen Shot 2013-08-21 at 6.56.39 PM

 

b). Adding default (OOB) special characters back:

A mentioned previously, adding your own special character overrides the default OOB list and we need to add it again if we need it. Lets go ahead and add some of the stuff back.

1. Trademark: Under ‘chars’ add a new node. The type for this child node is ‘nt:unstructured’ again. The name for this child node should reflect the character; for example, trademark.

2. To the ‘trademark’ node add a property with name as ‘entity’, type as String and value as the HTML representation of the required character; for example, ™ for pound.

3. Now go back to your content page and refresh it. You should see trademark sign in the list of special characters.

Screen Shot 2013-08-21 at 7.44.28 PM

Note: You can repeat above steps to add any number of characters that you need.

Hope this helps.

 

 

 

4:25 PM Permalink