Getting started

Fonto Connectors is intended for demo-grade integration only. It is not intended for production use. See Integrate with a CMS for alternative integration strategies.

This guide describes the development experience for creating a new Fonto Connectors application.

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 Fonto Connectors may have additional requirements, please see the Server requirements.

Fonto 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 several 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 initialize a new Fonto Connectors application.

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

Other

your-connectors-instance/
├── 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 Fonto Editor to Fonto Connectors.

The configuration of the editor itself is out of scope of this document, please refer to the Fonto Editor Getting started guide.

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

  1. Locate the directory where you have initialized Fonto Connectors.

  2. Paste the contents of the build (dist) directory of your configured Fonto 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

<?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 Fonto Connectors.

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

Step 5

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

Path rewriting

Fonto 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- and post-processing

Fonto Connectors optionally 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 Fonto Connectors. 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 Fonto Connectors which is available at http://localhost:<port>. See Configure Hosting for the default ports. When running in Docker, make sure these ports are exposed to the host system to be able to see the application in the browser.

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

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

Docker outputs the logs of Fonto Connectors to 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 Fonto Connectors containing a Fonto Editor, enabled for your cloud storage or CMS. We have setup a few production deployment guides which you can use to deploy Fonto Connectors. 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!