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

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

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:

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.
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.
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.
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.
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="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.


1. Reference		Chapter 4. Macro commands