Untangling Data Complexity: Custom Oxygen Frameworks for Edition Projects

What Is an oXygen Framework?

When editing an XML file, oXygen enables users to seamlessly switch between an XML view (Text mode), displaying the raw XML code, and a visual editing environment (Author mode). In Author mode, the code is presented in a visually enhanced format. A framework is a configuration or set of rules defining how XML documents are structured, presented, and edited.

The advantage of the Author mode is that it enables users with little or no knowledge of XML to work with XML files without having to engage directly with the XML code, as it is hidden from them. For example, the editing process can be made more controlled and streamlined by displaying only those fields (elements) that are to be filled with content, or by implementing dropdown menus that allow only certain predefined values to be added to the XML file. Users can insert, modify, or delete XML fragments using various functionalities without accessing the actual source code. Hiding the source code behind a form-like appearance minimises errors and inconsistencies, such as inserting elements in the wrong place or the accidental deletion of elements.

A framework can be as simple or as complex as required, varying greatly in the number of functionalities and features provided. Frameworks can therefore be tailored to different data complexities and requirements, and are not limited to specific use cases.

It is crucial to note that the framework options are both extensive and powerful, mirroring the capabilities of oXygen. However, this review will only focus on and assess the functionalities we deem useful for projects working on digital editions, as shown in section ‘Creating a Framework’.

General Technical Aspects

oXygen and its functionalities are written in Java. However, as oXygen is designed for editing and processing XML data, customisers only require Java skills if they wish to modify or expand core functionalities or write their own operations. The integrated functionalities should be sufficient to handle most use cases. Moreover, since XML is the designated data format, all operations related to XML data (such as XPath, XQuery, XSLT transformations, schemata) are fully supported.^*

Performance issues emerge in larger files (initially observed in a 1.3 MB file), especially when combined with complex CSS rendering and continuous background validation. The framework’s response time noticeably slows down, impacting processes like inserting fragments or navigating from one fillable form field to another. As of now, the exact cause and potential countermeasures have not yet been determined, as this issue has not been systematically analysed.

Installation and Building Process

oXygen allows users and customisers to create and use frameworks, regardless of the operating system used^*. However, it is important to note that the editor’s interface and the layout of the created framework, including spacing and field size, may vary. The steps required for installing a framework depend on the person’s role, whether they are a customiser (i.e. technical personnel) or a user (i.e. involved in editing the texts).

For customisers, in order to create a framework for a project, a few preparatory steps and configurations are necessary.^* Those include:

• The creation of a specific folder hierarchy (e.g., Demo/framework), as well as folders for icons, templates and a CSS file (fig. 1).
• The referencing of the folder structure as a Location in the Document Type Association Tab in oXygen (fig. 2).
• The actual creation process of a new framework (Document Type) in the Document Type Association Tab.

During this creation process, the framework is named, the previously created folders and files (framework folder, template folder, and CSS) are assigned, and the criteria on the basis of which a framework is applied to a file (association rules) are defined by the customiser.

For instance, fig. 3 shows the association rules for a Demo framework specifying that it is applicable to all TEI files with the attribute @rendition and the value ‘demo’ in the <TEI> root element.

After all these configurations, the newly created framework will be visible in the Document Type Association list. It is crucial that customisers initialise the framework by clicking on ‘Apply’. This will automatically generate a *.framework file in the chosen directory, containing all the framework’s information (fig. 4).

Once these steps have been completed, customisers can start editing the framework. It is recommended to create an oXygen project for the development process (see SyncRo Soft SRL 2002–2024d), as this allows for quicker access to the files.

To use a framework, all users need to do is associate it in oXygen. For this, customisers can either package the framework as an add-on for users to integrate or implement a GitHub (see GitHub Inc. 2024) or GitLab (see GitLab B.V. 2024) workflow for file sharing, which has proven effective for us^*. If the latter is set up, users can simply:

• Clone the framework repository from GitHub (or GitLab).
• Open oXygen, navigate to the Document Type Association Tab, and add the cloned folder structure as a Location.

The framework is then added to oXygen, and any file containing the defined attribute-value pair in the root element will automatically be rendered using the framework’s layout and have all its features.

Technical Know-How

For customisers, proficiency in CSS is essential for the design, as XML is translated into the visually appealing and user-friendly display of the Author mode through CSS. To selectively address and manipulate individual elements within the – sometimes intricate – XML structure or to insert a fragment at a context-dependent location, the ability to navigate the XML tree using XPath expressions is also necessary.^*

