Toolbar Menu Items: Code Example

This example code demonstrates the interfaces and methods implemented to include a custom action item in the "Actions" menu of the WebClient toolbar.

An Toolbar Menu Item plug-in consists of a two-tier class structure:

The first tier defines the toolbar plug-in and determines which second-tier objects (see below) should be offered to the WebClient depending on the current operational context.

• Toolbar Menu Items Plug-In
  serves as a container for and provider of one or more individual plug-in items that represent individual entries in the "Actions" toolbar menu

The second tier defines individual plug-in items; each item will be represented by its own entry in the "Plug-Ins" group of the toolbar menu "Actions", may define its own visibility context (based on store elements or other criteria) and provides its own, specific action.

• Executable Toolbar Menu Item
  provides a menu item and defines an executable action that will be executed on the server side and handle interaction with users
• Script Toolbar Menu Item
  provides a menu entry definition including title and icon, and defines a scripted action using JavaScript that will be executed on the client side

A toolbar menu items plug-in may contain one or more of the second-tier item classes. Each item will be represented by an individual entry in the "Actions" menu, provide its own action and define its own availability based on criteria such as context store element, etc. However, each of the second-tier menu items returned by getItems() must be an instance of a unique second-tier class and must return a unique label. WebClient will draw only one menu item for each class: the first object instance of each second-tier class returned by WebeditToolbarActionsItemsPlugin.getItems() will be represented in the interface, while any duplicate object based on the same class will be ignored.

The Toolbar Menu Items Plug-In

The toolbar menu items plug-in implements the interface WebeditToolbarActionsItemsPlugin and is responsible for collecting and returning a list of action items that will be shown as individual menu items. This class on its own has no representation in the WebClient user interface.

public class ExampleWebeditToolbarActionsItemsPlugin implements WebeditToolbarActionsItemsPlugin {

    private BaseContext _baseContext;


    @NotNull
    @Override
    public Collection<? extends WebeditToolbarItem> getItems() {
        return Arrays.asList(
            new ExampleExecutableToolbarActionsItem(),
            new ExampleClientScriptProvidingToolbarActionsItem();
    }


    @Override
    public void setUp(@NotNull final BaseContext context) {
        _baseContext = context;
    }


    @Override
    public void tearDown() {
    }

    // Place second-tier private classes specified later in this section here.

}

Collection<? extends WebeditToolbarItem> getItems()

After instantiating and setting up the toolbar menu items plug-in object, WebClient will call getItems() to poll for a list of available menu items. This method should return all available items defined as nested classes within the plug-in class; WebClient will autonomously call the appropriate, item-specific methods of each item returned by getItems() to determine in which context(s) each menu item should be shown and marked as active.

void setUp()

This method is called by the WebClient to set up the plug-in prior to polling it for available toolbar menu items.

void tearDown()

This method is called by the WebClient as the toolbar menu items plug-in is about to be destroyed.

Executable Toolbar Menu Item

The following code implements an executable toolbar menu item based on the interface ExecutableToolbarActionsItem and action that is able to use the full FirstSpirit APIs to produce functionality.

In this example, it is a private class nested within its parent, toolbar menu items plug-in class.

    private static class ExampleExecutableToolbarActionsItem implements ExecutableToolbarActionsItem {

        ExampleExecutableToolbarActionsItem() {
        }


        public String getLabel(@NotNull final ToolbarContext context) {
            return "Example Executable Toolbar Actions Item";
        }


        public String getIconPath(@NotNull final ToolbarContext context) {
            return null;
        }


        public boolean isVisible(@NotNull final ToolbarContext context) {
            return context.getElement() instanceof PageRef;
        }


        public boolean isEnabled(@NotNull final ToolbarContext context) {
            return context.getElement() instanceof PageRef;
        }


