Permanent Plug-Ins: Code Example

Compared to other plug-in interfaces, permanent plug-in structure is relatively simple: a permanent plug-in provides a set of functionality that should be executed during client start-up and another set of functionality that is to be executed while a client session is being closed.

This code example provides

• a description of a permanent plug-in's programmatic structure, and
• an explanation of the set of plug-ins called MessageMe, provided with the FirstSpirit Developer Example source code, which demonstrates the use of permanent plug-ins.

Permanent Plug-In Structure

Access API documentation:
SiteArchitect: JavaClientPermanentPlugin
ContentCreator: WebeditPermanentPlugin

public class ExamplePermanentPlugin implements JavaClientPermanentPlugin, WebeditPermanentPlugin {

    public void setUp(@NotNull BaseContext context) {
        // Functionality to be executed during client session start-up,
        // e.g. registration of client services.
    }

    public void tearDown() {
        // Functionality to be executed during client session shutdown,
        // e.g. unregistration of client services.
    }

}

setUp(BaseContext)

The setUp method is called as a client session is started. For both SiteArchitect and ContentCreator, this occurs after project selection.

At this point, the permanent plug-in may provide background functionality such as registering client services (see Services for more information), initialization of session-specific data for use by other plug-ins, etc.

The methods in a permanent plug-in may use project-specific agents such as ProjectAgent, QueryAgent and others. However, since permanent plug-ins are intended to provide background functionality, developers should not assume that interactive client operations (i.e. operations requested through the OperationAgent) and other agent functionality are available at this stage.

tearDown()

The tearDown method is called as a client session is shutdown.

Depending on the client, sessions are shutdown in different ways:

• a SiteArchitect session is shut down as a user exits the SiteArchitect window
• a ContentCreator session is shut down as a user explicitly logs out or as the session expires (in case the user has closed the browser tab or window containing a ContentCreator session without logging out)

The MessageMe Plug-In Set

Location: Developer Examples module Zip file
Module name: ui_universal
Package path: de.espirit.firstspirit.opt.example.universal.permanentplugin

In order to demonstrate permanent plug-in functionality, we provide a set of plug-ins named MessageMe as part of the Developer Examples module source code.

MessageMe functionality is kept deliberately simple and is thus limited to sending the current user a message that includes a user-specific and server-wide count of how many times such a message has been requested since the last time a counter service was started. Towards this end, the plug-in set provides an editorial toolbar button for the SiteArchitect's user interface and a menu item that will be displayed in the ContentCreator's Actions toolbar menu.

Installation

Once the source code of the ui_universal module included in the Module Developer Examples source code Zip file has been compiled into a FirstSpirit Module (FSM) file, this FSM file can be installed using the “Modules” page of the “Server Configuration” window in ServerManager. The MessageMe plug-in components will appear in the module listing as part of the module “FirstSpirit UI Examples - Universal”.

Configuring projects with the project application

Each project that should use this module's functionality must be configured with the project application named “Permanent Plug-In: MessageMe - Project application”.

In all client sessions that use projects which are not configured with the project application component, the permanent plug-in will not register the MessageMeController, which will cause the toolbar items plug-ins to not register their respective user interface components. Thereby, installation of the project application component controls in which projects MessageMe functionality will be presented.

Configuring project-specific ContentCreator web applications

Each of the projects that should use this module's functionality in ContentCreator must also be configured to use a project-specific ContentCreator web application. This web application must include the module's web application component named “FirstSpirit UI Examples - Universal: run-time library for ContentCreator 5”.

For more information on these installation steps, please consult the following pages in the FirstSpirit Manual for Administrators:

• Modules (→Documentation for Administrators)
• Project components (→Documentation for Administrators)
• Web components (→Documentation for Administrators)

Module Structure

The MessageMe plug-in set is centered around a permanent plug-in implementation, but requires more components to be functionally available.

For each client session, the permanent plug-in component checks whether the MessageMe project application component has been added to the current project. This enables the plug-in to identify which projects should offer MessageMe functionality.

If the project application is found, the permanent plug-in continues by registering a MessageMeController object as a client service. Availability of the MessageMeController client service is a prerequisite for the user interface plug-ins (MessageMeJavaClientEditorialToolbarItemsPlugin and MessageMeWebeditToolbarActionsItemsPlugin) to return their respective items through which message-sending functionality is triggered.

The MessageMeCounterService, which is a server-wide service, keeps count of how many times each user has triggered message-sending functionality since the service was last started. If the service is not available for some reason (e.g. it has been stopped by a server administrator), the MessageMeController's displayMessage method will still function but not include a message count in the message sent to the current user.

MessageMeProjectApp

Implements: ProjectApp
Component type: project-app

This project application bears no functionality. It is intended to provide a means by which to specify in which project(s) the MessageMe functionality should be made available.

Most of the functionality for this plug-in set resides in client-side plug-ins, including a PermanentPlugin implementation, a controller class and one toolbar items class for each SiteArchitect and ContentCreator.

Server-side, a project application provides a means to specify in which FirstSpirit projects MessageMe functionality should be available (to enable the plug-in set's functionality

MessageMeCounterServiceImpl

Implements: MessageMeCounterService, Service<MessageMeCounterService>
Component type: service

This class implements a simple counter service that will keep a persistent count of how many MessageMe messages have been sent out per user since the last time the service was started. The MessageMeController class uses this service in the course of sending a user messages to demonstrate functionality.

This class is an implementation of the interface MessageMeCounterService which exists in the same package. That interface is also used to parameterize the Service implementation.

MessageMePermanentPlugin

Implements: JavaClientPermanentPlugin, WebeditPermanentPlugin
Component type: public

This class is loaded as each client session is created. During setup, once the permanent plug-in has successfully verified that the MessageMeProjectApp has been configured for the current project and that the MessageMeCounterService is available, a MessageMeController object is instantiated and registered as a client service.

MessageMeController

Implements: nothing
Component type: not added as a component

This controller class acts as the central client service to provide MessageMe functionality. It may be called upon by the user interface plug-ins (the JavaClient editorial toolbar button and the WebClient Actions menu item) to send a message that should be displayed to the user who triggered one of these interface plug-ins. While processing a message display request, the controller communicates with the server-side MessageMeCounterService to receive an incremented count of how many times this user has sent a MessageMe message as well as an updated, cumulative count of how many messages have been sent total.

MessageMeJavaClientEditorialToolbarItemsPlugin

Implements: JavaClientEditorialToolbarItemsPlugin
Component type: public

If the MessageMeController is available as a client service in the current client session, this toolbar items plug-in provides an ExecutableToolbarItem. Clicking on this toolbar button will call the MessageMeController's displayMessage method.

MessageMeWebeditToolbarActionsItemsPlugin

Implements: WebeditToolbarActionsItemsPlugin
Component type: public

If the MessageMeController is available as a client service in the current client session, this toolbar items plug-in provides an ExecutableToolbarActionsItem. Clicking on this menu item will call the MessageMeController's displayMessage method.