2. Redefining or extending the right-click, contextual, popup menu
Prev | Chapter 3. Menu commands | Next

## 2. Redefining or extending the right-click, contextual, popup menu

The right-click, contextual, popup menu is displayed by a command called `contextualMenu`. In order to determine the content of this popup menu, the `contextualMenu` command proceeds as follows:

1. `contextualMenu` attempts to execute in order (see below) all the commands found in the "``current_configuration_name` contextualMenu`" namespace. If, given the current context, one of such commands can be executed, then this command is expected to display a custom menu replacing the “standard” right-click, contextual, popup menu. Therefore, once this command is executed, `contextualMenu` ends its work at this point.

2. `contextualMenu` attempts to execute in order all the commands found in the "`contextualMenu`" namespace. If, given the current context, one of such commands can be executed, then this command is expected to display a custom menu replacing the “standard” right-click, contextual, popup menu. Therefore, once this command is executed, `contextualMenu` ends its work at this point.

3. `contextualMenu` attempts to execute in order all the commands found in the "``current_configuration_name` contextualMenuItems`" namespace. If, given the current context, one of such commands can be executed, then this command is expected to display a custom menu contributing some menu items to the “standard” right-click, contextual, popup menu. Therefore, once this command is executed, `contextualMenu` captures the menu items (without displaying any popup menu at this stage) and proceeds with the next command found in in the "``current_configuration_name` contextualMenuItems`" namespace.

4. `contextualMenu` attempts to execute in order all the commands found in the "`contextualMenuItems`" namespace. If, given the current context, one of such commands can be executed, then this command is expected to display a custom menu contributing some menu items to the “standard” right-click, contextual, popup menu. Therefore, once this command is executed, `contextualMenu` captures the menu items (without displaying any popup menu at this stage) and proceeds with the next command found in in the "`contextualMenuItems`" namespace.

5. `contextualMenu` displays the “standard” right-click, contextual, popup menu. This menu contains all the items collected during step #3 and step #4.

The invocation order of the commands belonging to a given namespace is the lexical order of the local names of the commands. For example, command `{My Config contextualMenuItems}barMenuItems` is invoked before command `{My Config contextualMenuItems}fooMenuItems`.

By default, XXE attempts to execute the equivalent of the following command during step #2:

    <command name="{contextualMenu}AutoSpellMenu">
      <sequence>
        <command name="autoSpellChecker"
                 parameter="popupMenu"/>
      </sequence>
    </command>

More information about command `autoSpellChecker`.

By default, XXE attempts to execute the equivalent of the following command during step #4:

    <command name="{contextualMenuItems}xxeEditMenuItems">
      <menu>
        <item label="Repeat"
              command="repeat"/>
        <separator/>
        <item label="Cut"
              command="cut" parameter="[implicitElement]"/>
        <item label="Copy"
              command="copy" parameter="[implicitElement]"/>
        <item label="Paste Before"
              command="paste" parameter="before[implicitElement]"/>
        <item label="Paste"
              command="paste" parameter="toOrInto"/>
        <item label="Paste After"
              command="paste" parameter="after[implicitElement]"/>
        <item label="Delete"
              command="delete" parameter="[implicitElement]"/>
        <separator/>
        <item label="Replace..."
              command="replace" parameter="[implicitElement]"/>
        <item label="Insert Before..."
              command="insert" parameter="before[implicitElement]"/>
        <item label="Insert Into..."
              command="insert" parameter="into"/>
        <item label="Insert After..."
              command="insert" parameter="after[implicitElement]"/>
        <item label="Convert..."
              command="convert" parameter="[implicitElement]"/>
        <item label="Convert [wrap]..."
              command="wrap" parameter="[implicitElement]"/>
      </menu>
    </command>

Example 3.1. Whatever the configuration, add extra menu items to the right-click, contextual, popup menu

    <command name="{contextualMenuItems}xxeExtraMenuItems">
      <menu>
        <item label="Split" command="split" />
        <item label="Join" command="join" />
      </menu>
    </command>

More information about commands `split` and `join`.

If you want to the give the above snippet a try, add it to your `customize.xxe` file.

Example 3.2. DITA topic configuration: when an image is selected, allow to edit it using a helper application

    <command name="{$c contextualMenuItems}editImageMenuItem">
      <macro>
        <sequence>
          <match context="$selectedElement"
                 pattern="image[@href and @href != '???']" />
          <command name="{dita}editImageMenuItem" />
        </sequence>
      </macro>
    </command>

    <command name="{dita}editImageMenuItem">
      <menu>
        <item label="Edit image"
              command="editObject"
              parameter="href anyURI" />
      </menu>
    </command>

| "`$c`" is a shorthand for the name of the current configuration ("`DITA`" in the case of the above command).
| The "Edit image" item is added to the popup menu only if an `image` element having an `href` attribute is explicitly selected.
| A macro-command such as "`{DITA contextualMenuItems}editImageMenuItem`" may not have a `menu` child element element, hence the need to define helper command `{dita}editImageMenuItem`.
| More information about command `editObject`.

If you want to the give the above snippet a try, add it to ``XXE_install_dir`/addon/config/dita/topic.xxe`.

Example 3.3. Any of the two XHTML 1.0 configurations: when some text is selected, display a special, simpler, popup menu

    <command name="{$c contextualMenu}textMenu">
      <macro>
        <sequence>
          <test expression="$selectedChars" />
          <command name="{xhtml}textMenu" />
        </sequence>
      </macro>
    </command>

    <command name="{xhtml}textMenu">
      <menu>
        <item label="Cut" command="cut" />
        <item label="Copy" command="copy" />
        <item label="Paste"
              command="paste" parameter="to"/>
        <separator/>
        <item label="Convert to b"
              command="convert"
              parameter="{http://www.w3.org/1999/xhtml}b"/>
        <item label="Convert to i"
              command="convert"
              parameter="{http://www.w3.org/1999/xhtml}i"/>
        <item label="Convert to tt"
              command="convert"
              parameter="{http://www.w3.org/1999/xhtml}tt"/>
      </menu>
    </command>

| "`$c`" is a shorthand for the name of the current configuration ("`XHTML Transitional`" or "`XHTML Strict`").
| The “standard” right-click, contextual, popup menu is replaced by `textMenu` only if some text is selected.
| A macro-command such as "`{XHTML Transitional textMenu}`" may not have a `menu` child element element, hence the need to define helper command `{xhtml}textMenu`.
| More information about commands `cut`, `copy`, `paste`, `convert`.

If you want to the give the above snippet a try, add it to ``XXE_install_dir`/addon/config/xhtml/xhtml_common.incl`.

Prev | Up | Next
1. Reference | Home | Chapter 4. Macro commands