<
Module development in the Cloud, 2024.5
Module development in the Cloud, 2024.5
Documentation

Module Documentation

This document guides you through the module development process within the FirstSpirit Cloud. You will find the general process explained briefly. Links will lead you to the detailed documentation to address specific steps of the journey.

Target audience: (new) module developers in the FirstSpirit Cloud setting

Preconditions: DTA (Developer Training Advanced)
Training & Coaching Center

Your FirstSpirit Cloud environment

By default, your FirstSpirit Cloud instance includes three environments: Dev, QA and Prod:

Development (Dev)
This environment is where one or more developers can work without posing any risk to each other or the production code.

Quality Assurance (QA)
This environment is the staging or testing area where you can test developed segments to ensure quality before they’re transferred to the Production Environment. Therefore this is a nearly exact replica of the production environment.

Production (Prod)
This environment contains all deployed/published projects that may already hold content and are available for your customers.

  • All three stages contain nearly the same projects.
  • Template and setting changes are regularly moved to the next stage to avoid divergent development states.
  • While Dev and QA typically contain test content, Prod contains all of the live project content.

Supporting tools for module development

Development tool Used in Crownpeak Cloud development

Programming Language

Java 17

Version Control

Git

Branching Model

Git flow

Source Code Repository

Bitbucket

CI/CD

Bamboo

Build Automation Tool

Gradle

Artifact Repository

Artifactory

Extending FirstSpirit

FirstSpirit provides multiple extensibility opportunities that allow developers to implement customized server-side as well as client-side functionality. The FirstSpirit API's various extension points can be used by different so-called component types.

Components are packaged in and distributed as FirstSpirit modules which are in essence ZIP files with an .fsm extension containing all resources and dependencies as well as a module descriptor in XML format. Module Definition

Note: All cloud servers use the isolated mode. Some central aspects are described here: Module development "Isolated"

Extending the FirstSpirit ContentCreator

As part of the ContentCreator's user-centered design, Crownpeak provides project developers with means to design custom functionality that presents additional interaction features that will help editors perform specific tasks. ContentCreator Extensions

All of these plug-in types are connected to different areas in the ContentCreator user interface and is able to handle FirstSpirit data as well as poll input from users:

Use cases for ContentCreator modules Support

1. InlineEdit Items
Insert one or more actions into the button overlay that appears as the mouse pointer hovers over a section, page contents or datasets rendered in the preview pane.

InlineEdit Buttons

2. Template Buttons (FS_BUTTON)
Provide access to scripts and Java classes that implement extra functionality. These buttons are placed directly in page, section or dataset templates, may handle click and drag-and-drop interactions, and can be rendered in forms, preview/generated representations of elements or both.

Template Buttons

3. Toolbar Menu Items
Specify one or more menu items which will be shown in the Actions menu of the ContentCreator toolbar.

Toolbar Menu Items

4. Reports (Data Access)
Integrate external data sources (e.g. web services) with FirstSpirit so that data from these sources (e.g. images, Youtube videos,...) may be referenced within FirstSpirit content.

Data Access

5. Element Status and Workflow Grouping
Specify a project-wide algorithm to determine the page status (whether it is considered released, modified or currently in a workflow) that is displayed in the ContentCreator toolbar.

Element Status and Workflow Displays

6. Page-Based Notifications
Implement notifications that occur in the ContentCreator preview. They will be shown within the page status flyout of the ContentCreator toolbar as well as - optionally - prominently underneath the page status display.

Page-Based Notifications

Extensions in FirstSpirit SiteArchitect

The FirstSpirit SiteArchitect provides multiple means to integrate plug-in components. Such components can include automation features, additional input components or connectors to web services serving as data providers or further content editing tools. SiteArchitect Extensions

Each of these plug-in types is connected to a different area in the SiteArchitect UI and uses FirstSpirit API functionality to execute programm actions:

Use cases for SiteArchitect modules Support

1. Context Menu Items
Insert one or more menu items into the context menu of store elements, "New" or "Plug-ins" submenu.

Context Menu Items

2. Toolbar Items
Insert buttons into the toolbar displayed above the editorial (middle) workspace of the SiteArchitect and work within the context of the FirstSpirit element currently shown in that workspace (e.g. a section whose form is currently displayed).

Toolbar Items

