Important changes to Tiny Cloud pricing > Find out more

NOTE: TinyMCE 5 reached End of Support in April 2023. No more bug fixes, security updates, or new features will be introduced to TinyMCE 5. We recommend you upgrade to TinyMCE 6 or consider TinyMCE 5 Long Term Support (LTS) if you need more time.

Context forms

Context forms overview

Contribute to this page

A context form consists of an input field, and a series of related buttons. Context forms can be shown wherever a context toolbar can be shown. Also, when a context form is registered containing a launch configuration, a special context toolbar button with name form:${name} is registered which will launch that particular context form. Context forms are a generalization of the Insert Link form that existed in the original inlite theme from TinyMCE 4.

Registering a context form

A context form is registered by calling the addContextForm API in the registry. The specification of a context form is separated into two parts:

Launch

The button strings for launching a context form is form:${name} where name is the registered name of the context form (e.g. form:link).

Note: These buttons will only be present if the launch setting of the context form is specified.

The Launch specification. This relates to what the button that launches this form will look like.

Name Details
launch This is the specification for the launching button that can appear in a context toolbar only. It will be either type: contextformbutton or contextformtogglebutton, and will be identical to those definitions below except it will not have an onAction.

Launching context forms from a context toolbar

If a registered context form has a launch setting, then it can be launched from a context toolbar. The name of item will be form:${name} (e.g. ‘form:link’). When the user presses this button, the toolbar will change into the specified context form. If you the user presses Esc in a context form that was launched through a context toolbar, they will be returned to the original context toolbar.

Launching a context form programmatically

There is an editor event called contexttoolbar-show that can be fired to show a context form at the current selection. The event takes a parameter toolbarKey which specifies the name of the registered context form or context toolbar to show.

Form

This relates to the form itself. The form specifications are:

Name Details
launch This is the specification for the launching button that can appear in a context toolbar only. It will be either type: contextformbutton or contextformtogglebutton, and will be identical to those definitions below except it will not have an onAction.
label This is the label that will appear in the form.
initValue This is the initial value the input will have in the form.
predicate This controls when the context toolbar will appear.
position This controls where the context toolbar will appear with regards to the current cursor.
scope This controls whether the predicate is a node-based predicate, or an editor-based predicate. See context toolbar proirity for more details.
commands This is a list of the items to show in the context form. They can be either contextformbutton or contextformtogglebutton.

Positioning of context forms

There are three options for positioning context forms: selection, node, or line.

  • A selection position will place the context form above or below the current selection, centered if possible.

  • A node position will place the context form above or below the bounds of a node (e.g. a table or image).

  • A line position will place the context form to the right (or left in Right-to-Left languages) of the current selection.

Context form buttons

Unlike normal context toolbar buttons, Context form buttons are not registered beforehand. Instead, you need to define each button completely in the commands section.

Context form button

The definition of a context form button is very similar to the definition of a normal toolbar button. The main difference is that the action is slightly different (as it will relate to the form), and the type is contextformbutton instead of button. The following is the full list of options:

type: ‘contextformbutton’;

Name Value Requirement Description
primary boolean Optional This will activate the button on <enter> in the input form.
onAction (formApi, togglebuttonApi) => void Required This decides what happens when the user clicks the button.
active boolean Optional default:false
disabled boolean Optional default: false - Represents button state. Is toggled by the button’s API
tooltip string Optional Text for button tooltip.
text string Optional Text to display if no icon is found.
icon string Optional Name of the icon to be displayed. Must correspond to an icon: in the icon pack, in a custom icon pack, or added using the addIcon API.
onSetup (togglebuttonApi) => (togglebuttonApi) => void Optional default: () => () => {} - Function that’s invoked when the button is rendered.

Where the buttonApi is the same as a regular toolbar button and FormApi has (getValue: () => string, hide: () => void)

Context form toggle button

