Creating and Customizing Author Mode Actions for a Framework

There are several possibilities for creating new Author mode actions:

You can create new actions for a framework or edit existing ones using the Actions subtab of the Document Type configuration dialog box. In this case, the actions are stored internally in the *.framework file.
You can export existing actions from the Document Type configuration dialog box into individual XML files or use a built-in template to create a new XML file that defines a single action. In this case, the actions are stored externally as separate XML files. The benefits of using this approach are explained in the Creating or Editing Actions Using an Individual XML File for Each Action section below.

Creating or Editing Actions Using the Document Type Configuration Dialog Box

To add or configure Author mode actions for a framework (document type) using the Document Type configuration dialog box, follow this procedure:

Open the Preferences dialog box (Options > Preferences), go to Document Types Association, and select the framework.
Select your framework and click the Edit button (or you can use the Duplicate or Extend button to create an extension of the framework).
In the resulting Document Type configuration dialog box, go to the Author tab, then the Actions subtab.
To create a new action, click the New button. To edit an existing action, select the action and click the Edit button.
Step Result: In either case, this opens the Action configuration dialog box where you can configure numerous aspects of the action.
Once you are finished, click OK several times to exit the configuration dialog box.

Result: Your changes are stored in the *.framework file for your particular framework.

Creating or Editing Actions Using an Individual XML File for Each Action

It is possible to work with Author mode actions outside the Document Type configuration dialog box and store them externally from the *.framework file. You can either export existing actions or use a template to create a new action from scratch. The benefits of using this approach are:

You can share, copy, or reuse each individual action across multiple projects or frameworks.
It is easier to develop and test action configurations. After configuring the XML file that defines an action, you can test its functionality by opening a document from your particular framework and invoking the action to see if it works as expected. If you did not get the desired result, you can simply repeat the process until you are happy with the result without having to navigate through the framework configuration dialog box.

Exporting Actions

To export existing Author mode actions into individual XML files, follow this procedure:

Open the Preferences dialog box (Options > Preferences), go to Document Types Association, and select the framework.
Select your framework and click the Edit button (or you can use the Duplicate or Extend button to create an extension of the framework).
In the resulting Document Type configuration dialog box, go to the Author tab, then the Actions subtab.
[Important] Make sure the Storage option in the top part of the dialog box is set to External and the external location must be a subdirectory of your current framework directory (see the Notes About the Storage Path section).
Select the action (or multiple actions) you want to export, right-click, and use the Export action (this action is also located at the bottom of the table of actions).
Step Result: If you choose to export a single action, a resulting dialog box will allow you to select the destination path for the new XML file that contains the configuration details of the action. If you export multiple actions, they will automatically be saved as individual XML files inside a newly created folder (it will have _externalAuthorActions at the end of the folder name) inside your current framework directory.
[Important] Click OK several times to confirm your changes and exit the Preferences dialog box. The files will not be created until you exit this dialog box.
Step Result: Each exported action is extracted from the framework configuration file and exported as an individual XML file.
To configure and test a particular action, you can open its corresponding XML file in Oxygen XML Editor, make changes, save the file, then open a document from your framework, test the action and repeat until you get the desired result.
Note: You can add or edit the action files outside of Oxygen XML Editor, but you will need to restart the application each time to reload the changes.

Creating New Actions

To create a new Author mode action outside the framework configuration dialog box, follow these steps:

Open the New document wizard, search for a template called Author Action, and choose a storage path and file name. Remember that ultimately, it must be saved in a subdirectory of your particular framework directory (see the Notes About the Storage Path section). Complete the creation process.
Step Result: The resulting XML file contains some hints and it is an example of an action configuration that will insert a new paragraph.

Configure the action as needed and save your changes.

Note: You can use XInclude to reuse different fragments (such as XPath expressions or configured operations between actions).

Example: Reusing and XPath Expression

<a:operations>
    <a:operation id="InsertFragmentOperation">
      <a:xpathCondition>
        <xi:include href="expression.txt" 
            xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/>
        </a:xpathCondition>
      <a:arguments>
        <a:argument name="insertLocation">
            <xi:include href="expression.txt" 
                xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/>
            </a:argument>
      </a:arguments>
    </a:operation>
  </a:operations>

Where the content of the expression.txt file is self::para.

Example: Reusing an Entire Operation

  <a:operations xmlns:a="http://www.oxygenxml.com/ns/author/external-action">
      <xi:include href="operation.xml"
          xpointer="element(/1/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
  </a:operations>

Where the content of operation.xml is:

<a:operations xmlns:a="http://www.oxygenxml.com/ns/author/external-action">
    <a:operation id="ToggleSurroundWithElementOperation">
        <a:xpathCondition>ancestor-or-self::p</a:xpathCondition>
        <a:arguments>
            <a:argument name="element"><i/></a:argument>
        </a:arguments>
    </a:operation>
</a:operations>

Step Result: At this point, the action has been created but it needs to be added to the UI (in a toolbar or menu).

Add the new action to a UI component. For example, to add it in a toolbar, open the Document Type configuration dialog box, go to the Author tab, then the Toolbar subtab, and add the action.
To test the action, you can open a document from your framework and test the action. If you don't get the desired result, open the action file, make changes, then test them again. Repeat until you get the desired result.
Note: You can add or edit the action files outside of Oxygen XML Editor, but you will need to restart the application each time to reload the changes.

Notes About the Storage Path

As mentioned above, it is imperative that the action configuration files be stored in a specific subdirectory of your particular framework directory.

There are two possible naming conventions for this subdirectory:

{framework_directory}/externalAuthorActions - If there are multiple framework subdirectories inside {framework_directory}, using this path structure will make the actions available to all of them.
{framework_directory}/{framework_file_name}_externalAuthorActions - Using this path structure will make the actions only available in the framework stored inside the {framework_file_name}.framework file.
Note: When exporting actions from the UI, this is the directory structure that is used.

Action Configuration Tips

If an action is configured to insert a fragment that contains entities, you need to wrap it in CDATA markup.
For a list of default operation, see Built-in Author Mode Operations.

Resources

For more information about customizing Author mode actions, see the following resources: