Report Actions

Report actions may be added to individual report entries or act on a report-wide basis. For both SiteArchitect and ContentCreator, actions may be defined which execute Java code when triggered. Specific to ContentCreator is an action type which executes JavaScript when triggered.

Actions on Report Entries

Actions which operate on individual report entries may be added by implementing and providing the aspect ReportItemsProviding<D> via the data access component's Data Access Plug-In implementation.

One item may be associated with the entire rectangle of a report entry's snippet, other items will be shown as buttons with the report entry snippet.

public class MyReportItemsProvidingAspect implements ReportItemsProviding<MyDataObject> {

    @Nullable
    @Override
    public ReportItem<MyDataObject> getClickItem() {
        return new MyExecutableReportItem();
    }

    @NotNull
    @Override
    public Collection<? extends ReportItem<MyDataObject>> getItems() {
        return Arrays.asList(
            new MyClientScriptProvidingReportItem(),
            new MyExecutableReportItem()
        );
    }

    // See below for example report item implementations.
}

The Report Context Object

All methods defined by the report entry-specific action item interfaces described below receive a context object of type ReportContext<T> as a parameter which allows access to the report entry's associated data object as well as a means to redraw the report entry to reflect changed data and access agents included in the FirstSpirit APIs.

The report entry's associated data object may be obtained by calling the method getObject():

public String getLabel(@NotNull final ReportContext<MyDataObject> context) {
    final MyDataObject object = context.getObject();
    if (object != null) {
    return object.getHeader();
    } else {
        return "Unnamed object";
    }
}

The report entry may be redrawn by calling the method repaint(), which will trigger the Data Access Plug-In's data snippet provider to be called for the associated data object so that header, extract, thumbnail, and details may be redrawn in the report's user interface:

public void execute(@NotNull final ReportContext<MyDataObject> context) {
    final MyDataObject object = context.getObject();
    if (object != null) {
        object.setHeader(object.getHeader() + " - modified by report action item");
    }
}

Additionally, the report context object is a descendant of the interface SpecialistsBroker, meaning that FirstSpirit API agent objects available in the report context may be accessed using the methods requireSpecialist(...) and requestSpecialist(...).

Executable Report Item

An executable report item class implements one or both of the following interfaces to indicate compatibility with a FirstSpirit client:

• SiteArchitect: JavaClientExecutableReportItem<D>
• ContentCreator: WebeditExecutableReportItem<D>

Both interfaces share identical method definitions with the exception of those methods that provide icons for display in the user interface.

