close

Filter

loading table of contents...

Studio Developer Manual / Version 2101

Table Of Contents

7.4.5.5 Customizing Richtext Toolbar

The buttons and menu items of the toolbar can be customized by applying the addItemsPlugin and removeItemsPlugin to richTextPropertyField. The item ids of the buttons and menu items provided are listed as constants in the ASDoc of richTextPropertyField.

It is also possible to add a toolbar button for a custom plugin or a CKEditor plugin.

When adding a new button to the toolbar and you want it to perform a CKEditor command, you can use the RichTextAction with the configured command name. Currently used commands are listed as constants in the ASDoc. When the new button should display a state (like for example the "bold" button renders as pressed when a bold text is selected), make sure to set the config option enableToggle on the button to true, or use the convenience class RichTextActionToggleButton which does just that.

Note that all RichTextActions have a mandatory config option ckEditorValueExpression. When using the RichTextMenuCheckItem or RichTextMenuItem, or if you define a button or menu item for the RichTextPropertField toolbar or context menu yourself and they contain a RichTextAction you must set the ckEditorValueExpression config option.

When adding or extending a menu in the toolbar and the menu items should perform richTextActions for context-sensitive CKEditor commands, you should use the richTextMenuCheckItem for a correct representation of the enabled and active states of the command. See the ASDoc for more information.

Add the functionality into a Studio plugin that can be used in the richTextPropertyField configuration (see Section 7.1, “Studio Plugins” and especially the warning box why a separate file is necessary). The following code, included in a file CustomizeRichTextPlugin.mxml, moves the italic button between the internal link and external link button and removes the heading 3 paragraph format menu from the rich text toolbar.

<ui:NestedRulesPlugin
        xmlns:fx="http://ns.adobe.com/mxml/2009"
        xmlns:exml="http://www.jangaroo.net/exml/0.8"
        xmlns="exml:ext.config"
        xmlns:ui="exml:com.coremedia.ui.config">
  <fx:Script><![CDATA[
    import com.coremedia.cms.editor.sdk.premular.fields.RichTextPropertyField;
    import com.coremedia.ui.ckeditor.RichTextAction;

    private var config:CustomizeRichTextPlugin;
    public native function CustomizeRichTextPlugin(config:CustomizeRichTextPlugin = null);
    ]]></fx:Script>

  <ui:rules>
    <Toolbar>
      <plugins exml:mode="append">
        <ui:RemoveItemsPlugin>
          <ui:items>
            <Component itemId="{RichTextPropertyField.ITALIC_BUTTON_ITEM_ID}"/>
          </ui:items>
        </ui:RemoveItemsPlugin>
        <ui:AddItemsPlugin>
          <ui:items>
            <ui:RichTextActionToggleButton itemId="{RichTextPropertyField.ITALIC_BUTTON_ITEM_ID}"
                                           commandName="{RichTextAction.COMMAND_ITALIC}"/>
          </ui:items>
          <ui:after>
            <Component itemId="{RichTextPropertyField.INTERNAL_LINK_BUTTON_ITEM_ID}"/>
          </ui:after>
        </ui:AddItemsPlugin>
      </plugins>
    </Toolbar>

    <Menu>
      <plugins exml:mode="append">
        <ui:RemoveItemsPlugin>
          <ui:items>
            <Component itemId="{RichTextPropertyField.PARAGRAPH_HEADING3_ITEM_ID}"/>
          </ui:items>
        </ui:RemoveItemsPlugin>
      </plugins>
    </Menu>
  </ui:rules>
</ui:NestedRulesPlugin>

Example 7.28. Customizing the rich text editor toolbar


Please note that the RichTextActionToggleButton has a mandatory ckEditorValueExpression config. This config can only be omitted here, because the RichTextPropertyField's toolbar automatically adds it to all its items.

The baseAction, as in the above example, can also reference a custom action defined in a custom or CKEditor plugin. In this case, the commandName of the richtextAction is the name given in the plugin definition.

You can either apply the plugin to all rich text fields or only to a specific content type. When you add it to your *StudioPlugin.mxml file (the <bp:customizeRichTextPlugin/> line), then the plugin is applied to all rich text fields:

<editor:StudioPlugin>
  <editor:rules>
    …

    <editor:RichTextPropertyField>
      <editor:plugins mode="append">
        <bp:CustomizeRichTextPlugin/>
      </editor:plugins>
    </editor:RichTextPropertyField>
  </editor:rules>
