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:no
or @xsi:schema
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:no
orNamespace Schema Location @xsi:schema
value found on the root element of the file(s) you'll want to open with FontoXML.Location -
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 root
property should contain multiple keys. Remember that the package
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.
-
Run
fdt editor init
in the editor instance folder. -
Input a name for your instance.
-
Input the path to your schema source folder. For example
schema
or/some/path/to/your/xsd/schema/files
. -
Optionally enter the filename to a favicon file.
-
Optionally select addons.
-
select the fontoxml-dita add-on if you want to create an instance of FontoXML for DITA documents.
-
You do not need to select any (additional) add-ons, these can be added at a later point in time if you need any.
-
-
Select
Create
and press enter.Fonto XM L Editor instance
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 I
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 I
), 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 <element
.
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 configure
.
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:
-
fully configuring the schema experience,
-
integrate Fonto into your CMS, if you are using a CMS,
-
setting up clipboard integration using the Define copy & paste behaviour guide,
-
enabling more add-ons,
-
using modals to enable more intricate insert and edit flows and
-
creating popovers to help authors with writing their content.
You can use our FontoXML Development Tools to assist you with tasks such as getting information about your schema or elements therein.