JavaScript API: Reports

JavaScript object: top.WE_API.Report
Developer API documentation: Report

The Report object allows display and filter configuration of ContentCreator reports as well as those provided by FirstSpirit Modules.

show(String reportName, JavaScriptObject filterParameters, boolean restart) causes the requested report (reportName) to be displayed.

The report's filter settings and data provisioning behavior are determined by the values of parameters filterParameters and restart.

String reportName

The report that should be displayed is referenced using a technical report name.

The reports provided with ContentCreator are referenced with a shorthand code:

<script type="text/javascript">

    // Open the built-in "Related Objects" report and refresh it.
    top.WE_API.Report.show("RelatedObjects", null, true);

</script>

Report plug-ins are referenced by the fully qualified class name of their respective ReportPlugin implementation:

<script type="text/javascript">

    // Open the Example Text Blocks report provided by the ContentCreator Examples module.
    top.WE_API.Report.show("de.espirit.firstspirit.opt.example.universal.report.TextBlocksReportPlugin", null, false);

</script>

JavaScriptObject filterParameters

This parameter allows configuration of filter settings in a report plug-in. It assumes JSON format to provide a comma-separated list of key/value pairs corresponding to Parameter objects defined by the report plug-in class and understood by the plug-in's data provider.

Preventing change of all or specific report filters

If filterParameters is provided as a null value or as a JSON object with no key/value pairs at all, the report's filter settings will be retained as currently set or - if the report is displayed for the first time during the current client session - will apply default values as specified by the report plug-in.

Any filter parameter not given as a key/value pair will cause the report filter to retain the current filter value or - if the report is displayed for the first time during the current client session - to apply that filter parameter's default value as specified by the report plug-in.

Parameter types and values

The three Parameter types available to report plug-ins accept the following data types as values:

• ParameterText: String
• ParameterBoolean: boolean
• ParameterSelect: String
  The String value must correspond to a SelectItem object configured for the ParameterSelect parameter.

Values of other data types (e.g. int) will be interpreted - if possible - to match the data type expected for a parameter value. However, it is not guaranteed that the interpreted value will be a faithful representation of the originally provided value.

Key/value pairs indicating parameters not specified by the report plug-in will be ignored.

Invalid and non-interpretable values will cause a JavaScript warning and leave the associated report filter configured as is.

Applying parameter defaults

If a parameter is explicitly given with a null value, that filter's default value as specified by the report plug-in will be applied.

Example

To apply the filter settings

• Search words
  filter "pattern_text" (type ParameterText) with value "ContentCreator"
• Search in titles only
  filter "pattern_boolean" (type ParameterBoolean) with value true (checked)
• Sort order
  filter "pattern_select" (type ParameterSelect) with value "ascending"

in the Text Blocks Example report (see the ContentCreator Example Module source code), use the following JavaScript block:

<script type="text/javascript">

    top.WE_API.Report.show(
        "de.espirit.firstspirit.opt.example.universal.report.TextBlocksReportPlugin",
        {
            "pattern_text":"FirstSpirit",
            "pattern_boolean":true,
            "pattern_select":"ascending"
        },
        false
    );

</script>

boolean restart

This parameter indicates whether the report should perform a new data provisioning run (true) or leave an existing result list as is if the filter parameters remain unchanged (false).

If the call of WE_API.Report.show() causes any change to filter parameters, the report's result list is refreshed regardless of this parameter's value.