Example: Configuring the Insert Section Action for a Framework

This topic describes the procedure for defining the Insert Section action for a custom framework. It is assumed that the icon files, (Section16.gif) for the menu item and (Section20.gif) for the toolbar, are already available. Although you could use the same icon size for both the menu and toolbar, usually the icons from the toolbars are larger than the ones found in the menus. These files should be placed in your custom framework directory ([OXYGEN_INSTALL_DIR]\frameworks\[CUSTOM_FRAMEWORK_DIR]).

Figure 1. Action Dialog Box

Set the ID field to insert_section. This is a unique action identifier.
Set the Name field to Insert Section. This will be the action's name, displayed as a tooltip when the action is placed in the toolbar, or as the menu item name.
Set the Menu access key to i. On Windows, the menu items can be accessed using Alt+letter keys combination, when the menu is visible. The letter is visually represented by underlining the first letter from the menu item name having the same value.
Add a Description.
Set the Large icon (20x20) field to ${framework}/Section20.gif. A good practice is to store the image files inside the framework directory and use editor variable ${framework} to make the image relative to the framework location.
If the images are bundled in a JAR archive together with some Java operations implementation, for instance, it might be convenient for you to reference the images not by the file name, but by their relative path location in the class-path.
If the image file Section20.gif is located in the images directory inside the JAR archive, you can reference it by using /images/Section20.gif. The JAR file must be added into the Classpath list.
Set the Small icon (16x16) field to ${framework}/Section16.gif.
Click the text field next to Shortcut key and set it to Ctrl+Shift+S (Meta+Shift+S on macOS). This will be the key combination to trigger the action using the keyboard only.
The shortcut is enabled only by adding the action to the main menu of Author mode, which contains all the actions that the author will have in a menu for the current document type.
At this time the action has no functionality added to it. Next you must define how this action operates. An action can have multiple operation modes. The first action mode enabled by the evaluation of its associated XPath expression will be executed when the action is triggered by the user. The XPath expression needs to be version 2.0 and its scope must be only element and attribute nodes of the edited document. Otherwise, the expression will not return a match and will not trigger the action. If the expression is left empty, the action will be enabled anywhere in the scope of the root element. For this example, suppose you want the action to add a section only if the current element is either a <book>, <article>, or another <section>.
1. Set the XPath expression field to:
```
local-name()='section' or local-name()='book' or 
 local-name()='article'
```
2. Set the invoke operation field to InsertFragmentOperation built-in operation, designed to insert an XML fragment at the cursor position. This belongs to a set of built-in operations, a complete list of which can be found in the Author Default Operations section. This set can be expanded with your own Java operation implementations.
3. Configure the arguments section as follows:
```
<section xmlns=
"http://www.oxygenxml.com/sample/documentation">
     <title/>
</section>
```
  insertLocation - leave it empty. This means the location will be at the cursor position.
  
  insertPosition - select "Inside".