Setup preconfigured DITA

If you want to use or try DITA, you can start with our pre-built package. Following the instructions to install Xeditor (see link) but get @xeditor/xeditor-dita instead of @xeditor/xeditor-demo. This package uses our Blackbox by default and contains all necessary plugins. You can find additional information about our middleware server (Blackbox) and its basic concepts here.

DITA specific configuration

As the DITA demo package is already pre-configured and can be used without any adjustments, it already contains some configuration files.

First of all, the schema specific configuration is already included as part of a npm module. The modules are called @xeditor/schema-dita-1.2 and @xeditor/schema-dita-1.3, one for each version of DITA. They contain:

  • Schema configuration (types.js)
  • Dialogs adjusted for DITA
  • Listeners adjusted for DITA
  • General logic for DITA
  • Predefined toolbar button templates
  • DITA specific phrases
  • Styling for DITA elements

Additionally, the DITA demo package already contains defined toolbar configurations for different schemas. They are already placed in /src/js/config/ and can be adjusted to your needs.

DITA-Version and schema changes

Xeditor DITA edition 4.0 uses DITA 1.3 by default, but also supports DITA 1.2. In order to work properly, Xeditor needs two XML Schema definitions of DITA. One used for validation and one used for the generation of the configuration which is contained in types.js (see the core documentation for further information). The files used for the validation are the original DITA files.

Note: The files used for validation are placed in /WEB-INF/xsd/ of your DITA project.

DITA specialization

This chapter will describe how Xeditor handles specializations. It will also describe how to add a new specialized schema configuration to Xeditor.

About Xeditor and DITA specializations

Configuring DITA specializations follow a similar process to configuring any XSD/DTD from scratch in Xeditor (see Schema configuration).

The differences are noted here.

Specializations and styling

As the HTML elements within Xeditor use the same HTML classes as the DITA element, the styling of those elements is addressed using CSS class selectors. Each DITA default class is addressed within the CSS file editor.css. As specialized elements have to descend from at least one known class from the default DITA classes, each specialized element will automatically have the styling of the known classes.

However, it is still possible to adapt the styling of the specialized element. In order to to so, you only have to add the new class within the custom file editor.css found in /static/css/.

The new entry should look like this:

.classGroup\/newElement {custom styling of the new Element;}

Note: the ‚/‘ which separates the class group from the element name has to be escaped within the CSS file. Therefore the ‘/’ within the class has to be replaced with ‘\/’.

Specializations and transformation

As XSLT 1.0 doesn’t support schema aware transformations, we created an XML help file which matches all elements defined within the schema definition with their class. It also splits the found class down to each sub class, so it will indicate all elements the specialized element descends from. The help file classes.xml will be created using our specialization tool.

For example, a specialized element which descends from the note element would look like this within the file classes.xml:

<element name = ”newElement”>
<class>- topic/note elementGroup/newElement </class>

Note: The ‘|’ after each splitted class is used to indicate the end of each class. Otherwise elements like title and titlealts would match for the same template, as the XSL checks if given variables contain the given class.

The transformation file contenttoeditor.xsl contains variables which are used for matching each known DITA class with different XSL-templates like mixed or structure or inline.

The main steps of the transformation are as follows:

  1. The template which matches for each node will get additional information about the elements class by reading the help file classes.xml. It will call a new template with the following parameters:
    • length: The amount of classes found for the element
    • all: An Array containing each class of the element
    • current: The last class of the element
  2. The called template will check if the passed class is contained by one of the specified variables and calls the corresponding template for the actual transformation, if found.
  3. If the passed class is not contained by the specified variables, the template will call itself with adjusted parameters, including the elements previous class.
  4. Step 2 and 3 will iterate until the current class could be matched.

As DITA specializations have to use at least one of the default classes, each specialized element will be transformed according to its class. Furthermore, the transformation will always use the last known class, which guarantees that the element is as specialized as possible, but will still be transformed correctly.

Specialization and info.xml

The file info.xml contains additional generation information about each element. As specialized elements are not contained within the file (unless you already added them manually), but you may want to use the same configuration as within the known “parent class”, we created a tool which generates a new info.xml containing all known elements and the specialized elements at the bottom of the file. The specialized element will have the same role definition as the last known class of the specialized element.

If your specialized element adapts from the basic “note” element, its class may look like this:

- topic/note classGroup/newElement

Therefore, the entry for the new element within the file info.xml will use the same role as defined for the note element.

XSD based schema configurations and redefines

This chapter will provide general information about redefines and how to resolve them.