public class MyExecutableReportItem
    implements JavaClientExecutableReportItem<MyDataObject>, WebeditExecutableReportItem<MyDataObject> {

    public boolean isVisible(final ReportContext<MyDataObject> context) {
        final ExampleReportObject reportEntryObject = context.getObject();
        return reportEntryObject.getText() != null && !reportEntryObject.getText().isEmpty();
    }

    public boolean isEnabled(final ReportContext<MyDataObject> context) {
        return true;
    }

    public String getLabel(final ReportContext<MyDataObject> context) {
        return "Example Executable Report Item";
    }

    public Icon getIcon(final ReportContext<MyDataObject> context) {
        return new ImageIcon(this.getClass().getResource("example_executable_reportitem.png");
    }

    public String getIconPath(final ReportContext<MyDataObject> context) {
        return "example_report/example_executable_reportitem.png";
    }

    public void execute(final ReportContext<MyDataObject> context) {
        final ExampleReportObject reportEntryObject = context.getObject();
        final OperationAgent operationAgent = context.requestSpecialist(OperationAgent.TYPE);
        if (operationAgent != null) {
            final RequestOperation requestOperation = operationAgent.getOperation(RequestOperation.TYPE);
            if (requestOperation != null) {
                requestOperation.perform("Executable report item activated on report entry with text '" +
                        reportEntryObject.getText() + "'"
                );
            }
        }
    }

}

isVisible()

This method determines if the report item's button representation should be visible in the user interface.

The return value of this method only has effect upon report items shown as buttons attached to report list entries. A report plug-in's default report item is always assumed to be visible.

isEnabled()

This method determines if the report item should be enabled.

getLabel()

This method provides the text displayed in the report item's tool tip.

getIcon()

This method provides the icon displayed in this report item's button representation.

This method is only available in the interface JavaClientExecutableReportPlugin. The return value of this method affects only report items shown in the SiteArchitect.

getIconPath()

This method provides the URL of an icon that should be displayed in this report item's button representation.

This method is only available in the interface WebeditExecutableReportPlugin. The return value of this method affects only report items shown in the ContentCreator.

execute()

The code in this method will be executed when the report item's button or snippet (for a default report item) is activated by user interaction.

JavaScript-Providing Report Item (ContentCreator only)

Only available in ContentCreator. If a report plug-in is loaded in SiteArchitect and either its ReportItemsProviding aspect's getItems or getClickItem methods provide a report item object implementing this interface, the SiteArchitect will silently ignore it.

This report item provides JavaScript that should be executed as the report item is activated and implements the interface ClientScriptProvidingReportItem<T>.

public class MyClientScriptProvidingReportItem implements ClientScriptProvidingReportItem<MyDataObject> {

    public boolean isVisible(final ReportContext<MyDataObject> context) {
        final ExampleReportObject reportEntryObject = context.getObject();
        return reportEntryObject.getText() != null && !reportEntryObject.getText().isEmpty();
    }

    public boolean isEnabled(final ReportContext<MyDataObject> context) {
        return true;
    }

    public String getLabel(final ReportContext<MyDataObject> context) {
        return "Example Client Script-Providing Report Item";
    }

    public String getIconPath(final ReportContext<MyDataObject> context) {
        return "example_report/example_clientscriptproviding_reportitem.png";
    }

    public String getScript(final ReportContext<MyDataObject> context) {
        final ExampleReportObject reportEntryObject = context.getObject();
        return "top.WE_API.Common.showMessage('" + reportEntryObject.toString() + "');";
    }

}

isVisible()

This method determines if the report item's button representation should be visible in the user interface.

The return value of this method only has effect upon report items shown as buttons attached to report list entries. A report plug-in's default report item is always assumed to be visible.

isEnabled()

This method determines if the report item should be enabled.

getLabel()

This method provides the text displayed in the report item's tool tip.

getIconPath()

This method provides the URL of an icon that should be displayed in this report item's button representation.

This method is only available in the interface WebeditExecutableReportPlugin. The return value of this method affects only report items shown in the ContentCreator.

getScript()

This method provides JavaScript code that should be evaluated as the report item is activated. The code may make use of ContentCreator's JavaScript API by accessing the top.WE_API object.

Unlike the execute() method in executable report item classes, the getScript() method is called while the report item's button is rendered in the user interface. Only the JavaScript code returned by this method is executed upon the button's activation. It is therefore essential that this method's code contain only non-obtrusive functionality related to assembling JavaScript code.

Report-Wide Actions

Actions which operate report-wide may be added by implementing and providing the aspect StaticItemsProviding via the data access component's Data Access Plug-In implementation.

The items provided by this aspect will be made available near the report UI's title.

public class MyStaticItemsProvidingAspect implements StaticItemsProviding<MyDataObject> {

    @Override
    public Collection<? extends ReportItem<MyDataObject>> getItems() {
        return Collections.singletonList(new MyExecutableStaticItem());
    }

    // See below for example report item implementation.
}

Executable Report-Wide Item

An executable static item class implements a set of two interfaces, depending on the client in which the action should be made available:

• SiteArchitect: Item<BaseContext> and JavaClientExecutablePluginItem<BaseContext>
• ContentCreator: Item<BaseContext> and WebeditExecutablePluginItem<BaseContext>

Both interfaces share identical method definitions with the exception of those methods that provide icons for display in the user interface.

The methods resulting from the implementation of Item<BaseContext> and one of the executable plug-in item interfaces are similar to those of the Executable Report Items described above. However, as these items operate within a report-wide context, the method signatures differ: instead of context objects of type ReportContext<D>, the methods receive parameters of type BaseContext.

public class MyExecutableStaticItem implements Item<BaseContext>,
        JavaClientExecutablePluginItem<BaseContext>, WebeditExecutablePluginItem<BaseContext> {

    public boolean isVisible(final BaseContext context) {
        return true;
    }

    public boolean isEnabled(final BaseContext context) {
        return true;
    }

    public String getLabel(final BaseContext context) {
        return "Example Executable Static Item";
    }

    public Icon getIcon(final BaseContext context) {
        return new ImageIcon(this.getClass().getResource("example_executable_staticitem.png");
    }

    public String getIconPath(final BaseContext context) {
        return "example_report/example_executable_staticitem.png";
    }

    public void execute(final BaseContext context) {
        final OperationAgent operationAgent = context.requestSpecialist(OperationAgent.TYPE);
        if (operationAgent != null) {
            final RequestOperation requestOperation = operationAgent.getOperation(RequestOperation.TYPE);
            if (requestOperation != null) {
                requestOperation.perform("Hello, I am a report-wide action.");
            }
        }
    }
}

JavaScript-Providing Report-Wide Item (ContentCreator only)

Only available in ContentCreator.

This report item provides JavaScript that should be executed as the report-wide item is activated and implements the interfaces Item<BaseContext> as well as ClientScriptProvidingItem<BaseContext>.

The methods resulting from the implementation of Item<BaseContext> and ClientScriptProvidingPluginItem<BaseContext> are similar to those of the JavaScript-Providing Report Items described above. However, as these items operate within a report-wide context, the method signatures differ: instead of context objects of type ReportContext<D>, the methods receive parameters of type BaseContext.

public class MyClientScriptProvidingStaticItem implements
        Item<BaseContext>, ClientScriptProvidingItem<BaseContext> {

    public boolean isVisible(final BaseContext context) {
        return true;
    }

    public boolean isEnabled(final BaseContext context) {
        return true;
    }

    public String getLabel(final BaseContext context) {
        return "Example Client Script-Providing Report-Wide Item";
    }

    public String getIconPath(final BaseContext context) {
        return "example_report/example_clientscriptproviding_staticitem.png";
    }

    public String getScript(final BaseContext context) {
        return "top.WE_API.Common.showMessage('Hello, I am a report-wide action.');";
    }

}