36. executeMenuItem

Parameter syntax:

[ '[' menu_item_index ']' ]? 
  command_name 
  | '"' command_name '"' [ command_parameter ]*
  | ''' command_name ''' [ command_parameter ]*

Executes command called command_name with optional parameter command_parameter. This command, typically found in the "current_configuration_name contextualMenuItems" namespace, is expected to return a menu.

The default value of menu_item_index is 0, the index of the first menu item. Menu item #menu_item_index specifies a command which is then executed. executeMenuItem returns the result of this command, if any.

Example 6.8. Implementing a “click to follow link” facility using executeMenuItem

The executeMenuItem command may be used to implement a “click to follow link” facility which works whatever the kind of link.

DocBook 5+ example: the implementation leverages the menu items added to the contextual menu when a link of any kind is implicitly or explicitly selected.

<command name="{$c contextualMenuItems}linkMenuItems">
  <macro>
    <choice>
      <!-- link, xref -->
      <sequence>
        <match context="$implicitElement"
               pattern="*[@linkend]|*[@linkend]//*" />
        <command name="{db5}linkMenuItems1" parameter="linkend" />
      </sequence>
      ...
      <!-- olink -->
      <sequence>
        <match context="$implicitElement" pattern="db:olink|db:olink//*" />
        <command name="{db5}linkMenuItems3" parameter="targetdoc" />
      </sequence>
    </choice>
  </macro>
</command>

<command name="{db5}linkMenuItems1">
  <menu>
    <item label="Follow Link"
          command="{db5}followLink" parameter="%0" />
    <item label="Set Link Target..."
          command="{db5}setLinkEnd" parameter="%0 %0" />
  </menu>
</command>
... 
<command name="{db5}linkMenuItems3">
  <menu>
    <item label="Follow Link" 
          command="{db5}followLink" parameter="%0" />
    <item label="Set Link Target..." command="db5.setOlinkTarget" />
  </menu>
</command>

The “click to follow link” facility may then be implemented as follows:

<command name="db5.followLinkAt">
  <macro>
    <sequence>
      <command name="selectAt" parameter="begin" />
      <command name="selectAt" parameter="end" />

      <command name="executeMenuItem"
               parameter="{$c contextualMenuItems}linkMenuItems" />
    </sequence>
  </macro>
</command>

<binding>
  <mouseClicked button="1" modifiers="mod alt" />
  <command name="db5.followLinkAt" />
</binding>

When the user clicks an internal link, the command which actually gets the job done is then "{db5}followLink" with parameter "linkend". When the user clicks an olink, the command which actually gets the job done is then "{db5}followLink" with parameter "targetdoc".