Start page
Start page

Start page / Plug-In Development / Universal Extensions / Reports / Code Example / Report Plug-In

Chapter “Data Provider” >>

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)

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

The method getIcon() returns an icon to be used for this report. This icon will be used in the button display in the report bar as well as at the top of the report's panel.

The boolean selected indicates whether the report button is active (this report's panel is currently displayed; selected == true) or inactive (another report's panel is displayed or none of the report panels are currently visible; selected == false). If the report button is inactive, the icon will be displayed over a ruby-colored background; in its active state, the report button will have a white background. The report header and the report bar flyout always use the inactive icon version, displayed over a grey or ruby background, respectively.

Image Factory for Client-Specific Icons

Due to the cross-client nature of FirstSpirit report plug-ins, icon objects for reports and report entries are generated using a factory, Image$Factory.

For the ContentCreator, Image.Factory.fromUrl(String) should be used. The String parameter provides a path, including file name, relative to the root of the project-specific ContentCreator web application.

For the SiteArchitect, Image.Factory.fromIcon(javax.swing.Icon) should be used.

getParameter()

Report filter patterns

Report filter patterns

This method provides a list of parameter objects that will be used to construct the filter functionality at the top of the report panel. The list may either be empty - indicating that no filter configuration is used and the report's provider object should be polled automatically upon display - or contain any number of objects of the following types:

  • ParameterBoolean
    defines a checkbox; must be configured with a label string as well as a default state (checked or unchecked)
  • ParameterSelect
    defines a drop-down selection list; must be configured with a list of ParameterList.SelectItem objects that each carry a label string and a string value, as well as a default value that corresponds to one of the select items' values
  • ParameterText
    defines a text box; must be configured with a placeholder text that is used if the text box contains no value, and may be configured with a default value that is used as the initial value of this field

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.

Chapter “Data Provider” >>

© 2005 - 2015 e-Spirit AG | All rights reserved. | Last change: 2014-02-19