Getting started

This chapter describes the development experience for creating a new instance of FontoXML Connectors.

Prerequisites

You can develop on your preferred OS, whether it is Linux, macOS or Windows. Before you can get started with development, you just need to install the following software on your local machine:

Please note that hosting and running FontoXML Connectors may have additional requirements, please see the  Server requirements.

FontoXML Connectors is built in .NET Core, however, it does not require you to write any C# code. The configuration is managed through FDT, an XML configuration file and a few environment settings.

Step 1

Create a new connectors project via FDT, specify the version number which you can find in the Release notes:

  • Run fdt connectors init --version <version> in your command line to create a new Connectors instance.

FDT has created a file and folder based structure on your local machine as follows:

  • editor/
  • processing/
    • post/
    • pre/
  • templates/
  • .env
  • documentProcessing.xml

fdt connectors init also creates a .fontoxmlConnectorsManifest file. This file should not be modified, since it is generated by FDT.

Step 2

Add the configured built instance of FontoXML Editor to the Connectors instance.

The configuration of FontoXML Editor itself is out of scope of this document, please refer to the FontoXML Editor Guides to get started.

Please make sure you configure your FontoXML Editor with the FontoXML Connectors integration add-on. See Preparing your FontoXML Editor for details.

  1. Locate the directory where you have initialized your FontoXML Connectors instance.
  2. Paste the contents of the build (dist) directory of your configured instance of FontoXML Editor into the editor/ directory.

Step 3

Set up the document templates.

Document templates are starting points for newly created documents for your authors. You can use any document as a template. Please find an example for a DITA topic template below. For more information on document templates, click here.

Document templates need to have a .template extension and must be placed inside the templates/ directory.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" topic.dtd"> 
<topic>
	<title><?fontoxml-text-placeholder text="Title" ?></title>
	<body>
		<p><?fontoxml-text-placeholder text="Type your content" ?></p>
	</body> 
</topic>

Step 4

Configure the FontoXML Connectors instance.

This configuration includes enabling/disabling the storage connectors and configuring several UI settings. Please follow the configuration guide.

Step 5

Configure the schema experience and pre/post processing for FontoXML Connectors.

Path rewriting

FontoXML Connectors performs reference resolving for images, cross-refs, hyperlinks and reused content. To enable the reference resolving, the application needs to know which elements contain references (e.g. hrefs) and which strategy should be used to resolve those references. For more in-depth guidance on how to configure your application for your schema, please review the document processing guide.

Pre/post processing

FontoXML Connectors is able to perform processing before content is opened in the editor and before it is saved to the underlying storage connector. You can execute any version 1.0 XSLT on your content. For more in-depth guidance, please see the document processing guide.

Step 6

You are now done configuring the FontoXML Connectors instance. Run the fdt connectors run command inside your working directory to get your project up and running. (Make sure your Docker is running and you are logged in with the credentials you received in the prerequisites)

This command builds your image and runs it inside a Docker container. The container is cleaned up after you press Ctrl-C to stop the application.

If you are using CMIS or WebDAV, make sure you log out (upper right in the editor page) or click File > Save & Close before stopping the application. This gracefully releases locks and makes sure you do not end up in a dead-lock scenario.

You can now browse to your Connectors instance which is available at http://localhost:<port>. The port is the one you configured or the default which is 2200.

You may need to accept the self-signed certificate that is generated by FontoXML.

You should now see the sign-in page with the configured connectors.

Docker outputs the logs from FontoXML Connectors in the console window taking the configured minimal log level into account that you have set in your connectors configuration.

Step 7

Deploy to production!

You now have a fully configured FontoXML Connectors instance containing an instance of FontoXML Editor, enabled for your cloud storage or CMS. We have setup a few production deployment guides which you can use to deploy your FontoXML Connectors instance. Please follow the corresponding guides in the production deployment section.

Congratulations! You have completed the Getting Started guide and are now able to create, edit and save documents in the storage connector of your choice!