Reports: Functional Overview

Functionality

Report plug-ins will be integrated into the FirstSpirit clients' report bars alongside the clients' respective, built-in reports.

• For ContentCreator, report buttons will be added to the right-hand side report bar.
• For SiteArchitect, report buttons will be added to the Organize section of the left-hand side navigation toolbar. SiteArchitect-compatible report plug-ins may also be shown in this client's homepage; in this display context, filter configurations based on report parameters are not available.

Custom reports are capable of displaying information in a snippet list and provide filtering options. Each snippet object can receive interactive functionality through action buttons. Furthermore, each snippet can act as a data provider for drag-and-drop operations.

In terms of functional design, custom reports implement at least three interfaces: a high-level plug-in definition, a data provider and a data renderer.

• A high-level plug-in definition that describes the report's user interface, including name, icon and filter configuration
• A data provider that is responsible for assembling a list of objects, each of which will be displayed as an individual row (a snippet) in the report; as reports are designed for continuous scrolling with on-demand loading of additional snippets, this data provider supports incremental polling
• A data renderer that defines what object information is to be displayed in report snippets

These three components operate on Java objects of a predetermined type. Using this architecture, it is possible to develop reports that operate on FirstSpirit store elements or work on object instances of a custom Java class that may, for example, store data about individual entries of a corporate RSS feed. The plug-in's data renderer class then associates the data stored within an object with the various data items used to create and work with an individual snippet.

Additionally, a custom report plug-in may implement several optional features:

• A transfer handler object that provides information for drag-and-drop operations of single report entries within the FirstSpirit client user interfaces.
• One or more report items which provide on-click interaction with a single report entry. Generally, report items will appear as buttons attached to a report entry; one of these items may be set as the default action which will be executed upon click on the report entry itself.

In order for report plug-ins to become visible in a FirstSpirit project loaded in either SiteArchitect or ContentCreator, the following conditions must be met: the number of licensed FirstSpirit application integrations has neither been met nor exceeded (see Additional documentation, "FirstSpirit AppCenter", chapter 1.6: "License model") Additionally, use in ContentCreator requires a project-specific ContentCreator web application that is configured with a web-app component which contains all Java classes and resources required by the report plug-in.

Example Implementations

The FirstSpirit 5 ContentCreator Examples module contains one example implementation, Example Text Blocks.

Example Text Blocks

This plug-in implements a report plug-in (TextBlocksReportPlugin), a data provider (TextBlocksDataProvider) as well as a data renderer (TextBlocksDataRenderer) that work on a TextBlocksObject data type. For simplicity, sample content for this report is generated in the data provider class itself and consists of a headline, a short text and a thumbnail graphic, all of which will be displayed in the report's results list.

The plug-in also provides a class TextBlocksTransferHandler which acts as a data source for drag-and-drop operations in conjunction with the FS_BUTTON executable example, TextBlocksDropHandlerExecutable, as well as input components (such as CMS_INPUT_TEXT or CMS_INPUT_DOM) which accept plain-text data via drag-and-drop.

The report plug-in class TextBlocksReportPlugin as well as its associated object, provider and renderer classes are located in the package de.espirit.firstspirit.opt.example.universal.report in the ContentCreator Example module's source code.

Code Example

The Report Code Example introduces and documents the classes required for a fully functional custom report and explains the details of programmatic interaction between the report plug-in's individual components and with the ContentCreator.