While not strictly necessary, an understanding of the concept of variables and skills in XSL, XQuery, or JavaScript are helpful for making full use of the tool, as it supports the inclusion of scripts via dedicated Author Mode operations (e.g. JSOperation, XSLTOperation, and XQueryOperation^*). This allows for more complex XML manipulations for which the tool does not provide build-in operations.

Finally, knowledge of and the use of schemata such as XML Schema (see W3C, Fallside, and Walmsley 2004) or RelaxNG (see “RELAX NG Home Page” 2014) facilitate control over the data, preventing issues such as proliferation of attribute values, and ensuring that fragments are only inserted in valid places.

Conceptual Know-How

Before commencing framework development, the project’s conceptual objectives, requirements, and prerequisites must be established. This is vital for creating a tailored framework that meets the project’s specific needs. The process involves a comprehensive analysis of the source material and identification of existing groundwork (e.g. existing annotations of the data and / or defined data model) and requirements for the framework (e.g. how should it support users, what should be recorded and how). It also requires addressing questions related to the depth of information, features of the published (digital) edition, and any research questions the project aims to answer.

Guided by these conceptual considerations and building upon a data model^*, customisers can create template XML files, which are then accessible to users through oXygen’s ‘New Document’ option.^* Templates provide the project’s individual XML structure and placeholders for data entry, ensuring uniformity across all files.

Technical Interface and GUI

Once created, the framework is stored in a .framework file, which is a configuration XML file that encapsulates all the settings and resources needed to work with XML-based documents associated through document type association. This means, it can be manually accessed and edited in oXygen, just like any other XML file. Alternatively, the tool provides a graphical user interface (GUI). It primarily consists of classical dialogue boxes for creating and editing the framework.

The GUI generally poses no obstacle for customisers familiar with working with oXygen. It has the advantage of providing framework variables and displaying all possible options for selection, making it easier to configure settings without needing to know the exact XML syntax. However, the tool follows a logically formal arrangement of options, which regrettably causes essential settings to be somewhat hidden. It might be helpful if fundamental configuration options were more prominently placed or highlighted. For example, while actions are the core features of each framework, their configuration options are found only in the fourth tab within the second submenu of the dialogue box (fig. 5).

The same applies to the valuable option of integrating the framework’s actions into a new custom oXygen toolbar or menu^* (fig. 6, 7).

While the GUI proves to be sufficient and comfortable for most tasks, there are instances where direct access to the framework file is a more effective approach. For instance, if modifications are required in later stages of framework development, such as altering the name of an element that is used in multiple instances, the XML framework file can easily be searched, ensuring comprehensive changes across all fragments. In contrast, in the GUI each action dialogue box needs to be opened, checked and edited manually. Additionally, due to the restricted size of the input field for fragments in the dialogue box (fig. 8), directly inserting content into the XML file may be easier. However, the fragment is inserted as a plain text string without any code markup, which significantly reduces readability (fig. 9).

Terminology and Functionalities – Overview

oXygen provides a variety of built-in functionalities that can be used in either the CSS file or the framework file to facilitate interaction between the user and the document. The following is an overview of options deemed most useful, some of which will be explored in more detail later on.

Author Mode Action^*: used in the framework file. Actions are the core feature of the framework. Their main elements (fig. 10) are:

• ID – to identify each action and make it invocable from anywhere in the framework, such as the CSS file or other actions.
• Description – a plain text description of the action’s functionality to be displayed to the user on mouseover.
• Icon – to visually represent the action when it is displayed as a button, for example in the toolbar.
• Keyboard shortcut – to call the action using a keyboard shortcut.
• Operation – the operation to be performed and its arguments.
• XPath constraint – to enable or disable application of the action in certain parts of the document.^*

Author Mode Operations^*: used in Author Mode Actions; serving as the primary task to be performed, for example:

• DeleteElementOperation – deletes an element.
• ExecuteMultipleActionsOperation – consecutively calls and executes a list of actions via their ID.
• ExecuteValidationScenarioOperation and ExecuteTransformationScenariosOperation – validates or transforms the document using a scenario already configured in oXygen’s validation / transformation settings.
• InsertFragmentOperation – inserts an XML fragment.
• XSLTOperation – executes an XSL transformation either referencing an external XSL file or providing the entire script in the action’s script argument.

Form Controls^*: used in the CSS file to provide graphical user interfaces, for example:

• oxy_browser() – to integrate an HTML frame.
• oxy_checkbox() – a checkbox to select or de-select an option.
• oxy_combobox() – a dropdown menu with predefined values.
• oxy_datePicker() – a calendar (with the option to specify the desired date format).
• oxy_textfield() – a plain text input field.
• oxy_video() – to integrate a video.

