Package: Report

The Report package contains implementations for the user-facing parts of the Editorial Search and Replace module's functionality. As such, its classes and packages

• define the reporting user interface,
• implement data provisioning and rendering, and
• provide interactive features for navigating to and performing replace operations on store elements associated with report entries.

The Report Plug-In, Data Provider, Data Renderer, and Report Item classes are parameterized with the interface ReportEntry and thus use objects based on implementations of that interface to store report entry data. The interface ReportEntry as well as its various implementations are located in the sub-package Report Entries.

Report Plug-In

de.espirit.firstspirit.opt.example.editorialsar.report.EditorialSARReportPlugin
Developer API documentation: ReportPlugin<T>
ODFS Plug-In Developer documentation: Report Plug-In

This Report Plug-In class defines the central, user-facing access point for this module's functionality.

It specifies report filter parameters to provide search and replace settings and instantiates the module-specific DataProvider, DataRenderer, as well as ReportItem implementations which provide the report's functional features.

Data Provider

de.espirit.firstspirit.opt.example.editorialsar.report.EditorialSARDataProvider
Developer API documentation: DataProvider<T>
ODFS Plug-In Developer documentation: Data Provider

The Data Provider class is responsible for identifying store elements that match the search request configured in the report's user interface and to provide a set of Report Entry objects which are each configured to process one or more store elements.

Method void start(SpecialistsBroker, ParameterMap)

After instantiation of an EditorialSARDataProvider object, this method is called to perform basic setup for the report entry provisioning process which will take place later on.

During setup, the data entered in the report's filter fields (such as search words, store type, etc.) are stored in a SearchConfiguration object for later use. The setup method also assembles a query string consisting of the Search Configuration object's search words as well as FirstSpirit-specific element type constraints identified from the store type parameter. Lastly, this query is submitted to a QueryAgent object to be answered; the answer is stored as a field for later use during the report entry provisioning process.

Note that because this module is designed to search and replace only in textual form data as well as selected text data of non-form elements while the QueryAgent searches across all indexed fields, the QueryAgent's answer cannot be used directly to provide a valid set of report entries; the QueryAgent is used to identify an initial set of store elements that match the search words and desired element types, which is later reduced to a "filtered" subset consisting of only store elements containing the search word(s) in fields processable by this module's Search Adapters.

Method List<ReportEntry> getNext(int)

The FirstSpirit clients use this method to obtain a number of ReportEntry objects. The desired maximum number of report entries is specified by the method's int parameter.

getNext(int) traverses the QueryAgent's answer (obtained in start(SpecialistsBroker, ParameterMap)) using the answer's iterator object until either the desired maximum number of report entries is reached or the iterator indicates no further store elements are available in the QueryAgent's answer.

Each store element obtained from the QueryAgent's answer is passed into the utility method ReportEntry getReportEntry(IDProvider) (see below). If that method returns a ReportEntry object, it is added to the list of report entries to return.

Method ReportEntry getReportEntry(IDProvider)

This utility method instantiates a ReportEntry object of a type matching the IDProvider object passed as a parameter.

The IDProvider and the ReportEntry objects must meet the following criteria, otherwise, the method returns null:

1. The store element is not locked (i.e., not in edit mode)
2. The store element does not have any validation issues that prevent saving
3. The provided store element fits the store type indicated by the report filter
4. The ReportEntry object reports at least one search result within the store element

In a ContentCreator session, the method also performs the following tasks to produce ContentCreator-compatible report entries:

• For elements of type Section, identify the Page element in its parent chain, and instantiate a PageReportEntry object if the Page element has not been encountered yet during this Data Provider instance.
• Only return a PageReportEntry object if the above criteria are fulfilled and the report entry object provides a PageRef object which references the Page element associated with the report entry.

Data Renderer

de.espirit.firstspirit.opt.example.editorialsar.report.EditorialSARDataRenderer
Developer API documentation: DataRenderer<T>
ODFS Plug-In Developer documentation: Data Renderer

The Data Renderer class is tasked with identifying and formatting information that should be displayed in report entry snippets as well as detail flyouts in the ContentCreator (displayed as a user moves the mouse pointer over a report snippet).

Specific to this module's needs of presenting report entry data, the renderer provides the following information:

• an element icon
• a snippet title based on the element's snippet header field
• a snippet description including
  • number of search hits
  • number of editors/fields in which these hits occur
  • number of project languages in which these hits occur
• a snippet thumbnail based on the element's snippet thumbnail field or on a Media element
• detail information for some element types (shown as a flyout in ContentCreator)

As of FirstSpirit 5.1, obtaining element snippet data is not supported by the FirstSpirit APIs. The code in this class uses non-API functionality to perform this task (casting elements as SnippetSupport in order to obtain a SnippetProvider object from which header, extract, and thumbnail data may be read). This methodology is not supported by e-Spirit and must not be implemented in production-quality modules. In a future version of the FirstSpirit Developer API, a specialized agent object may provide access to element snippet data.

