FirstSpirit module development - Getting started

Published on 1 Mar 2019

Looking to build your own FirstSpirit modules? Follow our guide to get going right away!

Rafael Lopes das Dores

Consulting and Development

Motivation

When starting a new FirstSpirit project oftentimes you realise relatively quickly that not all desired functionalities and plugins are available within the SiteArchitect and the ContentCreator by default. For that reason e-Spirit offers a rich java-based API for FirstSpirit which can be used to develop your own FirstSpirit modules and extensions. Utilising these Java interfaces you will be able to modify and optimize the FirstSpirit clients’ abilities to your daily workflow.

In this short tutorial I would like to give an introduction on how to implement a FirstSpirit module and how to supply components to the SiteArchitect and the ContentCreator in the form of an FSM (FirstSpirit module). This is a simple example, but this setup the can be used as a baseline to create more complex types of modules in a FirstSpirit environment later on.

The foundation - Build management

To build FirstSpirit modules many different build management tools can be used. Most current projects will use either Gradle or Maven, whereas older projects might still utilise Apache Ant. In most cases each company will develop their own build process as infrastructure-wise the development process can vary greatly.

For this example we will use Apache Maven as we can use a reference implementation provided by the vendor e-Spirit on GitHub. As a first step please familiarise yourself with the so called firstspirit-module-parent-pom. Using this POM definition and Maven we will be able to automatically create the folder structure needed to create a FirstSpirit module.

Getting started

Add the firstspirit-module-parent-pom as well as its dependencies fsm-assembly and firstspirit-base-parent-pom to your local Maven repository. Ideally you want to host your dependencies in a centralised repository like JFrog Artifactory, Nexus or Apache Archiva to enable other developers in your company to use them.

Start by setting up a standard Maven project with its default folder structure. Within this project add the parent-pom from e-Spirit as a <parent> attribute in your pom.xml file. Make sure you replace [parent-pom-version] with the respective version that you checked out from the Git repository.

<parent>
<groupId>com.espirit.ps.maven</groupId>
<artifactId>firstspirit-module-parent-pom</artifactId>
<version>[parent-pom-version]</version>
</parent>

Linking the FirstSpirit Java API

FirstSpirit server information dialog including the server version number
FirstSpirit server information dialog including the version number

To use FirstSpirit Java interfaces you must add a library as a dependency to your project. This works by either adding it to the IDE right away or ideally pulling it from a central repository using Maven as well. All required interfaces can be found in the fs-isolated-runtime.jar. This library will always be distributed together with the FirstSpirit server you are currently running. You will be able to find it in the /data/fslib folder of your FirstSpirit installation directory. The versioning scheme uses the last minor version, followed by the current server version and its build number. For example for the January 2019 version, we would need 5.2.190105.

Find the correct version number for your server by going to the FirstSpirit startpage, clicking on the version number and selecting “Show all details”.

pom.xml including added dependency

Now add the library to your project using your pom.xml. Make sure you set the scope attribute to provided. This is to ensure the module we are building does not contain the library we just added but will instead use the library from the FirstSpirit server itself during runtime. By doing so our module will remain a lot smaller and contains only the classes that are really needed.

As a last step of our initial setup we will need a so called module descriptor. We can provide that in the form of a module.xml file created in our project’s resources folder. For a simple module we will only need the following attributes:

<module>
<name>MySimpleModule</name>
<version>1.0</version>
<description>A simple module to show FirstSpirit module development.</description>
<components></components>
</module>

After that you can build the module using the Maven lifecycle package. This will create an FSM-file in your target folder which can be installed on a FirstSpirit server later.

To find out more about what kind of extensions can be implemented for the components block, see our other blog posts about FirstSpirit module development. Should you have any questions on developing extensions or you require our support for your project do not hesitate to Contact Us!

facebook icon twitter icon xing icon linkedin icon
© 2019 aboutcontent GmbH