Functionality (Framework)

48It 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.

49Following 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.

50When 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.

51When 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.

52To 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).

53One 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.

54If 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.

56Customisers 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’).

57The 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.

58Particularly 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.

59Alternatively, 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.

60Another 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.

61And 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

62oXygen’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.

63In 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.

64 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.

65Both 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.

66In 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.

67In 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.

Conclusion

68Custom oXygen frameworks are a powerful tool to enable users with little or no knowledge of XML to engage directly with XML files, thereby lowering the barrier for non-technical personnel to work in digital edition projects. Creating and maintaining frameworks requires a certain level of technical knowledge from the customiser, including proficiency in CSS, schema languages, XPath, and XSL. For users of a framework, a significant challenge may arise from the complexity of the oXygen XML Editor itself, as it can initially feel overwhelming with its numerous features and functionalities. However, once the hurdle of setting up and familiarising oneself with oXygen are overcome, the benefits of using frameworks in projects become clear. They significantly reduce the need for specialised technical and digital annotation knowledge by visually replicating familiar systems (e.g., designing the framework as a form or making it resemble known text editors like Word). This allows users to focus on their annotation work in a familiar environment while producing high-quality data.

69Frameworks integrate well into existing project workflows and processes, as diverse techniques and project materials can be seamlessly and flexibly combined to create a comprehensive working environment that encompasses content creation, validation, and documentation. Data quality is reliably ensured, as the data inserted through the framework is uniform, and illegitimate or missing content can be highlighted and easily spotted by users. The built-in actions and functions meet the majority of editing requirements and can even be expanded and customised when necessary.

70Regrettably, the custom frameworks tool is not prominently featured in the oXygen environment, and its potential is not effectively communicated. A more user-friendly documentation and more real-world examples from other users and customisers would significantly improve visibility and accessibility.

71While the term ‘framework’ is often used interchangeably with ‘ediarum’, it is crucial to recognise that they are not synonymous. Ediarum is a large-scale working environment that relies on oXygen frameworks, whereas using the oXygen custom framework tool directly to create project specific frameworks is a highly effective and less technically demanding solution. The broad range of functionalities and options available cover all of our projects’ use cases. Even knowing or using only a basic set of the tool’s features, some of which were explored in this paper, is still sufficient to meet the tailored needs of most edition projects.

72To conclude, in our project experience, both the customisers and the users consider oXygen frameworks to be an effective, recommendable tool that significantly improves the editing workflow.