Xeditor schema configurations

Note: This only affects the DITA 1.2 configuration. As the DITA 1.3 configuration is based on the DTD files, it contains a separate folder for each topic type.

The DITA schema uses redefines in order to define different configurations for different topic types. As Xeditor needs one unique configuration for each element, it is necessary to have one types.js for each different schema definition. Currently there are five different schema definitions resulting in different types in our predefined schema configuration:

  • ditaMap (Dita Maps)
  • learningContent (Learning Content)
  • learningOverview_plan_summary_assessment (Learning overview + Learning plan + Learning summary + Learning assessment)
  • machineryTask (Machinery task)
  • topic_task_generalTask_glossentry_glossGroup_reference_concept (Topic + Task + Gloss entry + Gloss group + Reference + Concept)

Resolve redefines used in XML Schema

The tool which generates the Xeditor configuration based on your schema isn’t able to handle redefines. Therefore, any redefines used in your schema, as for example the standard DITA 1.2 XSDs do, have to be resolved.

Unfortunately, there is no simple way to resolve them. Based on our experience, the best way is going through the following steps:

  1. Identify all redefines used by every possible root element and collect them in a separate file for each root element.

For example: All redefines within the definition of the basic topic element or the basic task. Also the redefines of included XSDs have to be checked.

  1. Compare the collected redefines with each other. There may be some root elements which use the same redefines.

  2. Locate the root elements which use exactly the same redefines. Collect them within a list. Example: A list containing a few root elements which use the same redefines:

Configuration a:

Basic topic

Basic task

Gloss entry

Gloss group

Configuration b:

Machinery task

Configuration c:

Learning Overview

Learning Plan

Learning Summary

Note: The configuration for root elements with the same redefines can be generated within one file. For example the basic topic and basic task use the same redefines and use therefore the same configuration file within Xeditor.

As we have now identified which root elements use the same redefines, and therefore the same configuration, we are now able to resolve them.

  1. In order to resolve the redefine properly, we have to apply its changes on the target element. When the changes are applied, the redefines target file hast to be included

  2. Apply the changes of the redefine on the target element.

  3. Include the XSD file mentioned in the redefine with the include command.

  4. Remove the redefine entry from the XSD file.

  5. Repeat step 5-7 for all redefines within one unique configuration.

You now have removed all redefines and can generate the Xeditor configuration as mentioned in the basic developer guide of Xeditor.

Note: For future changes it is recommended to keep the adjusted XSD files for each configuration.

Note: You have to repeat the steps 4-8 for each unique configuration.

Redefine of the keyword element within task.xsd.

<xs:redefine schemaLocation="urn:oasis:names:tc:dita:xsd:commonElementGrp.xsd:1.2">
<xs:group name="keyword">
<xs:group ref="keyword"/>
<xs:group ref="pr-d-keyword" />
<xs:group ref="ui-d-keyword" />
<xs:group ref="sw-d-keyword" />

Therefore, we have to locate the definition of the keyword element within the file commonElementGrp.xsd. The definition looks like this:

<xs:group name="keyword">
<xs:element ref="keyword"/>

We have to adjust the definition defined by the redefined. So the keyword definition should look like this:

<xs:group name="keyword">
<xs:element ref="keyword"/>
<xs:group ref="pr-d-keyword" />
<xs:group ref="ui-d-keyword" />
<xs:group ref="sw-d-keyword" />

Note: The part of the redefine where the element calls its own group definition (here: group ref=”keyword”) has to be replaced by an element reference. Otherwise the generation will look endlessly.

After that, the redefine has to be changed to a normal include as follows:

<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:commonElementMod.xsd:1.2"/>

DITA Buttons

DITA has several pre-configured buttons that may be used or overridden. All of the buttons can be found in node_modules/@xeditor/schema-dita-core/src/js/config/buttons. For example:

'button:xeditor.dita.conref': {
icon: 'fa-external-link',
tooltip: global_phrases['xeditor.tags.conref'],
listeners: {
scope: editor,
click: function(button, e, eOpts) {
// show insert conref dialog
this.configObj.configData.prepareLookupConref(this, true);

DITA Roles

DITA contains several pre-configured roles that extend the core editor roles. These pre-configured roles can be found in node_modules/@xeditor/schema-dita-core/src/js/config/roles.js. For example:

'roles:xeditor.inline': {
extend: 'roles:xeditor.inline',
cssClass: '',
showChangeMenu: true,
showInChangeMenu: true

DITA Service API

The Service API that describes the DITA services can be found here: DITA Service API.