Using the oXygen XML Editor

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 1. oXygen interface

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

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 2. New file dialogue

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 3. Text button

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

Figure 4. 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 5. Author View

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 6. Title, Date and Author metadata fields completed

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 7. Edit tool bar

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:

1. Click on the Table button and Insert Table dialogue box appears:
   

   Figure 8. The table dialogue box
2. Give a title for the table in the Head field
3. Choose how many rows and columns your table requires using the dropdown lists
4. Make sure the Generate Table Header checkbox is ticked
5. Click on OK to create the table
6. 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 9. Example of splitting

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 10. 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 11. The rollover text seen for the div element

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 12. Visualization of elements in Author view
• In Text view you will see the actual element applied around your selected text. All elements are coloured blue:
  

  Figure 13. Text view

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 14. Highlighted text and the corresponding attribute box
• 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 15. Error highlighting in both Text and Author 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 16. Locating error indicators

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 17. Valid file indicator

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 18. Transformation buttons

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 19. Possible Scenarios to apply to your XML file

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 20. OUCS Normal transformation

Figure 21. LTG transformation

Figure 22. 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.