Custom CSS Functions^*: used in the CSS file to enhance the layout for users and perform specific operations on values, for example:

• oxy_action() – calls a predefined action from the framework or defines an action directly.
• oxy_concat() – concatenates strings.
• oxy_editor()^* – used in combination with oxy_label() to style forms.
• oxy_label() – supplies a display label for the edited segment.
• oxy_xpath() – evaluates an XPath expression.

Additional CSS Properties^*: used in the CSS file to control the appearance or behaviour of elements, for example:

• -oxy-collapse-text – to hide the text content of an element, for example, when it is already rendered using a function such as oxy_editor() (otherwise the content would be displayed twice).
• -oxy-editable – to enable or prohibit editing the content of an element.
• -oxy-foldable – to make elements foldable, for example, the metadata or facsimile section at the beginning of a TEI document.
• -oxy-placeholder-content – to show a placeholder for empty elements to let the users know what kind of input is expected (particularly useful when a form-like layout with labels is not feasible).

Editor Variables^*: used in the framework file to define reusable values and thereby facilitate flexible interactions between users and the framework, for example:

• ${ask} – to ask users to provide more input or to choose from a given set of options before an XML fragment is inserted, e.g., values for attributes.
• ${caret} – current cursor location, e.g., to set the next editable position inside or after an inserted XML fragment.
• ${date} – to insert or display the current date.
• ${framework} – the path of the current framework directory, e.g., to set a relative path to the folder containing icons used in the framework.
• ${id} and ${uuid} – application-level or universally unique identifier, e.g., to generate IDs to insert into the XML file or to use only during processing.
• ${selection} – currently selected text, e.g., to surround it with an XML fragment.

Design and Visualisation (CSS)

The design of the final framework is entirely in the hands of the customiser. Whether users consider a framework practical or not depends on how the customiser shapes the framework and utilises the capabilities provided by the tool. It must therefore be noted in all subsequent considerations that only the presence of a function in the tool or its implementation effort should be understood as part of this paper’s tool critique, not the actual realisation and configuration in the individual framework.

In our experience, a framework’s acceptance among users and non-technical personnel is improved by visual proximity to familiar programmes. For instance, aligning the layout with widely-used word processing programmes such as MS Word lowers the entry barrier due to familiarity and facilitates intuitive use. Actions such as highlighting text and applying formatting through a toolbar button, for example, to mark headings or italicisation, are well-known to users. The tool allows customisers to create buttons in a similar manner, group them in a toolbar, and assign them individual actions. This layout is particularly suitable for projects or documents where predominantly prose text is generated, such as transcripts or introductory sections.

Regarding the rendering^* of the XML file, essentially anything styleable using CSS is possible^*, such as Word-like page layouts, frames, colours, and more. However, CSS rendering has its limitations. Since no transformation or programming language is involved, each element is simply output where it appears in the document. Re-ordering or repositioning elements, such as numbered footnotes, or grouping and sorting metadata for neater input, is not possible, whereas in web development, CSS is widely used for these tasks. Furthermore, context-dependent styling is limited to the capabilities of CSS selectors: an element can be styled differently, for example, depending on its ancestor elements (parent / ancestor selector) or when it differs in terms of attributes or attribute values (attribute selector). However, it is not possible to conditionally output or style elements based on the presence of specific descendant elements.^*

Beyond conventional CSS styling options, the tool provides additional oXygen-specific CSS functionalities that broaden the spectrum. For instance, clearly structured and self-explanatory form fields can be designed through the oxy_editor() function (generating an input field that can be filled in by the users, adding either element content or attribute values), and explanatory labels can be provided through the oxy_label() function (fig. 11). As users are usually familiar with filling in forms, this approach combines intuitive form completion with standardised input formats, ensuring good data quality. In our projects, we found the form approach particularly useful in areas where traditionally highly formalised information is provided, such as metadata, bibliographic details, indices, or object descriptions.

Especially in digital edition projects, where data is traditionally published online both as data and as a digital edition, there is also the opportunity to tailor the framework’s design to align with the online presentation. This way, users can already visualise the future presentation of the edited text during the editing process, which is often perceived as helpful. For instance, elements that will later be presented as links can already be displayed in blue and underlined in the framework, elements denoting quotations can be surrounded by quotation marks, and text justification, indentation, or different font sizes can already be implemented.

One last aspect not to be underestimated is the ability to hide elements from the XML file that are relevant only for technical personnel, not for users, such as sections related to copyright and rights. This ensures a cleaner look and prevents accidental alterations to sections that should not be edited.

Functionality (Framework)