The context form toggle button is very similar to the a normal toolbar toggle button. The main difference is that the action is slightly different (as it will relate to the form), and the type is contextformtogglebutton, instead of togglebutton. The following is the full list of options:

type: ‘contextformtogglebutton’;

Name Value Requirement Description
primary boolean Optional This will activate the button on <enter> in the input form.
onAction (formApi, togglebuttonApi) => void Required This decides what happens when the user clicks the button.
active boolean Optional default:false
disabled boolean Optional default: false - Represents button state. Is toggled by the button’s API
tooltip string Optional Text for button tooltip.
text string Optional Text to display if no icon is found.
icon string Optional Name of the icon to be displayed. Must correspond to an icon: in the icon pack, in a custom icon pack, or added using the addIcon API.
onSetup (togglebuttonApi) => (togglebuttonApi) => void Optional default: () => () => {} - Function that’s invoked when the button is rendered.

Where the toggleButtonApi is the same as a regular toolbar toggle button.

formApi

Both contextformbutton and contextformtogglebutton are passed formApi in their onAction callback. The formApi has two functions:

Functions Description
hide This will hide the form. By default, no button hides the form. It is the responsibility of the developer to hide the form in the onAction handler of buttons that require that the context form close after the action.
getValue This will retrieve the value current typed in the input field.

Example configuration

This example shows how the link plugin adds the standard link context form. The context form will show whenever any content is selected.


tinymce.init({
  selector: 'textarea#context-form',
  height: 300,
  setup: function (editor) {
    var isAnchorElement = function (node) {
      return node.nodeName.toLowerCase() === 'a' && node.href;
    };

    var getAnchorElement = function () {
      var node = editor.selection.getNode();
      return isAnchorElement(node) ? node : null;
    };

    editor.ui.registry.addContextForm('link-form', {
      launch: {
        type: 'contextformtogglebutton',
        icon: 'link'
      },
      label: 'Link',
      predicate: isAnchorElement,
      initValue: function () {
        var elm = getAnchorElement();
        return !!elm ? elm.href : '';
      },
      commands: [
        {
          type: 'contextformtogglebutton',
          icon: 'link',
          tooltip: 'Link',
          primary: true,
          onSetup: function (buttonApi) {
            buttonApi.setActive(!!getAnchorElement());
            var nodeChangeHandler = function () {
              buttonApi.setActive(!editor.readonly && !!getAnchorElement());
            };
            editor.on('nodechange', nodeChangeHandler);
            return function () {
              editor.off('nodechange', nodeChangeHandler);
            }
          },
          onAction: function (formApi) {
            var value = formApi.getValue();
            console.log('Save link clicked with value: ' + value);
            formApi.hide();
          }
        },
        {
          type: 'contextformtogglebutton',
          icon: 'unlink',
          tooltip: 'Remove link',
          active: false,
          onAction: function (formApi) {
            console.log('Remove link clicked');
            formApi.hide();
          }
        }
      ]
    });
  },
  content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:14px }'
});

Troubleshooting context toolbar and context form conflicts

There are situations where custom context toolbars or custom context forms may conflict with:

  • Context toolbars or context forms provided by the editor,
  • Context toolbars or context forms provided by the Quick Toolbars (quickbars) plugin,
  • Other custom context toolbars or custom context forms.

How these conflicts are resolved depends on the TinyMCE version.

Determining the display priority of context toolbars and context forms

There are three settings that determine the priority of context toolbars and context forms: scope, predicate, and position.

  • scope - Sets the context toolbar or form as either: specific to certain types of content (node), or a general (global) toolbar or form (editor).
  • predicate - A function for determining if the context menu or form applies to the current selection or cursor position. This function should return a boolean value.
  • position - Sets where the context toolbar or form is rendered, relative to the current context (selection, node, or line).