</editor:StudioPlugin>

When the plugin should only be applied to a specific rich text field, you have to add it to a specific *DocumentForm.mxml file:

<editor:DocumentTabPanel>
  <editor:items>
  <editor:RichTextPropertyField propertyName="detailText">
    <editor:plugins mode="append">
      <bp:CustomizeRichTextPlugin/>
    </editor:plugins>
  </editor:RichTextPropertyField>
</editor:items>
</editor:DocumentTabPanel>

Here, it is important, that you use the mode="append" attribute. Otherwise, you would remove all plugins that are already defined for this field.

You may also add a custom icon to the toolbar or use one bundled with an existing CKEditor plugin. To do this, apply the addItemsPlugin as above to the richTextPropertyField. The iconButton can take the arguments iconCls, text and tooltip in order to apply and localize the custom icon. The iconCls property defines the CSS class of the icon. The icon image location and style may then be added to the css using the CSS class name defined by the iconCls.

<ui:IconButton iconCls="{MyPluginLabels_properties.INSTANCE.MyPlugin_icon}"
               tooltip="{MyPluginLabels_properties.INSTANCE.MyPlugin_tooltip}"
               text="{MyPluginLabels_properties.INSTANCE.MyPlugin_text}">

Example 7.29. Adding a custom icon to the rich text editor toolbar


As in the example above, these three properties may be defined in a separate properties bundle which can be localized.

You can customize the toolbar of the TeaserOverlayPropertyField. E.g. to add an InternalLinkButton, you can create a NestedRulesPlugin as follows.

<ui:NestedRulesPlugin ...>
  <fx:Script><![CDATA[
    ...
    private var teaserOverlayPropertyField:TeaserOverlayPropertyField;

    private function __initialize__(config:CustomizeTeaserOverlayFieldPlugin):void {
      teaserOverlayPropertyField = config.cmp as TeaserOverlayPropertyField;
    }
   ]]></fx:Script>

  <ui:rules>
    <ui:FloatingToolbar>
      <ui:plugins exml:mode="append">
        <ui:AddItemsPlugin>
          <ui:items>
            <editor:InternalLinkButton
                itemId="..."
                bindTo="{teaserOverlayPropertyField.bindTo}"
                forceReadOnlyValueExpression="{teaserOverlayPropertyField.forceReadOnlyValueExpression}">
              <editor:plugins>
                <editor:BindDisablePlugin
                  bindTo="{teaserOverlayPropertyField.bindTo}"
                  forceReadOnlyValueExpression="{teaserOverlayPropertyField.getRichTextButtonsDisabledVE()}"/>
              </editor:plugins>
            </editor:InternalLinkButton>
            ... for ExternalLinkButton and remove link button see below
          </ui:items>
        </ui:AddItemsPlugin>
      </ui:plugins>
    </ui:FloatingToolbar>
  </ui:rules>
</ui:NestedRulesPlugin>

Example 7.30. Adding InternalLinkButton to the toolbar in TeaserOverlayPropertyField


To add an ExternalLinkButton and a button to remove links insert the following code in the plugin. Remember: All of these buttons have a mandatory ckEditorValueExpression config, that will be set automatically by the floating toolbar.

<editor:ExternalLinkButton
    itemId="..."
    bindTo="{teaserOverlayPropertyField.bindTo}"
    forceReadOnlyValueExpression="{teaserOverlayPropertyField.forceReadOnlyValueExpression}"
    ckEditorValueExpression="{teaserOverlayPropertyField.getCKEditorValueExpression()}">
  <editor:plugins>
    <editor:BindDisablePlugin
      bindTo="{teaserOverlayPropertyField.bindTo}"
      forceReadOnlyValueExpression="{teaserOverlayPropertyField.getRichTextButtonsDisabledVE()}"/>
  </editor:plugins>
</editor:ExternalLinkButton>

<ui:RichTextActionToggleButton
    itemId="..."
    commandName="{RichTextAction.COMMAND_UNLINK}">
  <ui:plugins>
    <editor:BindDisablePlugin
       bindTo="{teaserOverlayPropertyField.bindTo}"
       forceReadOnlyValueExpression="{teaserOverlayPropertyField.getRichTextButtonsDisabledVE()}"/>
  </ui:plugins>
</ui:RichTextActionToggleButton>

Example 7.31. Adding two more buttons to the toolbar


Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

Please use Mozilla Firefox, Google Chrome, or Microsoft Edge.