Creating a base editor

This guide is a step by step guide to create a new Fonto editor for an XSD schema. After completing this guide you will have the minimal configuration required for your schema. You can then follow other guides for additional and more advanced configuration.

What you'll need

Step 1: Create the schema bundle

This step prepares the XSD files for a schema for Fonto's schema compiler. The schema compiler is used once, or when the XSD's are updated, to compile a web-optimized version of the schema into your editor. This enabled the editor to perform real-time, client side validation.

  • Download your schema files into a new directory. To download the example schema from GitHub, run:

    Terminal
    git clone https://github.com/FontoXML/training-schema-bundle.git --depth 1
  • Create a new file called fonto.json in the root folder of your schema. In this tutorial, the location for this file is training-schema-bundle/fonto.json. The contents of this file initially looks like this:

    training-schema-bundle/fonto.json
    {
        "rootSchemas": {}
    }
  • Add new properties to rootSchemas for every entry XSD your schema has, where the key is a relative file reference. In the case of the training schema bundle, this is only the recipe.xsd file. If your XSD modules import or include other XSD modules, that will be handled automatically. Your fonto.json becomes:

    training-schema-bundle/fonto.json
    {
        "rootSchemas": {
            "xsd/recipe.xsd": {}
        }
    }
  • Fill out the packageName and locations properties for every rootSchema. The package name affects the code structure generated by the schema compiler, so pick a descriptive name that does not contain special characters. The locations strings are used to match a given XML document with the schema. In the case of the training schema we can find what is already used from the XML files in training-schema-bundle/test/. The fonto.json file becomes:

    training-schema-bundle/fonto.json
    {
        "rootSchemas": {
            "xsd/recipe.xsd": {
                "packageName": "recipe-sx-shell",
                "locations": ["urn:fontoxml:training:delicious:recipe.xsd"]
            }
        }
    }

By now the minimal folder structure should look like this:

Folder structure
Training/
  training-schema-bundle/
    fonto.json
    xsd/
      recipe.xsd

Step 2: Initialise a new editor for your schema bundle

This step uses Fonto's development tools to generate code for your schema bundle. This is a one-time step.

  • Create a new directory alongside your schema bundle, for example "training-editor", and navigate to it in your terminal.
  • Run the following command, make sure to provide a valid version number:

    Terminal
    fdt editor init --version <version> --schema ../training-schema-bundle

    You can use the --help flag on any FDT command. It will then show you which options and parameters are expected.

FDT will prompt you for several other properties, which are all optional. When prompted for add-ons it is useful to select the "XML Source View [fontoxml-xml-view]" option. It allows us to see the document XML better. Do not select any other add-ons, as some of them require additional configuration in order to work. You can always install more add-ons later.

After the fdt editor init command finishes, your folder structure should look like this:

Folder structure
Training/
  training-schema-bundle/
    ...
  training-editor/
    config/
    dev-cms/
      files/
    packages/
      editor-clipboard-configuration/
      editor-masthead/
      recipe-sx-module/
      recipe-sx-shell/
    platform/
      ...
    config.js
    manifest.json
    messages-template.json

Step 3: Configure a test document

This step lets Fonto's development environment know which document(s) should be used for testing during development. It has to be a schema valid document, and you may have multiple. In the example schema bundle for this guide the example XML files are included in training-schema-bundle/test/.

  • Create a dev-cms/files/ directory in your editor code, and copy the test XML files there

    Terminal
    cp training-schema-bundle/test/*.xml training-editor/dev-cms/files
  • Open the config.js file in your editor, training-editor/config.js, and replace the "INSERT_FALLBACK_DOCUMENT.xml" string with the files(s) you want to use for tests. For the example schema, your config.js becomes:

    training-editor/config.json
    'use strict';
    
    module.exports = () => {
        return {
            scope: {
                documentIds: ['fried-guinea-pig.xml', 'mushroom-lunch.xml']
            }
        };
    };

Your folder structure should now look approximately like so:

Folder structure
Training/
  training-schema-bundle/
    ...
  training-editor/
	dev-cms/
      files/
        fried-guinea-pig.xml
        mushroom-lunch.xml
    ...

Step 4: Start your development server

The purpose of Fonto's development server is to allow you to configure Fonto without needing a full CMS integration in place. The training-schema-bundle/ folder is no longer required. The rest of this guide, and other guides, will focus on training-editor/.

  • Run the following commands:

    Terminal
    cd training-editor
    fdt editor run
  • Open http://localhost:8080 in your browser.

Congratulations on building your first basic Fonto editor.

That's it, you now have a basic Fonto instance up and running!

Of course it still looks a little empty. The documents are actually being loaded, but the visualization for all elements has yet to be configured with a CVK configuration variant other than the invisible one used in the generated code.

This is a good time to configure it further using one of the quick starts or advanced guides listed below, or by following the // TODO comments in the generated code, as stated at the end by the fdt editor init command.

Quickstarts

Advanced guides


Was this page helpful?