You can add a new Document Type Association or edit the properties of an existing one from the +Preferences+Document Type Association option pane. All the changes can be made into the Document type edit dialog.
The oXygen Author toolbars and menus can be changed to provide a productive editing experience for the content authors. You can create a set of actions that are specific to a document type.
In our example, the sdf framework, we created the
stylesheet and the validation schema. Now let's add some actions for
inserting a section and a table. To add a new
action, follow the procedure:
Open the Options Dialog, and select the Document Types Association option pane.
In the lower part of the Document Type Association dialog, click on the Author tab, then select the Actions label.
To add a new action click on the
Add button.
This paragraph describes how you can define the action for adding a
section. We assume the icon files 
Section16.gif for the menu item and 
Section20.gif for the toolbar, are already
available. Although we could use the same icon size for both menu and
toolbar, usually the icons from the toolbars are larger than the ones
placed in the menus. These files should be placed in the frameworks/sdf directory.
- ID
An unique identifier for the action. You can use insert_section.
- Name
The name of the action. It is displayed as a tooltip when the action is placed in the toolbar, or as the menu item name. Use Insert section.
- Menu access key
On Windows, the menu items can be accessed using (ALT + letter) 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. Since the name is Insert section, we can use as a menu access key the letter s.
- Description
You can add a short description for the action. In our case Adds a section element will suffice.
- Large icon (20x20)
The path to the file that contains the toolbar image for the action. A good practice is to store the image files inside the framework directory. This way we can use the editor variable
${frameworks}to make the image file relative to the framework location. Insert ${frameworks}/sdf/Section20.gif![[Note]](img/note.gif)
Note If the images are bundled in a jar archive together with some Java operations implementation for instance, it might be convenient for you to refer the images not by the file name, but by their relative path location in the class-path.
If the image file
Section20.gifis located in the directoryimagesinside the jar archive, you can refer to it by using /images/Section20.gif. The jar file must be added into the Classpath list.- Small icon (16x16)
The path to the file that contains the menu image. Insert ${frameworks}/sdf/Section16.gif
- Shortcut key
A shortcut key combination for triggering the action. To define it, click in the text field and press the desired key combination. We can choose Ctrl+Shift+s.
Note The shortcut is enabled only by adding the action to the main menu of the 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 we must define how this action operates. An action can have multiple operation modes, each of them activated by the evaluation of an XPath version 2.0 expression.
| Note |
|---|---|
The XPath expression of an operation mode is evaluated relative to the current element. The current element is the one where the caret is positioned. In fact there is hierarchy of elements containing the caret position, but we are considering only the closest one. A simple expression like: title is a relative one and checks if the current element has a "title" child element. To check that the current element is a "section" we can use the expression: local-name()='section' |
| Note |
|---|---|
oXygen Author determines the operation to be executed by iterating through the defined operation modes. The first operation whose XPath expression "matched" the current document context gets executed, while the others are being ignored. Make sure you order correctly your operations by placing the ones with more specific XPath selectors before the ones having more generic selectors. For instance the expression
person[@name='Cris' and @age='24']
is more specific than
person[@name='Cris']
The action mode using the first expression must be placed before the one using the second expression in the action modes list. |
We decide that we can add sections only if the current element is
either a book, article, or another
section.
- XPath expression
Set the value to:
local-name()='section' or local-name()='book' or local-name()='article'
- Invoke operation
A set of built-in operations is available. A complete list is found in the Author Default Operations section. To this set you can add your own Java operation implementations. In our case, we'll use the InsertFragmentOperation built-in operation, that inserts an XML fragment at the caret position.
Configure the arguments by setting the following values:
- fragment
<section xmlns= "http://www.oxygenxml.com/sample/documentation"> <title/> </section>- insertLocation
Leave it empty. This means the location will be the element at the caret position.
- insertPosition
Select "Inside".
We will create an action that inserts into the document a table with three rows and three columns. The first row is the table header. Similarly to the insert section action, we will use the InsertFragmentOperation.
We assume the icon files 
Table16.gif for the menu item and 
Table20.gif for the toolbar, are already available.
We place these files in the frameworks/sdf
directory.
The action properties:
- ID
You can use insert_table.
- Name
Insert Insert table.
- Menu access key
Enter the t letter.
- Description
We can use Adds a section element.
- Toolbar icon
Use ${frameworks}/sdf/Table20.gif
- Menu icon
Insert ${frameworks}/sdf/Table16.gif
- Shortcut key
We can choose Ctrl+Shift+t.
Now let's set up the operation the action uses.
- XPath expression
Set it to the value
true()
Note true() is equivalent with leaving this field empty.
- Invoke operation
We'll use InsertFragmentOperation built-in operations that inserts an XML fragment at the caret position.
Configure its arguments by setting the values:
- fragment
<table xmlns= "http://www.oxygenxml.com/sample/documentation"> <header><td/><td/><td/></header> <tr><td/><td/><td/></tr> <tr><td/><td/><td/></tr> </table>
- insertLocation
In our example will always add tables at the end of the section that contains the caret position. Use:
ancestor::section/*[last()]
- insertPosition
Select "After".
Now that we have defined the two actions we can add them to the toolbar.
The first thing to check is that the toolbar Author custom actions should be displayed when switching to the Author mode: Right click in the application window upper part, in the area that contains the toolbar buttons and check Author custom actions in the displayed menu if it is unchecked.
Open the Document Type edit dialog for the SDF framework and select on the Author tab. Next click on the Toolbar label.
The panel is divided in two sections: the left side contains a list of actions, while the right one contains an action tree, displaying the list of actions added in the toolbar. The special entry called Separator allows you to visually separate the actions in the toolbar.
Select the Insert section action in the left and
the Toolbar label in the right, then press the
Add as
child button.
Now select the Insert table action in the left
and the Insert section in the right. Press the
Add
as sibling button.
When opening a Simple Documentation Framework test document in Author mode, the toolbar below will be displayed at the top of the editor.
Defined actions can be grouped into customized menus in the oXygen menu bar. For this open the Document Type dialog for the SDF framework and click on the Author tab. Next click on the Menu label.
In the left side we have the list of actions and some special entries:
- Submenu
Creates a submenu. You can nest an unlimited number of menus.
- Separator
Creates a separator into a menu. In this way you can logically separate the menu entries.
In the right side we have the menu tree, having the Menu entry as root. To change its name click on this
label to select it, then press the 
Edit button. Enter
SD Framework as name, and D as menu access key.
Select the Submenu label in the left an the
SD Framework label in the right, then press the
Add as
child button. Change the submenu name to Table, using the Edit
button.
Select the Insert section action in the left and
the Table label in the right, then press the
Add
as sibling button.
Now select the Insert table action in the left
and the Table in the right. Press the Add as
child button.
When opening a Simple Documentation Framework test document in Author mode, the menu we created is displayed in the editor menu bar, between the Debugger and the Document menus. In the menu we find the submenu and the two actions:
| Note |
|---|---|
The shortcut of an action defined for the current document type is enabled only if the action is added to the main menu. Otherwise the author can run the action only from the toolbar. |
The contextual menu is shown when you right click (on Mac OS X it is used the combination ctrl and mouse click) in the Author editing area. In fact we are configuring the bottom part of the menu, since the top part is reserved for a list of generic actions like Copy, Paste, Undo, etc..
Open the Document Type dialog for the SDF framework and click on the Author tab. Next click on the Contextual Menu label.
Follow the same steps as explained above in the Configuring the Main Menu, except changing the menu name - the contextual menu has no name.
To test it, open the test file, and click to open the contextual menu. In the lower part there is shown the sub-menu and the action:
Below are listed all the operations and their arguments.
- InsertFragmentOperation
Inserts an XML fragment at the current cursor position. The selection - if there is one, remains unchanged. The fragment will be inserted in the current context of the cursor position. That means that if the current XML document uses some namespace declarations then the inserted fragment must use the same declarations. The inserted fragment will not be copied and pasted to the cursor position, but the namespace declarations of the fragment will be adapted if needed to the existing namespace declarations of the XML document. Examples of namespace adjusting when the fragment is inserted and the descriptions of the arguments are described here.
- InsertOrReplaceFragmentOperation
Similar to InsertFragmentOperation, except it removes the selected content before inserting the fragment.
- InsertOrReplaceTextOperation
Inserts a text. It removes the selected content before inserting the text section.
- text
The text section to insert.
- SurroundWithFragmentOperation
Surrounds the selected content by a fragment. Since the fragment can have multiple nodes, the surrounded content will be always placed in the first leaf element. If there is no selection, the operation will simply insert the fragment at the caret position. The arguments are described here.
- SurroundWithTextOperation
The surround with text operation takes two arguments, two text values that will be inserted before and after the selected content. If there is no selected content, the two sections will be inserted at the caret position. The arguments of the operation are:
- header
The text that will be placed before the selection.
- footer
The test that will be placed after the selection.
- fragment
The value for this argument is a text. This is parsed by the oXygen Author as it was already in the document at the caret position. You can use entities references declared in the document and it is namespace aware. The fragment may have multiple roots.
Note You can use even namespace prefixes that are not declared in the inserted fragment, if they are declared in the document where the insertion is done. For clarity, we recommend always to prefix and declare namespaces in the inserted fragment!
Note If there are namespace declarations in the fragment that are identical to the in the document insertion context, the namespace declaration attributes are removed from the fragment elements.
Example 7.2. Prefixes that are not bound explicitly
For instance, the fragment:
<x:item id="dty2"/> &ent; <x:item id="dty3"/>
Can be correctly inserted in the document: ('|' marks the insertion point):
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE x:root [ <!ENTITY ent "entity"> ]> <x:root xmlns:x="nsp"> | </x:root>Result:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE x:root [ <!ENTITY ent "entity"> ]> <x:root xmlns:x="nsp"> <x:item id="dty2"/> &ent; <x:item id="dty3"/> </x:root>Example 7.3. Default namespaces
If there is a default namespace declared in the document and the document fragment does not declare a namespace, the elements from the fragment are considered to be in no namespace.
For instance the fragment:
<item id="dty2"/> <item id="dty3"/>
Inserted in the document:
<?xml version="1.0" encoding="UTF-8"?> <root xmlns="nsp"> | </root>Gives the result document:
<?xml version="1.0" encoding="UTF-8"?> <root xmlns="nsp"> <item xmlns="" id="dty2"/> <item xmlns="" id="dty3"/> </root>
- insertLocation
An XPath expression that is relative to the current node. It selects the reference node for the fragment insertion.
- insertPosition
One of the three constants: "Inside", "After", or "Before" , showing where the insertion is made relative to the reference node selected by the insertLocation. "Inside" has the meaning of the first child of the reference node.
- fragment
The XML fragment that will surround the selection.
Example 7.4. Surrounding with a fragment
Let's consider the fragment:
<F> <A></A> <B> <C></C> </B> </F>And the document:
<doc> <X></X> <Y></Y> <Z></Z> <doc>
Considering the selected content that is to be surrounded is the sequence of elements
XandY, then the result is:<doc> <F> <A> <X></X> <Y></Y> </A> <B> <C></C> </B> </F> <Z></Z> <doc>Because the element
Awas the first leaf in the fragment, it received the selected content. The fragment was then inserted in the place of the selection.