        public void execute(@NotNull final ToolbarContext context) {
            final OperationAgent operationAgent = context.requireSpecialist(OperationAgent.TYPE);
            final RequestOperation requestOperation = operationAgent.getOperation(RequestOperation.TYPE);
            requestOperation.setKind(RequestOperation.Kind.INFO);
            requestOperation.perform("This is a message box generated by the Example Executable Toolbar Actions Item.");
        }
    }

String getLabel()

This method is responsible for providing the item's display name that will be shown in the toolbar menu.

String getIconPath()

The method getIconPath() returns the path and file name of an icon graphic related to this item. The icon will be displayed in the item's representation in the toolbar menu. The file path is relative to the root of the project-specific WebClient web application.

This method is reserved for future use and may safely return null. Currently, WebClient menu items will not be shown with individual icon graphics.

boolean isVisible()

This method is responsible for determining in which context the menu item is to be displayed. If the item is to be displayed, the boolean value true should be returned; the value false will suppress display of this item's menu entry.

Standard use cases involve discriminating between specific page references, or to determine whether a page reference is used for content projection. Towards this end, WebClient provides a context object of type ToolbarContext as a parameter.

boolean isEnabled()

The method isEnabled() indicates if the item's menu entry should be active in a given context. If the entry is to be shown as active, this method should return the boolean value true. If this entry is to be inactive, the boolean value false should be used; in this case, the item's action code will not be executed on-click.

As with the method isVisible(), the ToolbarContext object will provide access to store and element-related information that can help determine active states.

void execute()

This method will be called by the WebClient once a user clicks the item's representation in the toolbar menu. execute() is treated as a point of entry into executable code to carry out the item's action and is not expected to return any value.

Script Toolbar Menu Item

A scripted toolbar menu item has access to a JavaScript API that will allow client-side scripting directly in the user interface. It implements the interface ClientScriptProvidingToolbarActionsItem.

The following code implements a private class nested within its parent, toolbar menu items plug-in class.

private static class ExampleClientScriptProvidingToolbarActionsItem implements ClientScriptProvidingToolbarActionsItem {


    ExampleClientScriptProvidingToolbarActionsItem() {
    }


    @Override
    public String getIconPath(@NotNull final ToolbarContext context) {
        return null;
    }


    @NotNull
    @Override
    public String getLabel(@NotNull final ToolbarContext context) {
        return "Example Client Script-Providing Toolbar Actions Item";
    }


    @Override
    public String getScript(final ToolbarContext context) {
        return "top.fs.API.getInstance().getCommon().showMessage(" +
            "\"This is a message box generated by the Example Client Script-Providing Toolbar Actions Item.\"" +
            ");";
    }


    @Override
    public boolean isEnabled(@NotNull final ToolbarContext context) {
        return true;
    }


    @Override
    public boolean isVisible(@NotNull final ToolbarContext context) {
        return true;
    }

}

getLabel()

This method is responsible for providing the item's display name that will be shown in the "Actions" menu.

getIconPath()

The method getIconPath() returns the path and file name of an icon graphic related to this item. The file path is relative to the root of the project-specific WebClient web application.

This method is reserved for future use and may safely return null. Currently, WebClient menu items will not be shown with individual icon graphics.

isVisible()

This method is responsible for determining in which context the menu item is to be displayed. If the item is to be displayed, the boolean value true should be returned; the value false will suppress display of this item's button.

Standard use cases involve discriminating between specific page references, or to determine whether a page reference is used for content projection. Towards this end, WebClient provides a context object of type ToolbarContext as a parameter.

isEnabled()

The method isEnabled() indicates if the menu item should be rendered active in a given context. If the item is to be active, this method should return the boolean value true. If this item is to be inactive, the boolean value false will cause the menu item to be displayed with decreased contrast to produce a muted representation; while the menu item will be visible (given that isVisible() returns true in the same context), the item's action code will not be executed on-click.

As with the method isVisible(), the ToolbarContext object will provide access to store and element-related information that can help determine active states.

getScript()

This method will be called by the WebClient once a user clicks the associated menu item. getScript() is designed to return a String containing JavaScript code that will be executed within the WebClient user interface (as opposed to the executable InlineEdit item, which is executed server-side). A FirstSpirit-specific JavaScript API is available to implement commonly used functionality.