There are often multiple ways through which a single action can be realised (fig. 12). For instance, when a date value needs to be inserted into the document, the tool offers the option to open a calendar dialog box (oxy_datePicker()). Users can then select the date from the calendar, and it is automatically inserted in the desired, predefined format. Additionally, there is the option to insert the current date directly through an editor variable (${date}). And, of course, a free text field can also be created, allowing users to manually input the date (oxy_textfield()). All three options have legitimate use cases, and the choice made by the customiser depends not on limitations of the tool, but on the specific needs of the project. For new customisers, it would be helpful if more projects shared their examples, specific use cases, and experiences online. This would provide a broader understanding of the advantages and disadvantages associated with different implementation approaches.

It is important to note that the person customising the framework is often not the one using it. We therefore consider the need for communication between customiser and user as an essential part of working with the tool. Ideally, users express a desire for workflow improvement or highlight a cumbersome step, and the customiser provides a solution by implementing a suitable action from the tool.

Following is a selection of settings, operations, form controls, and variables, which have proven particularly useful for working on digital editions. As mentioned earlier, the capability to design buttons through which users can trigger actions is a central feature of the tool. They can be freely arranged in the toolbar, visually sorted using separators, or grouped thematically in dropdown submenus. The oxy_action() function in CSS allows buttons to be directly output within the text. This option is particularly useful when an action only makes sense at specific points in the document, such as when users should be able to delete an optional element. Icons can be custom-designed, and a freely formulated mouseover message can inform users about the action triggered by the button.

When there is a need to add content to existing elements, dropdown menus can be easily styled using the oxy_combobox() function. While the primary use case likely involves adding attribute values, it is also possible to provide a list of text content to choose from. This is particularly useful when standardised values are frequently repeated but should be inserted as a text node rather than an attribute value. For example, if the text genre in the metadata section isn’t manually inserted but can be selected from a list of options and then applied as a text node, it reduces the user’s typing workload, ensures consistency, and eliminates the risk of typographical errors.

When combined with the oxy-xpath() function, a dropdown menu doesn’t necessarily require a fixed, predefined list of values; instead, it can dynamically fetch and display values based on the provided path. For instance, in a section where the user must specify a location, the list of values can import the project’s index file and offer only those entries that are discernible as place names.

To assist users in using the framework correctly, external points of reference can be included. For example, oxy_video() allows the embedding of locally stored or remote videos (such as YouTube tutorials), providing guidance for users throughout the editing process. The oxy_browser() form control facilitates the integration of web pages, enabling customisers to link parts of a documentation to the framework. Customisers proficient in Java coding can also create their own custom form controls (see SyncRo Soft SRL 2002–2024k).

One of the most frequently used operations is to insert an XML fragment, for example, to create a new empty entry in an index file, which can then be filled in by the user (InsertFragmentOperation). The insert position is freely selectable (before / after, as the first / last child) and the insert location (any element in the document) can be specified via XPath. Thus, it does not necessarily have to happen at the point from which the action is triggered.

If the fragment is not only to be inserted but also to replace the selected content or surround it with markup, there are two closely related alternatives to achieve just that (InsertOrReplaceFragmentOperation and SurroundWithFragmentOperation). These are useful when it is necessary to add markup to existing text or elements, for instance, to mark a selected text as an entity, such as person or place, and surround it with the corresponding XML markup.

The XML fragment to be inserted or wrapped around the selected text is stored in the framework file and is output as is. However, there are instances where it proves beneficial to permit users to augment the fragment before it is inserted. This involves options such as selecting from a predefined list of attribute values to categorise an entity as either a person or a place. This approach enables key parts of the fragment to be determined dynamically without the need to customise separate actions for each variant. To facilitate this, editor variables can be used in the XML fragment. While powerful, these variables can be intricate to write in the input field due to their complexity. For instance, the ${ask} variable can be used to create a dialogue box, prompting users to choose from a list of predefined values in a radio menu^* before inserting the XML fragment with the selected values. A simple fragment (<entity>) with only two values (‘person’ and ‘place’) for the @type attribute might look as shown in fig. 13.

Customisers can specify a title for the dialogue box, telling users what kind of information they need to provide (‘Choose type of entity’), along with a list of values to be inserted into the fragment, a label to display in the dialogue box (‘Person’ and ‘Place’), and a default value, pre-selecting the option in the radio menu (‘person’).

