Using Code Templates in oXygen XML Editor

Recently a project asked me how they might easily re-enter similar content in a file again and again while using oXygen XML Editor. They thought they might use a second file with a bits of template XML in and then copy and paste this in when and where they needed it.

“Aha!”, I said, “What you need are ‘Code Templates’ in oXygen XML Editor”.

Code templates are small fragments of code that can be added at the current editing position as and when you want them.  They are reusable and oXygen comes loaded with a bunch of them for various editor modes.  For example when using oXygen XML Editor to write XSLT I often type ‘ct’ and press control-space (Command-space on Macs I believe).

 

This displays a list of matching code templates and the tooltip gives you a preview of it. The Copy Template is a template which, by default, copies all of the input to the output (which you can then override for particular elements you might wish to change). In this case pressing enter inserts the following into my XSLT Stylesheet:

 

However, this project is editing texts in TEI XML rather than writing XSLT, how will this help them?  While I won’t go into specifics about this project in particular, let’s say they have to enter metadata about people they find referenced in the text.   To do this they wrap a <persName> element around the name and point to a <person> element in another file by its @xml:id.

Code templates probably won’t help us with this, fair enough, it is easy enough to wrap an element around some highlighted text with ‘Surround-With-Element’ (Control-E).  However, when it comes to inserting the <person> element to which this refers in their personography.xml file, code templates can really help. Let’s say that for each <person> they must provide an @xml:id attribute (here SMI123) and a standardised form of the name. If they have the data available they’d also like to provide a birth date, death date, institutional affiliation, occupation, nationality, and information about their education.  Although these are optional they’d rather have them there and delete them for those they don’t have the information for, rather than add them.  How do we do this?  First we come up with a template in our chosen document, testing that when we fill in attribute values and element content properly it will be valid.  So for example they might create a template such as:

 

This will help them create a template person. The red underlining of the values for @xml:id and @when are oXygen warning that these must be completed with valid values.

After having created this template, they would need to turn it into a Code Template.  To do this in the menus they go to Options -> Preferences -> Editor -> Templates -> Code Templates.  This will be filled with default ‘Global Options’ templates for things like the XSL Editor.

 

 

The image above shows the Code Template for the copy template I inserted earlier.  Notice that it has an additional feature a ${caret} at the bottom. This tells oXygen where to put the caret or cursor after it has inserted the Code Template.

To create a Person Code Template they would click on ‘New’ and fill in the shortname it will be known by, a description reminding you what it is for, and associate it with a particular editor (in this case the XML Editor).  In some more recent versions of oXygen you can also assign it a shortcut key (and if you want make these platform-independent if you are sharing them between people using different operating systems).

 

 

Here we’ve given the Code Template the name ‘person’ which means if we type the first part of that and press control-space then the template should be inserted. (Or we can press control-space and scroll down to ‘person’ if we have lots of other templates.) We’ve given it a description, associated it with the XML Editor, and given it a shortcut key of Contrl-Alt-P.  Care must be taken not to use shortcut keys your operating system is using for other things.  The ${caret} here means that when the ‘person’ Code Template is activated the oXygen XML Editor will place the cursor in place to add the @xml:id. There are other variables that can be added including various file names, paths, timestamps, dates, and other information the oXygen XML Editor has available to it.  However the most useful to those inputting fragments of XML are probably:

  • ${caret} – Cursor position after insert
  • ${selection} – Current selected text
  • ${ask(‘Message’, input_type, ‘default_value’)} – Interactively ask for values
  • ${timeStamp} – Timestamp
  • ${pn} – Project name

The ${selection} variable puts the text that you already had selected before triggering the shortcut at that point. The ${ask()} variable is a function that takes a message, some input_type (like ‘generic’, ‘url’, ‘combobox’, ‘radio’) and a default value. These can end up being quite complicated and more than one variable can be used in a single Code Template. For example, we could use the ${ask()} one to prompt these users to enter the @xml:id, forename, surname, birth and death dates, etc. However, since it is quite common for them not to have all of these details, it is probably easiest to just put in the XML and let them edit it.  More information on these and other variables can be found at https://www.oxygenxml.com/doc/versions/18.1/ug-editor/topics/editor-variables.html.

Although not all projects will need to insert <person> elements, it is hoped that if you are repetitively entering the same bit of code again and again, that Code Templates in oXygen XML Editor might be a useful shortcut for you.

 

Posted in XML | Leave a comment

Leave a Reply