1. Introduction

FirstSpirit provides its own template-based navigation function for statically generated pages. In the modern headless world, a different solution is needed, one that seamlessly integrates a dynamic mapping between a navigation route and the corresponding content behind it.

The Navigation Service module provides a mechanism to transfer the structure of the FirstSpirit site store of a project into a JSON format and make it available via the Navigation Service endpoint. According to the documentation of the Navigation Service endpoint the structure can then be queried via its REST interface.

1.1. Architecture

The functionalities of the Navigation Service are realized by the interaction of different components (see figure Architecture).

These components are as follows:

  • Navigation Service

  • Navigation Service module

Figure 1. Architecture

The interaction of the components always follows the following scheme:

  • The creation and updating of navigation-relevant content takes place at FirstSpirit. Changes are made available to the Navigation Service endpoint (see REST API) in the context of an update. For this purpose, the FirstSpirit server creates a connection to it and transmits all relevant data.

  • The Navigation Service receives this data and updates its internal data model based on the information provided.

  • The customer’s application requests the stored information as needed from Navigation Service endpoint, which provides a REST API for this purpose. The querying of the data is performed according to the pull principle.

The communication between the FirstSpirit server and the Navigation Service is done by HTTPS.

2. Components

Using the Navigation Service in an existing FirstSpirit project infrastructure requires two additional components

When the Navigation Service module has been installed, a FirstSpirit service named Navigation Client Service and a project component named Navigation Project Configuration are provided to the FirstSpirit server.

Navigation Client Service

Upon installation of the Navigation Service module, the Navigation Client Service is added to the FirstSpirit server and is then started. For a transfer to the Navigation Service endpoint the project component must be added to the respective project. The Navigation Client Service then takes care of creating the navigations of the FirstSpirit projects.

Only when the Navigation Client Service is running will changes be transmitted to the Navigation Service .

Navigation Project Configuration

By adding/removing the project component Navigation Project Configuration to a FirstSpirit project, it is regulated whether navigations are created for this project. It has its own configuration, which is described in the chapter Configuration of the Navigation Service project component.

3. Configuration

The setup of the Navigation Service for operation on a server is done by configuring the project component: Navigation Project Configuration.

The following subchapters describe the required configuration steps.

3.1. Configuration of the Navigation Service project component

With the usage of the Navigation Service module the project component Navigation Project Configuration becomes available to the FirstSpirit server.

The addition of the Navigation Project Configuration to a FirstSpirit project triggers an initial creation of its navigation structure.

Removing the Navigation Project Configuration will delete the created navigations in the Navigation Service.

To add the project component, open the ServerManager and select the Project settings  project component area.

A list of all existing project component is displayed in the main panel. After clicking Add, select the {component name} and confirm the selection with OK.

projectcomponents add
Figure 2. Adding the project component: Navigation Project Configuration

This project component will be added to the list in the content area and must be configured afterwards (see figure Adding the project component: Navigation Project Configuration).

Select the entry in the list and open the corresponding configuration dialog via Configure.

Fill in the fields as described below.