FirstSpirit module development - Implementing an Executable

Published on 11 Mar 2019

This tutorial is a follow-up to our guide “Developing modules for FirstSpirit - Getting started”. Let's get into developing your first component.

Rafael Lopes das Dores

Consulting and Development

Implementing extensions for FirstSpirit projects

In a FirstSpirit environment many different types of extensions and plugins can be implemented for the SiteArchitect and the ContentCreator. In most cases module development is a fundamental part of a FirstSpirit project. The most basic form of an extension is an executable class that uses the FirstSpirit API.

In this example we will deal with a simple but everyday project scenario. It is our goal to ask an editor a question about his current editorial process. Depending on his/her selection we would like to trigger different actions either within the client or on the server itself. Our implementation will provide the means to show the dialog to the user.

Implementing the class

To make an executable your first step is to implement the interface de.espirit.firstspirit.access.script.Executable. This interface will provide two different execute methods. The simple type without additional writers is mostly sufficient to implement a proper FirstSpirit module. This is why for this example we will simply delegate the more complex method to the other one and continue on.

import de.espirit.firstspirit.access.script.Executable;
import java.io.Writer;
import java.util.Map;
public class MySimpleExecutable implements Executable {
    @Override
    public Object execute(Map<String, Object> map) {
        return null;
    }
    @Override
    public Object execute(Map<String, Object> map, Writer writer, Writer writer1) {
        return execute(map);
    }
}

Starting point - SpecialistsBroker

Starting point for the development of all FirstSpirit modules is always a so called SpecialistsBroker. Following the Broker pattern this provider will supply different types of “agents” through which you’ll be able to acquire more detailed information on a certain topic. Many of these agents can be found in the de.espirit.firstspirit.agency package of the FirstSpirit Developer API.

For our example we will simply display a dialog using the OperationAgent. To do so we retrieve the key “context” from the map provided by the execute method. This object will provide a SpecialistsBroker no matter where the executable is run.

However depending on the location from where the executable is accessed (from a template, deployment task, ContentCreator) the SpecialistsBroker will extend additional “context” interfaces. We will publish an extra blog post dealing with this topic specifically in the future.

In its most basic form the broker provides the methods requestSpecialist and requireSpecialist. The difference between the two is simply that the request method will be able to return a null value whereas requireSpecialist will throw an exception should it not be able to retrieve an instance from the server. This could potentially happen in multiple places. An OperationAgent could for example not be available if the script is being called from a schedule task. In that case the code is executed on the server where it does not make sense to display any dialogs at all. Check the documentation for each agent individually to find out more. Keep in mind to use the requestSpecialist method only if you as a developer can react to it accordingly.

Implementing the class

We will use the requireSpecialist method to load an instance of the OperationAgent. A simple type of operation provided by this agent is a RequestOperation which can be used to display a dialog to the user, asking a question and providing multiple answers.

import de.espirit.firstspirit.access.script.Executable;
import de.espirit.firstspirit.agency.OperationAgent;
import de.espirit.firstspirit.agency.SpecialistsBroker;
import de.espirit.firstspirit.ui.operations.RequestOperation;
import java.io.Writer;
import java.util.Map;
public class MySimpleExecutable implements Executable {
   @Override
   public Object execute(Map<String, Object> map) {
       final SpecialistsBroker broker = (SpecialistsBroker) map.get("context");
       final RequestOperation operation = broker.requireSpecialist(OperationAgent.TYPE).getOperation(RequestOperation.TYPE);
       operation.setTitle("An action requires your attention");
       operation.setKind(RequestOperation.Kind.QUESTION);
       RequestOperation.Answer yes = operation.addYes();
       RequestOperation.Answer no = operation.addNo();
       RequestOperation.Answer answer = operation.perform("Would you like to continue?");
       if (yes == answer) {
           //Do something
       }
       return null;
   }
   @Override
   public Object execute(Map<String, Object> map, Writer writer, Writer writer1) {
       return execute(map);
   }
}

The operation can be configured in many different ways depending on what kind of question you would like to ask or which piece of information you would like to display. Open the dialog by calling the perform method. Afterwards you can evaluate the Answer object containing the user input.

Making the class available in the client

To use the class as a script within the SiteArchitect/ContentCreator you have to add the component to your module.xml. By doing so FirstSpirit will be able to identify your class by a distinct name. Add a <public> tag with an alphanumeric name and the full qualified class name. Example:

<public>
   <name>SimpleExecutable</name>
   <class>de.aboutcontent.MySimpleExecutable</class>
</public>

After installing the module this component can be instanciated from a beanshell script or a schedule with the addition of a header:

#!executable-class
SimpleExecutable

Executables can be used in many different scenarios within a FirstSpirit project whereby this extension is one of the easiest ones to implement. For more types of plugins and corresponding example implementations please follow our other blog posts.

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