The Report Plug-In

Developer API documentation: ReportPlugin<T>

The report plug-in interface is the starting point for FirstSpirit report implementations. Classes implementing this object define the name and look of a report plug-in as well as its behavior by specifying data provider, data renderer, transfer handler and report item classes to be used.

A report plug-in class may also contain logic that determines when the report should be included in SiteArchitect and ContentCreator user interfaces.

Code Example

This class defines the basic properties of the report - name and icon as well as object type(s) to work on - and creates two mandatory objects - a data provider and a renderer - as well as several options objects - transfer handler and report items - that operate on those object types specified. It may be considered the top-tier class of a report plug-in structure and implements the interface ReportPlugin<T>.

public class ExampleReportPlugin implements ReportPlugin<ExampleReportObject> {

    // Filter objects. We will define their values in init().
    public static ParameterBoolean BOOLEANPATTERN;
    public static ParameterText TEXTPATTERN;
    public static ParameterSelect SELECTPATTERN;

    // BaseContext object for internal persistence in this class.
    private BaseContext _context;

    public boolean isVisible() {
        return true;
    }

    public String getTitle() {
        return "Example Report Plug-In";
    }

    public Image<?> getIcon(final boolean selected) {
        if (selected) {
            return Image.Factory.fromUrl("webclient_examples/media/report/example/reportbutton_selected.png");
        } else {
            return Image.Factory.fromUrl("webclient_examples/media/report/example/reportbutton_normal.png");
        }
    }

    public List<Parameter<?>> getParameter() {
        ArrayList<Parameter<?>> parameterList = new ArrayList<Parameter<?>>();
        parameterList.add(BOOLEANPATTERN);
        parameterList.add(TEXTPATTERN);
        parameterList.add(SELECTPATTERN);
        return parameterList;
    }

    public DataProvider<ExampleReportObject> createDataProvider() {
        return new ExampleDataProvider();
    }

    public DataRenderer<ExampleReportObject> createDataRenderer() {
        return new ExampleDataRenderer();
    }

    public TransferHandler<ExampleReportObject> createTransferHandler() {
        return new ExampleTransferHandler();
    }

    public ReportItem<ExampleReportObject> getDefaultItem() {
        return new DefaultExampleReportItem();
    }

    public Collection<? extends ReportItem<ExampleReportObject>> getItems() {
        return Arrays.asList(
            new FirstExampleReportItem(),
            new SecondExampleReportItem()
        );
    }

    public void setUp(final BaseContext context) {
        BOOLEANPATTERN = new ParameterBoolean("active", "Boolean Filter Pattern", false);
        TEXTPATTERN = new ParameterText("filter", "Text Filter Pattern", null);

        ArrayList<ParameterSelect.SelectItem> selectPatternItems = new ArrayList<ParameterSelect.SelectItem>();
        selectPatternItems.add(new ParameterSelect.SelectItem("Option 1", "value_1"));
        selectPatternItems.add(new ParameterSelect.SelectItem("Option 2", "value_2"));
        SELECTPATTERN = new ParameterSelect("sortorder", selectPatternItems, "value_1");
    }

    public void tearDown() {
    }

}

In this example, the class ExampleReportPlugin is an implementation of the interface ReportPlugin, parameterized with the type ExampleReportObject. Objects of the type ExampleReportObject are used to store individual report entry objects, and this parameterization defines that the classes associated with this report plug-in (e.g. data provider and data renderer) are also parameterized with and work on objects of this type.

isVisible()

This method specifies conditions which, if met, will lead to the report being displayed in a client user interface.

Likely use cases that should determine whether a report plug-in should be available in a client are

• availability of a specific client service (see Permanent Plugins) or server-side service
• limitation of report use to project (e.g. by determining if a project contains a specific project component)
• limitation of report use to either SiteArchitect or ContentCreator

getTitle()

This method is responsible for providing the report's display name. This string is shown at the top of the report's panel and as a button label in the report bar's flyout.

getIcon()

Report button states: inactive (left) and active (right)

getParameter()

Report filter patterns

createDataProvider()

This method simply creates and returns an object based on an implementation of the interface DataProvider. The report plug-in itself does not directly communicate with the plug-in's data provider object. Rather, the client software uses the information provided by the plug-in object to directly communicate with and poll the provider as necessary.

createRenderer()

As with createDataProvider(), this method creates and returns an object, in this case based on an implementation of the interface DataRenderer. Once again, the report plug-in itself does not directly communicate with the plug-in's data renderer object; the client software calls the renderer object as needed and passes the object(s) this report works on directly to the renderer.