Generally:

  • Context forms are prioritized over context toolbars.
  • Context forms with scope: 'node' are prioritized over scope: 'editor'.
  • Only one context form can be shown for a selection or cursor position, they cannot be concatenated to another context form or a context toolbar.
  • Context toolbars with position: 'selection' are prioritized over position: 'node', and position: 'line' is given the lowest priority.
  • The editor concatenates context toolbars when there is more than one context toolbar to display with:

    • A matching predicate,
    • The same scope and position values.

    Concatenated toolbars may contain duplicate toolbar items.

  • If no matching context toolbars or context forms are found for the selection or cursor position, then editor will recursively search for matches on the parent node of the current node, until it reaches the root node of the editor content.

Description of how context toolbars and context forms are prioritized

The following description can be used for troubleshooting the behavior of context toolbars and context forms.

The editor will determine which context toolbars or context form will be shown using following process:

  1. Find all context forms with both:

    • scope: 'node'
    • A predicate matching the current selection or cursor position.

    If there are any matching context forms, the first one found will be displayed in the editor and the process will end.

  2. Find all context forms with both:

    • scope: 'editor'
    • A predicate matching the current selection or cursor position.

    If there are any matching context forms, the first one found will be displayed in the editor and the process will end.

  3. Find all context toolbars with both:

    • Any scope
    • A predicate matching the current selection or cursor position.

    If there are any matching context toolbars, the editor will prioritize the context toolbars based on the position value.

    • All context toolbars with position: 'selection' or position: 'node' will be concatenated, the concatenated toolbar will be displayed, and the process will end.
    • Otherwise, all context toolbars with position: line will be concatenated, the concatenated toolbar will be displayed, and the process will end.
  4. Find all context forms with both:

    • Any scope
    • A predicate matching the parent node of the current node, selection, or cursor position.

    If there are any context forms found, the first one found will be displayed in the editor and the process will end.

  5. Find all context toolbars with both:

    • Any scope
    • A predicate matching the parent node of the current node, selection, or cursor position.

    If there are any matching context toolbars, the editor will prioritize the context toolbars based on the position value.

    • If there are context toolbars with position: 'selection', they will be concatenated, the concatenated toolbar will be displayed, and the process will end.
    • If there are context toolbars with position: 'node', they will be concatenated, the concatenated toolbar will be displayed, and the process will end.
    • Otherwise, all context toolbars with position: line will be concatenated, the concatenated toolbar will be displayed, and the process will end.
  6. Repeat step 4 and 5 for each successive parent node in the DOM for context toolbars and context forms with scope: node until either:

    • A matching context form or context toolbars are found and displayed,
    • The root node of the editor is reached.

Determining the display priority of context toolbars and context forms (Legacy behavior)

There are two settings that determine determine the priority: predicate and scope. The priority system mirrors the old inlite theme from TinyMCE 4. The predicate is a function that takes in the current context position and returns a boolean. The scope is either node or editor. The whole priority process works as follows:

  1. The current cursor position is stored to use as the first current context position.
  2. For this current context position, each predicate with scope: node in the registered ContextForm is called. Currently, the order they are checked-in cannot be specified. The first predicate that passes will win and that ContextForm will be shown.
  3. If no predicates (scope: node) match the current context position, then all of the scope: editor predicates are tried. The first one that matches the editor context wins.
  4. If no scope: editor predicates match, then the new context position is calculated by going up the tree one level to the parent node. All scope: node predicates are then checked again. As soon as one matches, it wins and that ContextForm is shown. If nothing matches, it goes up the tree and tries again.

Note: Only scope: node predicates are checked at this stage. The scope: editor predicate is only checked once and that check only happens in (2).

Caution: Since the order in which the ContextForms and ContextToolbars are checked is not specified, try not to have their predicates overlap.

Can't find what you're looking for? Let us know.

Except as otherwise noted, the content of this page is licensed under the Creative Commons BY-NC-SA 3.0 License, and code samples are licensed under the Apache 2.0 License.