Using the oXygen XML Editor

Table of contents

This document will show you how to configure and use the oXygen XML editor to write and edit OUCS documents.

1. Obtaining the Software

You will need a copy of the oXygen XML editor installed on your computer. This document assumes you have Version 10 (or a later version).

If you have a managed Windows desktop system, the ICT Support Team can add oXygen for you; mail them at itsupport@ict.ox.ac.uk. If you have an oXygen setup older than February 2009, delete it first, and start afresh. Delete the whole oXygen directory, it may have kept options files which will confuse you later.
If you use Ubuntu Linux, ensure you are set up to use OULD (see http://www.oucs.ox.ac.uk/ould/index.xml), and then install the package tei-oxygen
Otherwise, the latest version of oXygen should be downloaded directly from the developers web site: http://www.oxygenxml.com/download_oxygenxml_editor.html. oXygen will work on most operating systems. Please make sure you download the appropriate version for your machine. After you have downloaded the program, double click on the compressed file to unzip and begin the installation process.

Once installed, you will need to obtain a copy of the licence from the OUCS registration system (https://register.it.ox.ac.uk/self/software/). This needs to be pasted into the oXygen registration screen before you can use the program.

1.1. Starting oXygen

Once oXygen has been installed and the registration key accepted the program will open. You will see the following screen:

Figure oximages/oxygen-interface.png [oXygen interface]

The next stage is to download and apply the OUCS TEI setup into oXygen.

2. Obtaining and Installing the OUCS Templates

The Information Services Team have developed a series of OUCS-specific templates for use with oXygen. These should help you make new TEI documents from scratch and edit existing ones. You will need to download the OUCS Templates and then install them into the correct oXygen folder before you can use them.

OUCS Templates

Users of Windows managed desktop: The customization can be installed for you by ICTST suppport.
Debian or Ubuntu users using OULD: You can install the package ould-oucs-xml
Non-standard Windows, Mac, and other Linux users: Download /oucsweb/oucs-oxygen.zip. Now locate where oXygen has installed itself; in Windows that may be C:\Program Files\Oxygen XML Editor 10\, on Macintosh it will be in the Applications (or maybe your home) directory. In there is a directory frameworks. Unpack the zip file there (replacing some files existing tei directory).

You should then be able to open oXygen on an OUCS XML file and:

Edit in author mode
Validate the file
View your work locally in your favourite browser
Access a small range of OUCS Templates to help start you off

You are now setup to access OUCS templates and can work in either WYSIWYG (Author) or code (Text) mode depending on your own preference.

3. Making a working copy of some or all of the OUCS web site

Before you begin editing or making new OUCS documents you need to make a local copy of the part, or parts, of the OUCS web site that you are interested in. This is covered in the Syncro Client Guide and will not be covered here. Once you have a local working copy of the OUCS site you can begin to write or edit OUCS documents.

Please note: Saving files back to the central repository is also covered in the Syncro Client Guide and not repeated here.

4. Using oXygen

Once you have applied the OUCS Template files described in the previous section, you can open oXygen. To make the most of oXygen and its abilities to integrate with the OUCS Subversion system, you will now need to configure the built-in Subversion client called Syncro Client. Which is found under the [Tools] > [SVN Client] menu option. Full details on how to configure this to access both local and server repositories are given in the Syncro Client Guide. The rest of this document will assume that you have read and configured your system to use the Syncro Client.

4.1. Making a new document

To start a brand new document go to the top menu and select [File] > [New]. The New dialogue menu opens with two tabs:

Figure oximages/templates.png [New file dialogue box opens on New tab]

Select From Templates tab and scroll down the list until you find a template called TEI P4 - OUCS. Click on this name to open the template in the main oXygen work window. This document contains all the basic page structures needed for an OUCS XML web page. By default this file will open in Text view.

If you want to use the Author (WYSIWYG) view you need to switch the file to it. Near to the bottom of the working window, there are three words, Text, Grid and Author. One of these will be highlighted in a box. This box indicates which view you are currently using on the file. When Text is boxed you will see the code view of the file.

Figure oximages/textbutton.png [Position of text button]

If you wish to change to view you need to select the Author mode.

Figure oximages/authorbutton.png [Position of the Author button]

Clicking the Author button will result in a new window appearing telling you about white space. Just click on the OK button to continue. The Author view of your new file will now appear. Part of this is shown in the screen shot below. You can now start to add your new content.

N.B. In the rest of this document when Author is used it refers to the WYSIWYG view of the file.

Figure oximages/author-start.png [Author view of opened template]

In the Author view you will see that the oXygen syntax checker will underline the authority and email fields. These are not 'wrong' as such, but there is an error on the page. The date field above is empty and this is causing the error you see in the following two fields. Add a date into the <date> field to correct this problem. You should also give your document a title and also an author. Fill in both the <title> and <author> elements with the appropriate information.

This same error is also noted in the Text view. However in this view it is the <fileDesc> field that appears to be wrong. Again filling in a date will remove this error.

Figure oximages/author-start2.png [Shows examples of completed meta data]

Once the metadata (title, date, author) is complete, you can move on to writing the actual content your readers will see.

Anything written inside the <text> element will appear on your web page (providing you have correctly structured your XML of course!). If you are new to writing for our web site, you should read the Simple guide to XML. Those more experienced in web coding will find that the Guide to XML covers TEI XML in more detail. Whether you are experienced or not, you must make sure that any content you supply follows our Accessibility Rules. e.g. images must have 'alt' (alternative text) for instance. See the Guide to XML for lots of accessibility advice.

4.1.1. The Edit Toolbar

In the Author mode oXygen provides an Edit toolbar similar to those seen in word processing packages:

Figure oximages/edit-toolbar.png [Edit toolbar similar to those of word processors]

This Edit toolbar allows you to add in familar word processing features like images, lists, tables etc. To use a feature all you need to generally do is click the appropriate toolbar button. If you are in an appropriate place for that feature it will be inserted into your document. If the context is not correct, oXygen will display an error message.

To add bold, links etc. to text you should select the appropriate text and click on the Bold (or Italic) button to apply the presentational effect. Links are added by clicking the a button. You will see the element appear in your text as two triangles with the cursor inbetween them. Type in your link text making sure that it is meaningful when viewed outside of the context of the sentence i.e. 'Click Here', 'More', and other meaningless link phrases must NOT be used. The URL for the link is added to the curly brackets that are present in front of the first triangle. However, you cannot enter this directly into the curly brackets but you must use the Attributes panel (see next section).

Adding an image is slightly more involved but very similar to adding one to a normal word processing document. Clicking the hills and sun button will open up a browse screen where you can navigate to where the image is located. Select the image and click Open. The image will now appear in your document. N.B. to appear on our web site, you need to add the image to your local repository and submit it to the main Subversion repository.

Adding a table is slightly more involved as you need to state how many columns and rows your table requires. To insert a table:

Click on the Table button and Insert Table dialogue box appears:
Figure oximages/table.png []
Give a title for the table in the Head field
Choose how many rows and columns your table requires using the dropdown lists
Make sure the Generate Table Header checkbox is ticked
Click on OK to create the table
You can now add your data to the new table

It is also possible to add and remove columns or rows as well as merge and split them using the other table buttons present on the toolbar.

Adding paragraphs can also be done through the Edit Toolbar using the paragraph button. It should also be noted though that you can add paragraphs, new list items, and other elements by hitting the <Return> key. This causes oXygen to open up a Split dialogue box from which you can either add e.g. a new paragraph or choose a different element from the list to add to that point in your file. The dialogue box is shown below:

Figure oximages/splitting.png [The splitting dialogue box]

4.1.2. Elements and Attributes Panels

When writing your document, oXygen tries to help you by displaying what elements you can use at a particular point in your content. On the righthand side of the oXygen interface you will see two boxes, one called Attributes and another called Elements.

Figure oximages/elementsb.png [attributes and elements boxes ]

Both of these boxes are very useful. They list all available elements and attributes that can be used. If you are unsure as to what element you can use at a particular point of your code, look at the list provided in the Elements box. Please also remember to use the scroll bar on the longer lists, your required element maybe hiding! If you move your mouse over each element in the list a popup will appear giving you a little bit of information about each element:

Figure oximages/rollover1.png []

For a fuller description of elements and examples of their use, please see the Guide to XML document.

The Attributes box is also useful but used far less frequently. Attributes are most useful when you need to add an id, n (title) or rend (class) to one of the XML elements. Both the id and n attributes use the names provided by the author. The rend however is more specialised and used to add CSS classes to elements in the final web page. A list of rends and what they do, can be found in the Guide to XML.

When you need one of the elements to be applied to your text:

Select your text
Look in the Elements box to find the element you need. (N.B. if it is not displayed you cannot apply that element at that position in your document.)
Double click on the name of the element to apply it to your selected text
Your selected text will now have the element wrapped around it.
In the Author view your text will have two small triangles surrounding it indicating it has been applied. It may also show extra formatting e.g. coloured, bold etc., depending on the type of element applied:
Figure oximages/triangles.png [Shows triangles surrounding text in Author mode]
In Text view you will see the actual element applied around your selected text. All elements are coloured blue:
Figure oximages/text-view.png [Text view of the document]

Applying an attribute to an element is slightly different:

Text View

Find the element you need to add an attribute to and click inside the opening element
The Attributes box will list all that can be added to the element
To add an id to the element, click in the Value area of the id attribute found inside the attributes box. The Attribute and its Value field will turn blue
You need to repeat the click until the Value field becomes white again
Now add a short name e.g. myID and press <Enter>
The attribute is then added to the element in your code
When you become familiar with the attributes available on a particular element it is quicker to type in the attribute yourself as you code your document. oXygen also helps you with auto-complete as you type elements into your code.

Author View

Find the element you need to add an attribute to
The Attributes box will list all that can be added to the element
To add an id to the element, click in the Value area of the id attribute found inside the Attributes box. The attribute and its Value field will turn blue
You need to repeat the click until the Value field becomes white again
Now add a short name e.g. myID and press <Enter>
Figure oximages/attribute2.png []
The attribute is then added to the element in your code but this is not visible to you in Author view. You need to look at the Attributes box to see that one has been added to a particular element.

Sometimes you cannot easily get to an element e.g. the list element does not show up on the page while the individual list items do. In such circumstances you can either switch to Text view and edit it there or, in Author mode:

Go to the nearest element that you can easily see near to where you think you need to be
Look at the top of the editor window where you will see a list of elements
If you are in the right area you will see the e.g. list element listed
Click on the list name
All of the list in your page will become highlighted and the cursor will flash at the point of the list element in your page
You can now add an attribute to the element by using the Attributes box as previously described.

4.2. File Validation

oXygen has the ability to check your code as you type. This is a very useful feature of the program as it means errors are highlighted as you work e.g.

Figure oximages/errorhighlight.png [Errors highlighted in both modes]

oXygen/ also indicates errors throughout the document via the vertical strip at the side of the main content window. When you have errors you will see both a red square at the top and red bars down the strip. Clicking on one of the error bars takes you to where oXygen/ thinks the error is located.

Figure oximages/error.png [Error indicators shown in vertical column]

When the file content is all valid XML, the red box will turn green and there will not be any red bars in the column..

Figure oximages/validfile.png [Valid file indicated by green box in vertical column]

4.3. Viewing your work

It is always useful to see what your page looks like as you work. There are two options available to you:

Submit the file back to the main repository and view on the Preview web site. This will give you the most authentic view of the page.
Transform the page locally and view in your favourite browser.

The first option is covered in the Syncro Client documentation and will not be repeated here.

The second option where you can view your work locally will give you a good idea of how your page will appear on the real web site - but not entirely. The major difference is that your major divisions will not be show as separate pages. You will see your work as one long page, broken down into sections.

In both Text and Author modes the method to transform your work into a web page is the same.

In oXygen's top menu, you will see a series of buttons:

Figure oximages/scenariosbuttons.png []

The first button is the Start Transformation button. This will either provide a list of possible scenarios if this is the first time you have used it or it will use the last transformation configuration you used. The second Spanner button will allow you to pick from a list of possible transformation scenarios. The third button is the Debug Scenario button but this is outside the scope of this document.

To choose which transformation scenario you want to use, click on the Spanner button. This will open the

Configure Transformation
              Scenario

dialogue box. Here you will see several different scenarios that you could apply to your XML file.

Figure oximages/scenarios.png []

The default OUCS style is called OUCS Normal. Selecting this option will transform your XML and the output will look very similar to the normal OUCS web page style with the exception that it will appear as one complete page and not split into different pages as will be the case on the real site. Choosing the OUCS LTG transformation will make your page look like a page from the LTG sub site. Similarly if you go for the OUCS one column transformation, the resultant page will just show your content in a single column with no side column navigation area present.

To transform your XML file into the standard OUCS style:

Click on the Spanner button
Select [OUCS Normal] from the list and click on the Transform Now button
You will see a green box with a short message stating that the transformation is in progress appearing at the foot of your XML file
When the transformation is complete, your page will appear in your default web browser for viewing.
If you now edit your XML again and want to see the file in the same OUCS style you can just click on the first button. The OUCS normal transformation will automatically be applied to your XML file and will open in your default browser. (To change this behaviour to a different scenario you must reconfigure your transformation option again)

Please Note: If the document has XML errors in it the transformation will fail. Please make sure you have a valid document before proceeding.

Below are three different views of the same document produced with the OUCS Normal, LTG and One column transformations:

Figure oximages/normal-transform.png [View showing result of OUCS Normal transformation]

Figure oximages/ltg-transform.png [View showing result of LTG transformation]

Figure oximages/single-col-transform.png [View showing result of single column transformation]

If you need other transformation scenarios please contact the Information Services Team.

4.4. Publishing to the Internet

Unless you have special access you can only publish files through the Preview web site.

Publishing a file

Go to the Preview web site and find the page to be published
At the top of the preview page there are a series of buttons, the most important of which is the red button p-file (means publish file). Click this button to publish the file
A new page appears stating that the file has been committed and that it is now live. You can either return to the preview page or visit the live one via links on this confirmation page

Publishing a directory of files

This is very similar to Publishing a file above but here you publish all files in a directory instead of a single file.
Go to the page which is inside the directory with new pages to publish
Click on the p-dir button (means publish directory) a new page opens listing all the unpublished files in that directory
Decide which files to publish and uncheck any that should not be published
Click the red Make the above changes to the website button
Your files are now published to the live server and are available for viewing
You will see a new page inviting you to return to the preview version of the page or to go and see the live version

4.5. Available Templates

oXygen now has built-in OUCS templates for your use. These are:

General OUCS template
Job Description template
General Minutes template
SMG Minutes template

The Information Services Team are happy to make more templates for you. Please contact the Information Services Team if you need a specific template constructing.

IT Services

Using the oXygen XML Editor

Table of contents