Java-Executables entwickeln - FirstSpirit Modulentwicklung

Veröffentlicht am 11.03.2019

Dieses Tutorial knüpft an unseren Guide “Module entwickeln für FirstSpirit - Getting started” an. Entwickeln Sie Ihre erste FirstSpirit Komponente.

Rafael Lopes das Dores

Consulting and Development

Erweiterungen in FirstSpirit Projekten

Im FirstSpirit-Umfeld können verschiedenste Plugins und Erweiterungen für SiteArchitect und ContentCreator implementiert werden. Meistens ist die Modulentwicklung ein elementarer Bestandteil eines FirstSpirit-Projektes. Die einfachste Form der Erweiterung sind sog. Executables, also ausführbare Java-Klassen, die sich die FirstSpirit API zunutze machen.

In diesem Beispiel behandeln wir ein einfaches aber klassisches Projektszenario. Wir möchten dem Redakteur eine Frage zum Redaktionsprozess stellen und je nachdem, wie dieser sich entscheidet, unterschiedliche Aktionen im Client oder auf Serverebene auslösen. Unsere Klasse wird den dafür benötigten Dialog anzeigen.

Implementierung der Klasse

Um mit dem Entwickeln zu beginnen, wird im einfachsten Fall das Interface de.espirit.firstspirit.access.script.Executable implementiert. Diese Schnittstelle liefert zwei execute-Methoden. Die einfachere Variante ohne zusätzliche Writer, reicht in den meisten Fällen aus, um das Modul zu implementieren. Deswegen wird der komplexere Aufruf für unser Beispiel lediglich an die andere Methode weitergereicht.

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);
    }
}

Einstiegspunkt - SpecialistsBroker

Der Einstiegspunkt für die Entwicklung sämtlicher FirstSpirit-Module ist immer ein sog. SpecialistsBroker. Dieser liefert nach dem Broker-Pattern diverse Agents über die erweiterte Informationen abgerufen werden können. Eine ganze Reihe dieser Agents kann im Package de.espirit.firstspirit.agency der FirstSpirit Developer API eingesehen werden.

Für unser Beispiel werden wir mithilfe des OperationAgents einen einfachen Dialog anzeigen. Dafür laden wir aus der Map, die uns die execute-Methode liefert, den Key “context”. Dieser hält in allen FirstSpirit-Kontexten einen SpecialistsBroker für uns bereit.

Je nachdem aus welchem Kontext heraus Klassen aufgerufen werden (Template, Auftragsskripte, Generierung, ContentCreator), stehen zusätzliche kontext-spezifische Methoden zur Verfügung, die der SpecialistsBroker erbt. Zum Thema FirstSpirit Contexts werden wir noch einen zusätzlichen Beitrag veröffentlichen, um es ein wenig näher zu beleuchten.

In der einfachen Form sind die Methoden requestSpecialist und requireSpecialist vorhanden. Der Unterschied liegt darin, dass die request-Methode einen null-Wert liefern kann, wohingegen require eine Exception wirft, sollte ein Agent nicht verfügbar sein. Dies kann an unterschiedlichsten Stellen der Fall sein. So ist der OperationAgent in unserem Beispiel in Auftragsskripten nicht verfügbar, da es für den auf dem Server ausgeführten Code nicht sinnvoll ist, Dialoge anzeigen zu können. Die request-Methode sollte daher nur an Stellen verwendet werden, an denen ich als Entwickler tatsächlich adäquat auf diesen Umstand reagieren könnte.

Implementierung der Aktion

Wir benutzen die requireSpecialist-Methode, um eine Instanz des OperationAgents zu laden. Eine einfache Variante einen Dialog anzuzeigen oder dem Benutzer eine Frage zu stellen bietet in diesem Fall die besondere Ausprägung der RequestOperation. Eine solche Instanz lässt sich wiederum über den Agent laden.

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);
   }
}

Die Operation lässt sich unterschiedlich konfigurieren, je nachdem welche Frage gestellt wird und welche Antworten zur Option stehen sollen. Durch den Aufruf von perform wird der Dialog angezeigt. Danach lässt sich das Answer-Objekt auswerten.

Klasse verfügbar machen

Damit die implementierte Klasse im SiteArchitect/ContentCreator in verschiedensten Skripten verwendet werden kann, muss die Komponente in der module.xml bekannt gemacht werden. Dazu wird ein <public>-Tag mit einem alphanumerischen Namen und dem vollqualifizierten Klassennamen versehen. Beispiel:

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

Danach kann ein Beanshell oder Auftragsskript mit folgendem Aufruf die Klasse ausführen:

#!executable-class
SimpleExecutable

Es gibt diverse weitere Stellen, an denen die Executables Anwendung finden. Diese Art des Moduls stellt lediglich die einfachste Variante dar. Für zusätzliche Implementierungsbeispiele verfolgen Sie unsere anderen Blogposts und lesen Sie auch die offizielle FirstSpirit Dokumentation.

Wenn Sie Fragen zur Entwicklung von Erweiterungen haben oder Sie unsere Unterstützung für Ihr Projekt benötigen, zögern Sie nicht und treten Sie mit uns in Kontakt!

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