Skip to content


Use our middleware to do more with less.

Xeditor offers the optional use of a middle ware server called the Blackbox. The Blackbox server is based on Node.js and can be installed on any operation system within your environment and communicates with Xeditor and your backend server. It will handle all the Xeditor core services and only requests necessary information, like XML input, from your server.

If you use it, you do not have to adapt Xeditor's backend services into your own language/system (.NET, Java, PHP, etc.). For example, when loading a file, you do not have to perform the required transformation from XML to HTML. You only have to pass the requested XML to the Blackbox and it will take care of all necessary steps.

How it works:

When starting Xeditor, it will send a request for XML content to the Blackbox server. The Blackbox server will then send a request to your own server. The request will contain all parameters and request headers that have been send to the Blackbox. When you pass the requested XML as a response back to the Blackbox, it will perform all required operations, like the transformation to HTML. The result will be passed back to Xeditor automatically.


  • You do not have to implement Xeditor's core services yourself
  • New features that require backend logic do not need to be adapted to your system. The Blackbox will always support Xeditor core services
  • Your server does not have to be connected to the internet, as it only needs to communicate with the Blackbox
  • Xeditor core services will be maintained by the Xeditor development team

Blackbox requirements

The Blackbox is our middleware and it is optional for your end configuration. However, it is required to run Xeditor pre-built packages.

  1. Install Java RE supporting Java 6 or higher.
  2. Note

    Manually installing xsltproc is only necessary for Linux systems. Windows and Mac will already have this installed.

    Install xsltproc with sudo get-apt install xsltproc.

Blackbox installation

  1. Open your terminal.
  2. Change into the directory of your Xeditor project.
  3. Install @xeditor/blackbox and requirements:

    npm install @xeditor/blackbox --save --registry

Blackbox configuration

Before starting the Blackbox server, you have to configure it properly. The Blackbox requires some information regarding the location of your transformation and validation files, as well as information about the server it will communicate with. Additionally, you can adjust it according to your Xeditor configuration, like which MathML editor should be used (if any).

The Blackbox will be configured using a JavaScript file called xeblackbox.config.js.

When starting the Blackbox server using your command prompt, you can pass a parameter indicating the location of the configuration file by using -c [location]. If no parameter is passed, the Blackbox will assume the configuration file in your home directory.

Example command for starting up the Blackbox:

xeblackbox -c location/to/configuration/xeblackbox.config.js

Along with your demo configuration, you'll receive a demo configuration file for the Blackbox. In this, the Blackbox will be configured for the demo server that simulates your Server. Generally, it should be enough to adjust the host and port of your server along with the locations for your transformation and validation files.


The paths of the location to the validation and transformation files needs to be added to the configuration file. In order to shorten your paths, you may use the following shorthand placeholders:


    The Blackbox will replace the placeholder with the location of the configuration file.


    The Blackbox will replace this placeholder with the location of the Blackbox itself.

General configuration

This chapter describes how to perform the general Blackbox server configuration.

  1. Open the file xeblackbox.config.js.
  2. Note

    The configuration file already contains the configuration for the demo setup. It also contains comments that may help you with adding required information.

    Fill in required information.

Your general configuration may look like this:

general: {
    // Port the black box server runs on
    host: process.env.XEDITOR_BLACKBOX_HOST || packageConfig.config.BLACKBOX_HOST,

    // Port the black box server runs on
    port: process.env.XEDITOR_BLACKBOX_PORT  || packageConfig.config.BLACKBOX_PORT,

    // Configuration for customer server that the black box server will send requests to
    // (i. e. request for XML to be loaded in Xeditor)
    server: {
        host: process.env.XEDITOR_SERVER_HOST || packageConfig.config.SERVER_HOST,
        port: process.env.XEDITOR_SERVER_PORT || packageConfig.config.SERVER_PORT

    // Flag inditacting whether document should be validated when loading. If set to true, Raw XML editor
    // will open if document was invalid.
    validateOnLoad: true,

    // if you applications uses wepPath prefixes, such as
    // you can configure this here. If you application doesn't use any, you can remove this config
    // webPath: 'xeditor',

    // Flag to enable/disable compression of the blackbox. Will use 'deflate' or 'gzip' for compression.
    compression: true,

    // can be 'xformula' or an Object containing WIRIS configuration
    // mathml: {
    //  host: '',
    //  path: '/wiris/app/'
    // },
    mathml: 'xformula',

    // Flag indicating whether SVG is used (adds additional preparations to load action)
    svg: true,

    // Configuration for spell checker
    spellchecker: {
        host: '',
        username: 'xeditor',
        password: 'xeditor8spellchecker'

Schema configuration

As the Blackbox server will perform your transformation and validation operations, it requires information regarding the locations of the files it should use. It also supports the use of multiple different schemas. This chapter describes how to perform the schema specific configuration of the Blackbox server.

  1. Open the file xeblackbox.config.js.
  2. Locate the schema object within the configuration file.
  3. Create a new object for each schema you want to configure.
  4. Enter the file property and map object for each schema. The file property contains the location to the main schema file which will be used as the start point for the validation. The map object resolves the locations for all referenced schema files.
  5. Add the transformation object to each schema. The transformation object contains resolves the locations of the transformation files that should be used for this schema.
  6. optional: Add the default property to the schema object. Its value will determine the schema the Blackbox will use if no schema parameter was passed.

Your schema configuration may look like this:

schema: {
    default: 'demo', 
    demo: { 
        file: '#CONFIGPATH#/WEB-INF/xsd/content.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" 

Blackbox Protocol

The Blackbox supports HTTP and HTTPS protocol. HTTP protocol is used as default, as HTTPS requires proper certificates. To switch to HTTPS, set the protocol setting to 'HTTPS' in the configuration and set the paths to the certificate and key data (optionally, the ca file path can also be set). If necessary, the URLs in the Xeditor configuration (e.g. urls.js, plugins.js) have to be adapted to send the requests to the HTTPS server.

    // set protocol to HTTPS
    protocol: 'HTTPS',

    // set private key
    key: '/path/to/privatekey.key',

    // set certificate
    cert: '/path/to/certificate.crt'

Requests to the server can also be changed to HTTPS. To do this, set the server.protocol setting to 'HTTPS'.

Blackbox API

The Blackbox Service API describes the service requests the Blackbox will send to your server and the response and it format it is expecting. Please refer to the following link for further information: Blackbox Service API