Getting up and running

This step by step guide is aimed at getting an instance of FontoXML up and running in the least amount of time possible.

  • Your schema XSD file(s).

  • A text editor which doesn't add any markup to your documents such as Notepad for Windows. Mac OSX users should be careful with editors which will automatically replace " with “ or ” as this will cause errors throughout the process.

Step 1 (Optional)

This step is optional. If your schema only consists of a single xsd file, the catalog is not required.

Create a new file called catalog.xml in the same folder as your XSD file(s).

Create a folder for your editor instance, and create a folder named schema in the editor instance folder.

Fill the file with the following:

XML

<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
	<uri name="[your_schema_name]" uri="[your_xsd_name].xsd"/>
</catalog>

Replace [your_xsd_name] with the name of your XSD file.

Replace [your_schema_name] with the identifier that you want to use in your schema. If you already have XML, it might already refer to this name with the @xsi:noNamespaceSchemaLocation or @xsi:schemaLocation attribute found on the root element of the file(s).

The name and uri attributes in the catalog.xml are case-sensitive.

If you have multiple XSD files repeat the <uri> elements for those files.

If your XSD files are in separate folders set the @uri attribute to the full relative path to the XSD files. If the schema uses multiple XSD files in the same folder, you can use the <group> element for grouping. For example if your XSD file is in a folder named 'shells':

XML

<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
	<group xml:base="shells/">
		<uri name="[your_schema_name]" uri="[your_xsd_name].xsd"/>
	</group>
</catalog>

Step 2

Create a new file called fonto.json in the same folder as your XSD file(s) and the catalog.xml file.

Fill the file with the following, and replace the markers with the location of the XSD file and the name you chose in the previous step:

fonto.json

JavaScript

{
	"rootSchemas": {
		"[your_xsd_name].xsd": {
			"packageName": "[company_name]-sx-shell",
			"locations": ["[your_schema_name]"]
		}
	}
}

This file has a number of fields:

  • rootSchemas specifies the used root XSD files by location within the schema bundle.

  • packageName specifies the name of the schema package that is generated for the XSD file.

    • package names have to be unique because they are the names of the folders inside the "packages" folder on disk

  • locations specifies the schema names used in the generated schema package.

This example can be adapted for your situation by filling in the placeholders in the previous example:

  • Replace [your_xsd_name] with the name of your XSD file.

  • Replace [company_name] with the name of the company you are creating this instance for.

  • Replace [your_schema_name] with the @xsi:noNamespaceSchemaLocation or @xsi:schemaLocation value found on the root element of the file(s) you'll want to open with FontoXML.

  • Repeat for every XSD file you have.

filenames and locations in the schema bundle are case-sensitive.

If your (root) XSD file is in a folder add the folder name to the [your_xsd_name]. For example if your XSD file is in a folder named 'shells':

JavaScript

{
	"rootSchemas": {
		"shells/[your_xsd_name].xsd": {
			"packageName": "[company_name]-sx-shell",
			"locations": ["[your_schema_name]"]
		}
	}
}

If you use multiple schemas, the rootSchemas property should contain multiple keys. Remember that the packageName property must be unique, like this:

Other

{
    "rootSchemas": {
        "shells/maps.xsd": {
        "packageName": "sandbox-dita-sx-shells-maps",
            "locations": [
                   "urn:fontoxml:sandbox:names:dita:xsd:maps.xsd"
            ]
        },
        "shells/topics.xsd": {
            "packageName": "sandbox-dita-sx-shells-topics",
            "locations": [
                "urn:fontoxml:sandbox:names:dita:xsd:topics.xsd"
            ]
        }
    }
}

Step 3

Install or update the FontoXML development tools and it's requirements, and make sure you have placed a valid Fonto (developer) license on your system.

Step 4

Open a command prompt in the editor instance folder. Create this folder if you did not already do so in step 1.

  1. Run fdt editor init in the editor instance folder.

  2. Input a name for your instance.

  3. Input the path to your schema source folder. For example schema or /some/path/to/your/xsd/schema/files.

  4. Optionally enter the filename to a favicon file.

  5. Optionally select addons.

    1. select the fontoxml-dita add-on if you want to create an instance of FontoXML for DITA documents.

    2. You do not need to select any (additional) add-ons, these can be added at a later point in time if you need any.

  6. Select Create FontoXML Editor instance and press enter.

This will place all the needed files in the current editor instance folder. If you want to upgrade this instance in the future, you can use the fdt editor upgrade command, and if you want to update your schema you can use the fdt editor schema compile command.

Compiling your schema

Whenever your schema is updated, for example when new elements are added or existing elements are modified, you can use the fdt editor schema compile command to generate new schema packages.

Step 5

Start your local development server by executing the fdt editor run command in the editor instance folder using your command-line/terminal to start your server process. For additional help for this command, you can use fdt editor run --help.

Step 6

Open your browser and go to http://localhost:8080 to start the editor. Open the developer tools of your browser by using the F12 key on your keyboard.

Keep this open at all times when configuring and developing your instance of FontoXML.

Step 7

You're probably seeing the "Something went wrong" error page of FontoXML, as there is no document to load and no configuration specified.

Place the document you want this instance to load by default in the dev-cms/files/ folder.Open the config.json file in the root folder of your instance and replace INSERT_FALLBACK_DOCUMENT.xml with the name of your document.

Step 8

Restart your local development server by restarting the fdt editor run process. The changes made to config.json are now active. Only files relating to the development CMS packaged with the SDK require your server to restart. You never have to restart your server for changing just front-end files.

Step 9

Open your browser and go to localhost:8080 again. If you simply reload the previously loaded page (for INSERT_FALLBACK_DOCUMENT.xml), you will get the same error as before.

FontoXML will now show a modal stating something went wrong. If we take a look at the developer tools there will be an error in the console stating: Template not defined for node "recipe" in mode: default <element name>. This error notifies you that no configuration has been done for <elementName>.

Step 10

Create a new folder in the packages/ folder that will contain your configuration and give it an appropriate name. Your new package should also contain a src/ directory, which is where almost all of your code will go.

Step 11

In the src/ folder create a new file called configureSxModule.js.

Fill the file with the following:

JavaScript

define([
	'fontoxml-families/configureAsRemoved'
], function (
	configureAsRemoved
	) {
	'use strict';

	return function configureSxModule (sxModule) {
		configureAsRemoved(sxModule, 'self::element()');
	};
});

This code tells FontoXML to consider all elements, done by the 'self::element()' selection, as removed.

Step 12

Reference the newly created package folder from the fonto-manifest.json file found in the *-shells-sx folder that was already present in the packages folder to ensure the newly created configuration gets loaded by FontoXML.

Fill the file with the following:

JavaScript

{
	"dependencies": {
		"[package_name]": "packages/[package_name]"
	}
}

Replace both occurances of [package_name] with the name of the package containing your newly created configuration.

Step 13

Reload FontoXML in your browser. There should be no more errors in the console of the developer tools, but Fonto will not (yet) show any content because you've configured all elements to be hidden in Step 14.

Step 14

Use the Configure the schema experience guide to configure FontoXML to display your content. Add this code to your latest package, or create new packages, as you see fit. If you have a large schema, it is likely that the interdependencies between XSD files will be more or less reflected in the dependencies between Fonto packages.

Step 15

Use the create an operation guide to configure a number of operations.

Step 16

Use the Create a masthead guide to create the toolbar for your application.

Step 17

That's it, you now have a basic FontoXML instance up and running! Of course, this is not everything as you'll still want to make Fonto as good as it can get by:

You can use our FontoXML Development Tools to assist you with tasks such as getting information about your schema or elements therein.