Author Settings

You can add a new Document Type Association or edit the properties of an existing one from the Options+Preferences+Document Type Association option pane. All the changes can be made into the Document type edit dialog.

 

Figure 7.12. The Document Type Dialog

The Document Type Dialog


 Configuring Actions, Menus and Toolbars

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:

 
  1. Open the Options Dialog, and select the Document Types Association option pane.

  2. In the lower part of the Document Type Association dialog, click on the Author tab, then select the Actions label.

  3. To add a new action click on the Add button.

 The Insert Section Action

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.

 

Figure 7.13. The Action Edit Dialog

The Action Edit Dialog

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.

Toolbar icon

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]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.gif is located in the directory images inside the jar archive, you can refer to it by using /images/Section20.gif. The jar file must be added into the Classpath list.

Menu icon

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]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]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]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".

 The Insert Table Action

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]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".

 Configuring the Toolbar

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.

 

Figure 7.14. Configuring the Toolbar

Configuring the Toolbar


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.

 

Figure 7.15. Author Custom Actions Toolbar

Author Custom Actions Toolbar

 Configuring the Main Menu

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.

 

Figure 7.16. Changing the Name of the Menu

Changing the Name of the Menu

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.

 

Figure 7.17. Configuring the Menu

Configuring the Menu

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. The menu contains at the top the Author actions that are not dependent on the current document type, that is the generic actions. In the menu we find the Table submenu and the two actions:

 

Figure 7.18. Author Menu

Author Menu

[Note]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.

 Configuring the Contextual Menu

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.

 

Figure 7.19. Configuring the Contextual Menu

Configuring the Contextual Menu

To test it, open the test file, and click to open the contextual menu. In the lower part there is shown the Table sub-menu and the Insert section action:

 

Figure 7.20. Author Contextual Menu

Author Contextual Menu

 Author Default Operations

Below are listed all the operations and their arguments.

InsertFragmentOperation

Inserts an XML fragment at the current caret position. The selection - if there is one, remains unchanged. 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.

 The arguments of InsertFragmentOperation
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]Note

You can use even undeclared namespace prefixes, if they are declared in the document where the insertion is done. For clarity, we recommend always to prefix and declare namespaces for the elements in the fragment!

[Note]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.

 The arguments of SurroundWithFragmentOperation
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 X and Y, then the result is:

<doc>
   <F>
      <A>
         <X></X>
         <Y></Y>
      </A>
      <B>
        <C></C>
      </B>
   </F> 
  <Z></Z>
<doc>

Because the element A was the first leaf in the fragment, it received the selected content. The fragment was then inserted in the place of the selection.