Creating and Customizing Author Mode Actions for a Framework
- 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
- Open the Preferences dialog box , 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
- 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 , 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
- 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.