RealObjects Nimbudocs Editor 2.5.3885_Beta5

Guide: Customization


Introduction

If not specified otherwise, Nimbudocs Editor loads a default action map, ui config, as well as a locale file. The action map is a JSON object containing all available actions to Nimbudocs Editor, the ui config defines content and structure of the user interface, and the locale contains a mapping between locale constants and localized text in different languages.

Usually it is recommended to only extend the action map and the locale instead of replacing them. In these extensions, new entries will be added to the default action map or locale files. Entries in the extensions have higher priority than the entries in the default files, thus default entries can be overridden.

Configuration Objects

Action Map

The action map is a nested JSON object containing action IDs and several configuration options.

Properties:
Name Type Argument Default Description
type String <optional> "client" The type of the action. If set to "stateless" instead of "client", the action will not be created on the server and thus cannot receive automatic action state updates. These actions can also not be restricted by the allowedContextNames and prohibitedContextNames. The third type is "server" and only used by internal Nimbudocs Editor actions.
title String The locale constant is used to look up the locale string in the locale object. If none is found, the value of the title is used directly as a tooltip for the action.
iconText String <optional> The locale constant is used to look up the locale string in the locale object. If this is set, this text will be displayed as the toolbar text. Otherwise the title setting will be used.
iconURL String <optional> The path to the default icon that is used for this action. If a relative path is used, it is resolved relative to the integration base or the icon repository URL (if it is specified). If not specified otherwise, this icon will be scaled according to the size of the action UI element. If omitted, a default icon in the default server icon repository will be used.

If set to null and none of the other *IconUrl properties is set, no icon will be displayed/loaded for this action.

quickIconURL String <optional> The path to the icon that is used for this action if it is specified within the quick action panel. If a relative path is used, it is resolved relative to the integration base or the icon repository URL (if it is specified). If not specified otherwise, this icon will be scaled according to the size of the action UI element.
tinyIconURL String | Boolean <optional> The path to the icon that is used for this action if it is specified as a tiny button size. If a relative path is used, it is resolved relative to the integration base or the icon repository URL (if it is specified). If not specified otherwise, this icon will be scaled according to the size of the action UI element.
smallIconURL String | Boolean <optional> The path to the icon that is used for this action if it is specified as a small button size. If a relative path is used, it is resolved relative to the integration base or the icon repository URL (if it is specified). If not specified otherwise, this icon will be scaled according to the size of the action UI element.
mediumIconURL String | Boolean <optional> The path to the icon that is used for this action if it is specified as a medium button size. If a relative path is used, it is resolved relative to the integration base or the icon repository URL (if it is specified). If not specified otherwise, this icon will be scaled according to the size of the action UI element.
largeIconURL String | Boolean <optional> The path to the icon that is used for this action if it is specified as a large button size. If a relative path is used, it is resolved relative to the integration base or the icon repository URL (if it is specified). If not specified otherwise, this icon will be scaled according to the size of the action UI element.
shortcut String <optional> A keyboard shortcut for the action consisting of one or more modifier key and a letter or number. Possible modifier keys are:
  • ctrl: The CTRL key.
  • alt: The ALT key.
  • shift: The shift key.
  • cmd: The Mac CMD key.
  • msck: The CTRL key on Windows and the CMD key on Mac environments.
Example: "msck d"
macShortcut String <optional> An optional shortcut that overrides the shortcut setting on Mac environments.
allowedContextNames Array <optional> A list of context names in which the action is allowed. Contexts are defined in CSS. If an entry in the array is "none", the action may not be used at all. This setting is mutually exclusive with the prohibitedContextNames setting.
prohibitedContextNames Array <optional> A list of context names in which the action is disallowed. Contexts are defined in CSS. This setting is mutually exclusive with the allowedContextNames setting.
require String <optional> "CARET_OR_SELECTION" Defines in which caret related context a "client" action is enabled.
  • SELECTION_ONLY: The action is only enabled when there is a selection.
  • CARET_ONLY: The action is only enabled when there is no selection and a valid caret position.
  • CARET_OR_SELECTION: The action is enabled when there is either a valid caret position or a selection.

Action Map Extension

The default action map may also be extended, which means that you do not have to write a completely new action map from scratch. This is also useful if you want to add contexts to existing actions

Action Map Extension

var actionMapExt = {
    "insert-image-dialog": {
        "title": "L_INSERT_IMAGE_DIALOG",
        "iconText": "L_INSERT_IMAGE_DIALOG_TEXT",
        "allowedContextNames": [
            "imagefield-context"
        ]
    },
    "bold": {
        "type": "server",
        "title": "L_BOLD",
        "shortcut": "msck B",
        "iconText": "L_BOLD_TEXT",
        "allowedContextNames": [
            "none"
        ]
    },
    "my-custom-action": {
        "type": "stateless",
        "title": "L_MY_CUSTOM_ACTION",
        "iconURL": "icons/custom-action-icon.png"
    }
};

In the example above, the "insert-image-dialog" action is only allowed in the context "imagefield-context", the "bold" action is disabled and the custom action "my-custom-action" is added.

Locale Extension

Locale Extension

The following example shows how to write a locale extension. The locale extension is a nested JSON object containing language codes as keys and a mapping of locale constants and localized strings as value.

The language code "" (empty string) means that the mappings will be applied to all languages, if not otherwise specified.

