Getting started

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 .
  • Run the following command:

    Terminal
    fdt editor init --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 addons 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 addons, as some of them require additional configuration in order to work. You can always install more addons later.
After the fdt editor init command finishes, your folder structure should look like this:
Folder structure
Training/
  training-schema-bundle/
    …
  training-editor/
    config/
    packages/
      recipe-sx-shell/
    platform/
    manifest.json
    config.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
    mkdir training-editor/dev-cms
    mkdir training-editor/dev-cms/files
    cp training-schema-bundle/test/*.xml training-editor/dev-cms/files
  • Open the config.json file in your editor, training-editor/config.json, and replace the "INSERT_FALLBACK_DOCUMENT.xml" string with the files(s) you want to use for tests. For the example schema, your config.json becomes:

    training-editor/config.json
    {
      "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.

The editor should look like this:

Step 5: Create a package for the element configuration

This step provides a fallback configuration for unconfigured elements, and solves the "Something went wrong" error that is currently being displayed.

  • Create a new package folder: training-editor/packages/recipe-sx-module/
  • Create a new file src/configureSxModule.js, and copy the following code into it:
training-editor/packages/recipe-sx-module/src/configureSxModule.js
import configureAsRemoved from 'fontoxml-families/src/configureAsRemoved.js';

export default function configureSxModule (sxModule) { 
    // Configure all elements to be hidden
    configureAsRemoved(sxModule, 'self::element()');
}

Having a fallback configuration in place is useful because it allows you to incrementally add support for more elements, without being blocked by an error message. It is recommended to remove the fallback configuration prior to releasing to production, or to configureAsRemoved all missing elements individually.

  • Change packages/recipe-sx-shell/fonto-manifest.js to include a reference to your element configuration package. This creates a dependency, and activates the package containing your element configuration.
training-editor/packages/recipe-sx-shell/fonto-manifest.json
{
    "dependencies": {
        "recipe-sx-module": "packages/recipe-sx-module"
    }
}
  • Reload Fonto in your browser. There should be no more errors shown in the editor.

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. This is a good time to configure it further:


Basic Guides

Advanced Guides