Package: Report Entries

The classes in this package are implementations of the abstract class ReportEntry contained in the same package. As the module's report components are parameterized with ReportEntry, that class' extensions are the work objects passed between components. Report entries store one or more store elements that should be processed together in search and replace operations.

To allow for the procedural differences in handling store elements (e.g. some store elements are form-based while others are not, some are directly compatible with ContentCreator's preview while others are not, etc.), ReportEntry is extended by several, store element type-specific classes.

The following Report Entry classes do not implement FirstSpirit API.

• DatasetReportEntry is used to handle a single Dataset element.
• MediaReportEntry is used to handle a single Media element (of either File or Picture type).
• PageReportEntry is used to handle a single Page element and may contain a list of one or more associated child Section elements which should be processed together with the parent Page element in search and replace operations (for use with the ContentCreator report's store type filter "Web Pages").
• SectionReportEntry is used to handle a single Section element.
• TemplateReportEntry is used to handle a single TemplateStoreElement of type PageTemplate, SectionTemplate, FormatTemplate, LinkTemplate, or TableTemplate.

DatasetReportEntry, MediaReportEntry, PageReportEntry, and SectionReportEntry support processing of their respective element's metadata if the project's metadata template is activated for processing in the project application configuration. Metadata processing will use a FormDataSearchAdapter in conjunction with the Language constant SOLE_LANGUAGE, specified in the interface EditorValue.

Package: Report Items

The classes in this package provide interactive functionality with report entries. Providing specific implementations for ContentCreator and SiteArchitect, these items allow navigation to an element associated with a report entry (in the case of SiteArchitect, stepping through search results within that element) or to start a replacement process on such an element.

Navigation (ContentCreator)

de.espirit.firstspirit.opt.example.editorialsar.report.item.NavigateToElementWebeditExecutableReportItem
Developer API documentation: WebeditExecutableReportItem<T>
ODFS Plug-In Developer documentation: Executable Report Item

The ContentCreator-specific navigation report item triggers navigation to a specific store element in the preview pane. It is only available on report entries that store elements for which a preview-compatible store element can be identified. Elements compatible with the ContentCreator preview are PageRef, PageRefFolder and Dataset elements. If a report entry provides a store element of this type either directly (ReportEntry#getElement()) or indirectly (ReportEntry#getWebeditTargetElement()), the report item will become available and can be executed by clicking on the report entry snippet's rectangle.

Navigation (SiteArchitect)

de.espirit.firstspirit.opt.example.editorialsar.report.item.NavigateToElementJavaClientExecutableReportItem
Developer API documentation: JavaClientExecutableReportItem<T>
ODFS Plug-In Developer documentation: Executable Report Item

The SiteArchitect-specific navigation report item triggers navigation in the workspace area to the store element associated with the report entry. This item will attempt to cycle step-wise through the list of search results for the report entry, causing navigation through all of the element's tabs (language, metadata, or other tabs, depending on the element type) that contain editors or other text fields that match the search string. At the same time, highlighting will be used to mark any occurrences of the search string as well as the replacement string.

To facilitate stepping through search results located in different tabs of template elements, this report item uses non-API functionality marked as such in the source code. This methodology is not supported by e-Spirit and must not be implemented in production-quality modules.

Replace All (ContentCreator)

de.espirit.firstspirit.opt.example.editorialsar.report.item.ReplaceAllWebeditExecutableReportItem
Developer API documentation: WebeditExecutableReportItem<T>
ODFS Plug-In Developer documentation: Executable Report Item

This replacement executable handles locking, triggering replacement on, saving and unlocking of the store element associated with the context report entry. In this process, it observes certain requirements imposed by the ContentCreator's user guidance scheme.

• All elements of type DataProvider (i.e. Page, Section and Dataset elements) will be validated before saving. Should validation errors occur, the save process will be skipped, and the user notified.
• Replacement on report entries of type PageReportEntry will always include the Page element as well as all child Section elements for which search hits have been recorded. Should validation fail on any of these elements, the entire set will not be saved.
• Upon successful replacement, preview-compatible elements are loaded in the preview. For replacements performed on non-previewable elements, the report item will cause display of a message box, informing the user that replacement was successful.

Replace All (SiteArchitect)

de.espirit.firstspirit.opt.example.editorialsar.report.item.ReplaceAllJavaClientExecutableReportItem
Developer API documentation: JavaClientExecutableReportItem<T>
ODFS Plug-In Developer documentation: Executable Report Item

This replacement executable handles locking, triggering replacement on, saving and unlocking of the store element associated with the context report entry.

To prevent inconsistent data as a result of a replacement process, this item ensures that all elements of type DataProvider (i.e. Page, Section and Dataset elements) involved in a replacement process will be validated before saving. Should validation errors occur, the save process will be skipped, the user notified, and the form with post-replacement data displayed in the workspace area so that the user may perform manual corrections.