6.2.2Customizing richtext input

The richtext input field is the most flexible input field and thus has a own way to be customized.

As editor for handling richtext cmsWorks integrats the 3rd party product TinyMCE. TinyMCE is highly configurable thus in features, behavior and design. Also integrated cmsWorks specific plugins to enable linking to other cmsWorks documents or setting text components using other cmsWorks resources. All configuration properties of the following list belong to the current release of TinyMCE that is included in the current cmsWorks release.

var customer_modification = {
  ...
  "richtext": {
    "tinymce": {
      "block_formats": "Paragraph=p;Headline 2=h2;Headline 3=h3;", // the block formats dropdown of the toolbar
      "style_formats": [ // the style formats dropdown / menu of the toolbar
        {"title": "Text", "items": [ // this is a submenu
          {"title": "Interview name", "inline": "span", "classes:" "ivname"},
          {"title": "Cite", "inline": "span", "classes": "quote"},
          {"title": "Label", "inline": "span", "classes": "label"},
          {"title": "Live", "inline": "span", "classes": "live"}
        ]},
        {"title": "Links", "items": [
          {"title": "External link", "selector": "a", "classes": "linkExt"},
          {"title": "PDFDownload", "selector": "a", "classes": "linkPDF"}
        ]},
        {"title": "Tables", items: [
          {"title": "Standard Table", "selector": "table", classes": "taStd"},
          {"title": "Table 100%", "selector": "table", "classes": "wide"},
          {"title": "Alternating colors light/dark", "selector": "table", "classes": "ac"},
          {"title": "Table Headline", "selector": "tr", "classes": "taHead"}
        ]}
      ],
      "valid_elements": // valid elements of the HTML code
        "a[!href|class|title]," +
        "#p[class]," +
        "br," +
        "-h2/h1," +
        "-h3/h4/h5," +
        "#h6," +
        "-span[!class]," +
        "-table[class|style|width]," +
        "-tr[class|style]," +
        "#td/th[class|colspan|rowspan|style|align]," +
        "-ol[class]," +
        "-ul[class]," +
        "-li," +
        "-b/strong," +
        "-i/em," +
        "-u/strike",
      "plugins": [
        "searchreplace advlist lists link anchor table code paste itwcomponent"
      ],
      "toolbar":component uncomponent | table | styleselect removeformat | bold italic underline | " + 
        "formatselect | bullist numlist | link unlink code | undo redo searchreplace"
    }
  },
  ...
}

The properties and their functionalities depend on the respective functionalities of the used TinyMCE plugin version.

TinyMCE produces richtext encoded as HTMLm that means you one is working on tags and properties and text in an hierarchical structure. Some tags are defined as block formats (p, h2, div), some tags are used as inline formatter (i, b, span) and some tags have kinds of special abilities (for instance table/tr/td for table structures, ul/li for unordered list entries or ol/li for ordered list entries). Attributes like "class" are used to customize the layout of a tag and may be used on any available tag.

The used configuration properties above are a summarized example of previous cmsWorks projects. Let's explain the properties in detail:

block_formats

"block_formats": "Paragraph=p;Headline 2=h2;Headline 3=h3;", // the block formats dropdown of the toolbar

Using these block formats the Blocks-dropdown in the TinyMCE toolbar will then show the following three entries:

• Paragraph - using the p-tag
• Headline 2 - using the h2-tag
• Headline 3 - using the h3-tag

Thereby the default block tag in TinyMCE is the "p-tag".

Selecting another block tag by using the dropdown changes the current block to the selected block type. You do not have to select the block completely to change it, just placing the cursor into the block wil suffice. Selecting the same block type again will fallback to the default p-tag.

style_formats

"style_formats": [ // the style formats dropdown / menu of the toolbar
  {"title": "Text", "items": [ // this is a submenu
    {"title": "Interview name", "inline": "span", "classes:" "ivname"},
    {"title": "Cite", "inline": "span", "classes": "quote"},
    {"title": "Label", "inline": "span", "classes": "label"},
    {"title": "Live", "inline": "span", "classes": "live"}
  ]},
  {"title": "Links", "items": [
    {"title": "External link", "selector": "a", "classes": "linkExt"},
    {"title": "PDFDownload", "selector": "a", "classes": "linkPDF"}
  ]},
  {"title": "Tables", items: [
    {"title": "Standard Table", "selector": "table", classes": "taStd"},
    {"title": "Table 100%", "selector": "table", "classes": "wide"},
    {"title": "Alternating colors light/dark", "selector": "table", "classes": "ac"},
    {"title": "Table Headline", "selector": "tr", "classes": "taHead"}
  ]}
],

In the style_formats section menu classes are assigned to tags according to the styling purpose of the project.

{"title": "Interview name", "inline": "span", "classes": "ivname"},

The "title" is shown in the formats dropdown. "inline" defines the tag we are working on. "classes" are the classes that are set for the tag. There may be added also multiple classes like for instance "ivname special"

{"title": "External link", "selector": "a", "classes": "linkExt"},

There is a difference in using "selector" or "inline".

If "selector" is used, the cursor can be placed anywhere in the text of the tag, selecting the style via the formats combobox will set the style only to the declared tag.

If "inline" is used, a new tag will be inserted (like <i>...</i>) or removed (if already existing).

For table tags or links it is not advisable to use the "inline" method because the format combobox should only set or remove styles, rather it must not remove links or destroy table structures.

valid_elements

"valid_elements": // valid elements of the HTML code
  "a[!href|class|title]," +
  "#p[class]," +
  "br," +
  "-h2/h1," +
  "-h3/h4/h5," +
  "#h6," +
  "-span[!class]," +
  "-table[class|style]," +
  "-tr[class|style]," +
  "#td/th[class|colspan|rowspan|style|align]," +
  "-ol[class]," +
  "-ul[class]," +
  "-li," +
  "-b/strong," +
  "-i/em," +
  "-u/strike",

This is the list of elements allowed in the richtext editor. A tag inserted that is not in this list will be removed. The full explanation of the rules can be found on the TinyMCE documentation pages, anyway, here are some examples:

The above listing of allowed tags does not contain a div-Tag since this is not really part of a text. It also has no image tag defined because cmsWorks uses text components to place images, embeds or other objects of that kind. That is because text components normally would have more content fields like (for an image) a title, origin, dimensions or subformats. Keeping the amount of tags enabled for richtext low supports an easier distribution of the text in various content formats (HTML, XML, Plain-Text, pdf, ...).

Text components

Just as a tiny digression, a text component is a special tag containing a reference to another document storing its ID combined with a placement (normally one of Left|Right|Centered|Inline). The text component can be added by adding "component uncomponent" to the toolbar and "itwcomponent" as plugin. The configuration of the placement is done in the richtext section of the customer_modification.

plugins

"plugins": [
  "searchreplace advlist lists link anchor table code paste itwcomponent"
],

This is the list of Plugins currently in use at cmsWorks. Any additionally desired plugins may be placed in here. Only the itwcomponent is a self created plugin handling text component placements.

toolbar

"toolbar": "component uncomponent | table | styleselect removeformat | bold italic underline | " + 
  "formatselect | bullist numlist | link unlink | undo redo searchreplace"

The definition of the elements shown in the TinyMCE toolbar.

More properties

Using the documentation of TinyMCE there are much more properties that can be used to adjust the richtext input field. Just put them into the q-custom.js, reload the cmsWorks editors desktop and test their functionality.