3. Reports (Data Access)
Integrate external data sources (e.g. web services) with FirstSpirit so that data from these sources (e.g. images, Youtube videos, etc.) can be referenced within FirstSpirit content.

Data Access

Setting up your work environment

As a developer, you need to set up your environment:

  • Access to Git repositories
  • Artifactory credentials

The setup only needs to be done once; the configuration is shared across all repositories.

Setting up access to Git repositories

To get access to the Git repository, you must provide your SSH key in your Bitbucket profile. Use an existing key or create one. Add the public key to your profile.

Setting up artifactory credentials to access module dependencies

Dependencies specified in your module are downloaded from our artifactory, which acts as a Maven repository. To make this work, you need to specify the log-in information in your personal gradle.properties.

The gradle.properties file is located in $HOME/.gradle/gradle.properties.

The file should contain at least:

artifactory_hosting_username=cloud_username artifactory_hosting_password=cloud_encrypted_password

cloud_username is usually your full email address.

The encrypted password can be retrieved with a simple REST call-up of the artifactory. For logging in use your cloud log-in credentials.

Developing modules

The first step to developing your module is to clone the existing repository from your FirstSpirit Cloud Git. If the repository does not yet exist, send a request to the Crownpeak Support team.

The following steps can help you in developing your own FirstSpirit modules:

Developing modules Support

1. Send a request to the TechnicalSupport team
if the repository does not exist yet.
You should use a separate repository for each module.

Create ticket at TechnicalSupport
Provide the desired name(s) of the repositories within the ticket. Ensure that the naming is meaningful.

2. Clone the existing repository in Bitbucket
The initial setup already contains a preconfigured Gradle environment.
This build automation tool allows for compiling and packaging your module while taking care of things such as external dependencies.

Bitbucket

Gradle Build Tool

3. Packaging a module into an FSM file
is performed by the FirstSpirit Module Gradle Plug-in. It creates a module descriptor and adds all required dependencies to the archive.

FirstSpirit Module Gradle Plug-in

Use a local test server
to speed up local development. The FirstSpirit Gradle Plug-in can start such a server for you and install the module automatically. This feature is also useful for automatic integration tests.

Usage of Web application components
Components of web applications can either be used globally or project locally. It’s needed to create global components because of resource and performance reasons.
Send a request to the Technical Support team to add a global web-app component.

FirstSpirit web applications

Create ticket at TechnicalSupport
Please provide the following information within the ticket:

  • name of the instance
  • name of the component to be added
  • name of the Web app
    (e. g. "ContentCreator")
  • optional: configuration of the component

Distributing modules

Depending on the Git branch that you are using, a pushed commit will trigger an automatic build process. This will install the module in one of your cloud instances. The naming convention is identical to the one in the Git Flow, a Git workflow which we recommend using.

The following steps can help you in developing your own FirstSpirit modules:

Distributing modules Support

1. Develop features locally

New features should always be developed and tested locally on a feature branch. Pushed commits on these branches will be compiled and tested by our CI pipeline, but your cloud servers will be left unchanged.
The CI pipeline will fail unless at least one successful unit test exists.

2. Push finished features to Dev branch

Pushed commits on the Dev branch are installed on the Dev Cloud instance. This requires a successful compilation and test execution without any errors.

CI / CD Pipeline

If your module contains WebApp components and your component is deployed for the first time, contact Technical Support to have the component added to the respective global web application (ContentCreator / Preview).

In the ticket, provide the

  • name of the instance
  • name of the component to be added
  • name of the Web app (e. g. "ContentCreator")
  • configuration of the component (optional)

Create Technical Support ticket
Updating a module may cause redeployments, e.g. for the ContentCreator. This can interrupt existing user sessions on the Dev instance.

3. Merge changes to master branch (QA)

To release a new version of your module, it needs to be installed in your QA instance. The installation is performed automatically after the changes are merged into the master branch.
The "Release" plan automatically generates the module's version number in the master branch. To manually increase the snapshot's version number, update it before merging the changes to master.
We recommend using Semantic Versioning.

4. Install module in Prod instance

New module versions in the production instance are installed during patch days only. Contact the FirstSpirit Technical Support team for details.

In the ticket, provide the

  • module name
  • required version number

Create Technical Support ticket

Table of Contents