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

architecture
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.

projectcomponents config
Figure 3. Navigation Service Configuration
CaaS 3.x mode

This mode is available in case the FirstSpirit server has the Content as a Service module installed in a version equal or greater than 3. If the CaaS 3.x mode is activated, the corresponding CaaS routes are used in the navigation as the reference to the data. Additionally, the Advanced URLs UrlFactory is used for the SEO routes.

Content Reference URL Prefix

A optional prefix can be entered in this field. The value will be prepended to the generated ContentReference URL of each FirstSpirit page reference.

Content Reference URL Factory

In this field the URL Factory which is responsible for the path generation of the referenced content can be selected. This selection field is disabled once CaaS 3.x mode has been enabled.

SEO Route Url Factory

In this field the URL Factory which is responsible for the SEO routes can be selected. This selection field is disabled once CaaS 3.x mode has been enabled.

Navigation URL (release and preview state)

These listed navigation URLs indicate the locations to which the navigations created for the project are transmitted. These are endpoints for the front-end developers, provided by e-Spirit.

Available in languages

This is a list of all languages of the current FirstSpirit project, for each of which a navigation is provided.

Ignore errors

This mode is not recommended and per default deactivated in all projects. If it is enabled, errors will be ignored when generating the navigation. Instead, null values will be written to the affected locations. You will therefore lose the certainty that data in the Navigation Service is always correct.

4. Usage

The Navigation Service module makes it possible to query the structure of the FirstSpirit site store of a FirstSpirit project via the Navigation Service endpoint.

The following sections describe how such a navigation is created and how to optionally enrich it with additional information.

4.1. Creation of the navigation

The navigations for the preview and release state are updated each time a page reference, structure folder or root node of the site structure has been changed or released. Additionally, an update of the navigation is triggered by changes to pages, if the page is referenced by at least a single page reference.

When changes are made to the global URL settings of the project, both the preview and the release state are updated.

Navigations are created for each language of the project as well as for each release status.

Navigations that correspond to a language that is not part of the project are deleted daily as part of a change-triggered update.

4.1.1. Resilience

Occasionally, FirstSpirit projects may contain errors. Nevertheless, it is desired that a maximally complete navigation is generated and transmitted to the Navigation Service despite isolated errors.

To ensure this, PageRefs for which a navigation node cannot be generated are ignored and not included in the resulting navigation.

PageRefFolders are always included in the navigation even if the data is (partially) incorrect, to prevent the loss of potentially valid underlying elements.

4.1.2. Scheduled Tasks

It is also possible to trigger the generation of the navigation by a FirstSpirit scheduled task. When installing the project app, two jobs are added to the project for this purpose: Navigation Live Generation and Navigation Preview Generation. These consist of two tasks each, which transmit the current navigations in all languages to the Navigation Service and delete existing navigations for which there is no corresponding language in the project.

The NavigationInspectionExecutable can be used to calculate the navigation tree for a specified element at generation time. It expects the following parameters:

Name Type Description

element

en.espirit.firstspirit.access.store.IDprovider

The FirstSpirit element (page reference, structure folder or root node of the structure store element) for which the navigation should be calculated.

language

en.espirit.firstspirit.access.Language

The FirstSpirit language object for which the navigation should be calculated.

key (optional)

String

The attribute to be returned as a result object. If not set, the entire navigation element is returned.

The return value is a JSON object. The method .toString() provides the serialized JSON of the object. If the key parameter is set and the specified attribute has a primitive type, a String is always returned directly.

4.2. Custom Data

If the navigation data in the generated standard format is not sufficient, it is possible to add further information to the navigation. The Navigation Service Module provides the so-called Custom Data Script for this purpose. It allows users to transfer self-defined content to the Navigation Service endpoint.

One use case for this is, for example, a page description, which is required in addition to the navigation information for the presentation.

The following chapter describes the setup of exactly this particular use case.

4.2.1. Setting up a Custom Data Script

Open the SiteArchitect and add a script to your project with the following reference name: navigation_service_custom_data.

Within the script it is necessary to write the code into the first output channel.

Example implementation of a Custom Data Script
import de.espirit.firstspirit.access.store.pagestore.Page;
import de.espirit.firstspirit.access.store.sitestore.PageRef;

if (e instanceof PageRef) {
    page = e.getPage();
    formData = page.getFormData();
    pageDescription = formData.get(language, "pt_pageDescription").get();
    customData.put("pageDescription", pageDescription);
}

The CustomData Script is evaluated directly after the creation with each following change at the FirstSpirit project as well the release.

The resulting JSON of an exemplary FirstSpirit page reference
{
    "id": "815c307c-2ca6-4f02-9653-fa3454988fc2",
    "label": "Products",
    "seoRoute": "/Products/Products.html",
    "seoRouteRegex": null,
    "contentReference": "/examplePrefix/Products/Products.html",
    "customData": {
        "pageDescription": "Our Offers"
    },
    "_links": {
        "self": {
            "href": "https://navigation-example.e-spirit.live/navigation/preview.7c5c1555-c706-45a7-8371-ccddbb4ba8be/node/815c307c-2ca6-4f02-9653-fa3454988fc2?depth=10&language=de_DE"
        },
        "path": {
            "href": "https://navigation-example.e-spirit.live/navigation/preview.7c5c1555-c706-45a7-8371-ccddbb4ba8be/node/815c307c-2ca6-4f02-9653-fa3454988fc2/path?depth=10&language=de_DE"
        },
        "seoRoute": {
            "href": "https://navigation-example.e-spirit.live/navigation/preview.7c5c1555-c706-45a7-8371-ccddbb4ba8be/by-seo-route/Products/Products.html?depth=10&language=de_DE"
        }
    },
    "visible": false,
    "children": null,
    "hasChildren": false
}

You can find all information on the use and format of the generated navigation structure in the corresponding Navigation Service endpoint documentation.

In addition to the already mentioned IDProvider, other fields are available to the script within the execution context:

Name Type Description

e

de.espirit.firstspirit.access.store.IDProvider

The current FirstSpirit element (page reference, structure folder or root node of the structure store element).

context

de.espirit.firstspirit.access.BaseContext

Instance of an FirstSpirit-SpecialistBroker.

language

de.espirit.firstspirit.access.Language

The FirstSpirit language object at runtime

customData

Map<String, Object>

Entries in this map are written to the custom data and then provided by the Navigation Service endpoint.

Please note that the maximum size of the customData map is limited to five entries.

The values must be equivalent to JSON primitives (e.g. String, Number or Boolean).

If you have a use case that cannot be covered by the above-mentioned fields, please contact e-Spirit Support.

4.3. Content projections

In the case of a content projection for detailed views the related navigation nodes contain an attribute that can be used to resolve dynamic routes. A content projection is regarded as a projection for detail views if the following attributes are configured in the Content tab of a page reference:

The *Number of entries per page value is greater than 0 (e.g. 1) The *Maximum number of pages value is not 1 (e.g. 0)