var localeExt = {
    "": {
        "L_CUSTOM_TAB": "Custom Tab",
        "L_PROPERTIES_PANE": "Properties"
    },
    "de-DE": {
        "L_PROPERTIES_PANE": "Eigenschaften"
    },
    "fr-FR": {
        "L_PROPERTIES_PANE": "Propriétés"
    }
};

User Interface

The structure of the user interface is defined in the uiconfig. This JSON file configures which actions should be represented with buttons and in which tab and panel they should appear. Furthermore, the uiconfig also defines the possible content of the context menu.

Please Note: If no uiconfig is specified or if it could not be parsed, a default configuration is used instead.

Defining the toolbar

To define the structure of the toolbar, the uiconfig contains different objects in different levels, each representing certain elements in the toolbar:

The structure and options in the uiconfig.json is described in the following list. Keywords are marked as bold and surrounded with quotation marks. Placeholders for specific names are italic. The data type of the value is specified behind the colon.

uiconfig sample

{
    "toolbar": {
        "quickactions": [
            "undo",
            "redo"
        ],
        "ribbons": {
            "options": {
                "sortabletabs": "false"
            },
            "elements": {
                "L_EDIT_TAB": {
                    "shortcut": "msck e",
                    "L_DOCUMENT_PANE": {
                        "subpanels": [
                            {
                                "size": "mediumPanel",
                                "actions": [
                                    "new-document",
                                    "load-url-dialog"
                                ]
                            }
                        ]
                    },
                    "L_FONT_PANE": {
                        "subpanels": [
                            {
                                "size": "dropdownPanel",
                                "comboactions": {
                                    "font-size": {
                                        "options": {
                                            "comboWidth": "150",
                                            "dropdownWidth": "150"
                                        },
                                        "dropdownactions": {
                                            "font-size-default": "",
                                            "font-size-8": "",
                                            "font-size-12": "",
                                            "font-size-18": "",
                                            "font-size-24": ""
                                        }
                                    }
                                }
                            }
                        ]
                    }
                }
            }
        }
    }
}

In the example above, the toolbar has one tab, with two panes. Their names are locale codes that will translated into the editor's language. The second pane has a simple dropdown menu with a specified width of 150 pixels.

Defining the context menu

All entries that may appear in the context menu are defined in the uiconfig using the key "contextmenu" with an array as the value.

This array represents the main level of the context menu and can be filled with more array, action-names and submenu objects.

Name Type Allowed Children / Properties Description
Root Menu Array Groups The main level of the context menu. This scheme is also used for the submenu items array.
Group Array Actions, Submenus A horizontal line separates the groups from each other.
Action String N/A This is the id of the action this menu item is based on. Label and icon are also retrieved from this action.
Submenu Object
  • "name": The display name of this item, i.e. title of the submenu.
  • "menuid": The unique id of the submenu. Only used internally.
  • "items": The submenu items. Contains at least one group.
The submenu item opens another menu level when hovering over it.

Context Menu

{
    "toolbar": {
        // ...
    },
    "contextmenu": [
        [
            {
                "name": "L_ALIGN",
                "menuid": "alignmenu",
                "items": [
                    "align-left",
                    "align-center",
                    "align-right",
                    "align-justify"
                ]
            },
            {
                "name": "L_CONTEXT_STYLE",
                "menuid": "stylemenu",
                "items": [
                    [
                        "bold",
                        "italic",
                        "underline",
                        "strikethrough"
                    ],
                    [
                        "script-super",
                        "script-sub"
                    ]
                ]
            }
        ],
        [
            "image-properties-dialog"
        ]
    ]
}

The sample above is the uiconfig for a contextmenu with two levels. The first group has two submenu items (text-align and style menus), each of them has several actions. The second group has only one action (image-properties-dialog).

Please Note: Nimbudocs Editor disables actions that can not be used at the current caret position or context as it is called. Their context is defined in the action map.

As long as at least one item in a group is active, the inactive one are just disabled. If all items in a group are disabled, no item is shown and the whole group is left out of the context menu.

Spellchecking actions

In general, the context menu should offer actions for words that have been recognized as misspelled. The following actions will only appear if the spellchecker has been enabled and the current word is misspelled:

Action Description
spellcheck-add-word Adds this word to the personal dictionary.
spellcheck-ignore-all Ignores this word and all further occurrences of it.
spellcheck-suggestions This is a special action replaces the current word with a suggestion made by the spellchecker. Depending on how many suggestions for the misspelled word are available, there are generated several entries in this action's group.

Note: It is possible to limit the number of the suggestions that are shown in the context menu. To do so, just add -n to spellcheck-suggestions, where n is the desired limit. For example spellcheck-suggestions-3 would show the best three suggestions.

Spellchecker Dictionaries

Spell checker dictionaries contain a list of words that are recognized as spelled correctly for a certain language. The following types of dictionaries are supported:

Personal Dictionary

Nimbudocs provides a personal dictionary that allows individual users to customize spell checking. It is automatically available without further integration code.

Please note: The personal dictionary is stored inside HTML 5 local storage. All limitations regarding local storage apply.

Application Dictionary

It is possible to provide Nimbudocs with an application dictionary. The following example adds "Realobjects" and "Nimbudocs" to the american english dictionary:

var applicationDictionary = {
    "en-US" : ["RealObjects", "Nimbudocs"]
};
editor.setDictionary(applicationDictionary, "application");

Setting an application dictionary should be done early the onready event handler. This way the dictionary is available from the start.