This chapter will guide you through the process of preparing everything you need to get Xeditor up and running using your custom schema.

After you performed all required steps your schema will be ready to be used by Xeditor. We will then proceed with a basic guide on how to get Xeditor up and running, as well as being able to open, edit, and save your documents.

Start with a clean package

You can build Xeditor from scratch by downloading the clean package. Following the instructions to install Xeditor but get @xeditor/xeditor instead of @xeditor/xeditor-demo. This version will not contain any plugins or configurations, but it will contain all required files, as well as some pointers on what has to be done.

Schema configuration

This chapter describes how to configure your own schema according to Xeditor.

If you are using DTD you need to transform it first to XSD. For an instruction on how to achieve this please have a look at this chapter.

Efficient Xeditor configuration

In order to prevent unnecessary changes on the generated Xeditor configuration, you can also add additional information to elements. This information will be used in the generation process and will be included in the generated result.

Generate info XML file

This process uses pregenerate_info.xsl to automatically generate the info.xml file needed to assign roles. This process is optional, but recommended in order to avoid manually creating each element in info.xml.

1. Download the Xeditor generation tool xetypesgen: >npm pack @xeditor/tool-xetypesgen --registry https://npm.xeditor.com:4873 (for more information also read here).
2. Decompress downloaded package.
3. Run the XSL using Saxon.

java -jar pathToSaxon/saxon9he.jar step1_empty.xml help/pregenerate_info.xsl > output/info.xml

The info.xml file will be created in /output/.

Assign Roles

Every element in a schema must be assigned a role, which defines properties and governs behavior for that element in Xeditor. When generating a new schema configuration, the roles are defined in the info.xml file.

Xeditor comes with predefined roles. Custom roles can be created in src/js/config/roles.js. You can find some additional information on Xeditor roles here.

In addition to the XSD schema, the elements from different roles have to be assigned. The role assignment takes place in an XML file. This step is however optional. The schema can also be generated without the file info.xml. In This case, the roles need to be added later in the generated schema.

1. Create new XML file.
2. Name the file info.xml.
3. Note: All elements must be assigned a role. Place all elements in your schema and assign corresponding roles.

<xedin:elements xmlns:xedin="http://xpublisher.com/xeditor/config/info">
    <xedin:element name="content" role="xeditor.masterContainer"/>
    <xedin:element name="heading" role="xeditor.container"/>
    <xedin:element name="p" role="xeditor.container"/>
</xedin:elements>

Roles and attributes

In addition to the roles also attributes can be assigned in the file info.xml.

In the following example an emptyText attribute is used. It defines a placeholder text, to which you can assign content in the file phrases.js. This text is then displayed in Xeditor instead of an empty element.

This function can be used to specify which content needs to be added in the corresponding element.

Example of info.xml with @attribute definition:

<xedin:elements xmlns:xedin="http://xpublisher.com/xeditor/config/info">
    <xedin:element name="content" role="xeditor.masterContainer"/>
    <xedin:element name="heading" role="xeditor.container" emptyText="global_phrases['xeditor.tags.heading']"/>
    <xedin:element name="p" role="xeditor.container"/>
</xedin:elements>

For further examples of configuration options you may see the sample file that was used to generate the demo.

Generate Xeditor configuration

Now that we prepared your schema and created the info.xml file containing the role information, it's time to generate the actual Xeditor schema configuration.

We generate the Xeditor schema configuration using the same tool we used in the previous steps to generate the info.xml file.

1. Move your previously prepared info.xml file to the /input folder of our generation tool
2. Execute the script generate.sh or the corresponding one generate.bat for Windows Systems

The tool will generate the Xeditor configuration file result.js into the /output folder of the generation tool.

Congratulations! We just created all required files and information Xeditor needs in order to be able to read, edit, and save your documents! Now we will proceed with a proper Xeditor setup, so you can actually start using Xeditor.

Further preliminaries and configurations

Now that we've prepared everything that Xeditor needs, it's time to set everything up and start actually using Xeditor with our documents. Since we are working with the previously downloaded Xeditor package, you might want to refresh your knowledge about our folder structure.

Adding required files to Xeditor

1. Copy the whole content of the previously generated file result.js into the file /src/js/config/types.js of your Xeditor project.
2. Move all your schema files (XSD or DTD) into /WEB-INF/xsd/

Blackbox configuration

In order to enable our middleware server to perform required transformation and validation steps, it needs to be configured for your schema. You can find additional information about our middleware server and its basic concepts here.

The configuration of the middleware server is done within the JavaScript file xeblackbox.config.js of your Xeditor project.

The most important part is the schema object within this file. Within this object the definition of the schema to be used for validation, as well as the location of the transformation files is configured. In order to configure it for your schema, proceed as follows:

1. Add the name of your schema within the schema object
2. Define the root schema to be used
3. Add additional schema files that might be referred within the root schema to the map object
4. Add transformation files

A complete schema definition should look like this:

'customSchema@0.0': {
    file: '#CONFIGPATH#/WEB-INF/xsd/customSchema.xsd',
    map: {
        'mathml/mathml3.xsd': '#CONFIGPATH#/WEB-INF/xsd/mathml/mathml3.xsd',
        'mathml3-common.xsd': '#CONFIGPATH#/WEB-INF/xsd/mathml/mathml3-common.xsd',
        'mathml3-content.xsd': '#CONFIGPATH#/WEB-INF/xsd/mathml/mathml3-content.xsd',
        'mathml3-presentation.xsd': '#CONFIGPATH#/WEB-INF/xsd/mathml/mathml3-presentation.xsd',
        'mathml3-strict-content.xsd': '#CONFIGPATH#/WEB-INF/xsd/mathml/mathml3-strict-content.xsd'
    },

    transformation: {
        contenttoeditor: "#CONFIGPATH#/WEB-INF/xsl/contenttoeditor.xsl",
        editortocontent: "#CONFIGPATH#/WEB-INF/xsl/editortocontent.xsl",
        pastetoeditorfirst: "#CONFIGPATH#/WEB-INF/xsl/pastetoeditorfirst.xsl",
        pastetoeditorsecond: "#CONFIGPATH#/WEB-INF/xsl/pastetoeditorsecond.xsl"
    }
}

Basic Xeditor configuration

Xeditor offers a lot of configuration options, meaning it can easily be adjusted to your needs. However, for now we will simply start with a basic configuration covering most basic options. We prepared a guide on how to configure Xeditor.