The importance of the default value argument must not be underestimated. It allows users to swiftly proceed through dialogue boxes by pressing ‘Enter’ if the most common option is pre-selected. Day-to-day use has shown that these seemingly minor simplifications can significantly enhance work efficiency. The ${ask} editor variable has proven useful and very popular among users, as manually entering the sometimes quite technical attribute values can be tiresome. Moreover, it reduces the necessity for displaying separate input fields for each attribute, contributing to a cleaner framework. This is especially useful for projects that rely heavily on storing standardised information in attributes instead of textual element content.

Particularly for complex encoding it may not always be possible to achieve the desired result in a single action. The ExecuteMultipleActionsOperation allows listing multiple actions that are then triggered consecutively. For example, the first action might insert a <graphic> element to the XML file, asking users to provide an ID and an URL to the image file. A second action could then execute an XSL script using the XSLTOperation to update a corresponding facsimile section of the document. The XSLTOperation is a powerful operation, as it allows for complex manipulations of the XML file which are not possible with the build-in operations. It must be noted, however, that the tool’s interface only provides a small input field for providing XML fragments or scripts. Due to the window’s limited size and without most of oXygen’s usual code support, such as colours and indentation, debugging and maintenance can be difficult. It is therefore recommended to store XSL scripts as separate files.

Alternatively, the ExecuteTransformationScenariosOperation could be employed, which references and triggers a transformation scenario already configured in the transformation settings, thus including all the scenario’s arguments, such as defining an output file path for the resulting document.

Another highly advantageous configuration option involves the ability to mark text content, entire elements, attribute values, or suggested values in dropdown menus as either editable or non-editable by setting the editable argument of the function to either true or false. This way, more technical segments, such as IDs, metadata, or attribute values, can be selected and displayed but not altered. If entire elements should be displayed for review but not edited, the CSS property -oxy-editable can be set to false.

And finally, for clarity of layout, the :empty (and :not(:empty)) selector in CSS has proven particularly effective. It enables the customiser to reduce the display to relevant parts of the XML file or to present action buttons in the text only when they are contextually appropriate, such as displaying an ‘open link in browser’ icon only once a URL has been provided. It enhances clarity when specific elements or actions are revealed to the user only after a higher-level value has been selected or entered. Moreover, empty fields can be highlighted in colour, or specific placeholder content can be displayed using the -oxy-placeholder-content CSS property, drawing the user’s attention to missing inputs.

Documentation and Learnability

oXygen’s website provides a comprehensive guide (see SyncRo Soft SRL 2002–2024j) for creating custom frameworks, with additional resources available in various webinars on oXygen ‘s official YouTube channel (see SyncRo Soft SRL and @oxygenxml 2004). However, these materials provide only a basic overview. The webinars primarily focus on customising the DITA framework or addressing specific use cases. The website documentation outlines the functions of individual options but lacks clear implementation instructions and examples. This information gap is particularly noticeable regarding the built-in Author Mode operations.

In some cases, unexpected issues may arise, such as with the SurroundWithFragmentOperation and the InsertOrReplaceFragmentOperation. The intention was to display a button in the text, triggering the action of surrounding a selected passage of text with XML markup (indicated by explicitly including the ${selection} variable). However, the action was not applied to the selected text. Instead, an empty element fragment was inserted where the button was displayed. Apparently, the text selection was shifted to the button’s position when it was clicked. This issue could only be resolved by relocating the button to the toolbar. Instances like these highlight the need for more comprehensive documentation and additional examples.

In other sections the documentation omits the explanation of functions that seem to be deprecated but still work, as exemplified by the oxy_editor() function. It was introduced to the framework in 2012 (see SyncRo Soft SRL 2012) to facilitate form-based layouts. As noted before, the oxy_editor() function can include any form control as an argument, such as comboboxes. The two code snippets shown in fig. 14 and 15 are therefore functionally identical.

Both versions create a dropdown menu, offering the values A, B, C, D for the @type attribute of the <p> element. The value selected by the user will then be used as the attribute value. The oxy_editor() function is widely used in webinars, yet it is missing from the current documentation. This means new customisers cannot find any information on the arguments associated with this function.

In our opinion, the documentation could be improved by adopting a more user-friendly style and intuitive navigation system. Currently, it adheres to the formal structure of the GUI dialogue boxes, making it difficult to find important features. The table of contents can also be challenging to navigate, especially for first-time users who are not familiar with form controls, CSS functions, and other technical distinctions. Improving the clarity and structure of the documentation would help customisers access the information they need.

In summary, learning to use custom frameworks can be challenging and requires extensive research through written documentation and video tutorials. The full potential of the tool may only become apparent through interactions with experienced customisers and users who actively use frameworks, as they can often identify areas for improvement by addressing tedious or laborious processes that may not be immediately apparent to new customisers.