Configuring metadata for additional element attributes

As an implementor of an pentaho-reporting extension, from time to time you will need to store additional information along with report elements.

Pentaho reporting allows all elements to carry additional attributes on elements. Attributes are stored as objects and described by metadata.

1. Attributes without metadata

If attributes are stored on elements without suitable metadata descriptions, the engine will fall back to an default mode. If the attribute value is a string, the attribute value will be stored in the PRPT file when the report is saved. Values of undeclared attributes, that are not strings, will be lost.

If the PRPT file is parsed and the xml-parser encounters an undeclared attribute, the attribute's raw string value will be stored in the parsed element. Upon the next save, such an attribute's value will be preserved.

2. Attribute Metadata properties

All meta-data in Pentho Reporting follows a similar schema. Metadata describes features and their presentation to the user. All metadata is held in various metadata registries.

The attribute metadata is bound to an element-type. Attributes are keyed by a namespace and name pair. The namespace denotes the organization responsible for maintaining the property. Metadata for extensions should be placed in their own namespace to avoid conflicts with the built-in metadata.

Element Attribute metadata properties are:

3. Declaring metadata

Metadata should be declared or parsed during the reporting engine's boot process. If metadata is registered after reports have been parsed, the reporting engine's behaviour is undefined.

The safest way to inject code into the boot process is by writing an reporting-engine extension module.

An OEM can declare attribute metadata by two methods. Either the metadata is declared in an XML file or hard-coded in a Java-Class. Both methods are equally valid and yield the same result, although the XML-declaration tends to be more maintainable.

3.1 Hard-coded attribute metadata

To declare metadata programmatically, you need to add an AttributeMetaData instance with suitable properties to the target element's attribute-registry.

The attribute registry provides access to the attribute definitions of an element and can be retrieved like this:

    final AttributeRegistry registry = ElementTypeRegistry.getInstance().getAttributeRegistry("master-report");

Pentaho reporting comes with a default implementation of the AttributeMetaData interface. You will need to provide a resource-bundle for any localized property. The resource-bundle must be loadable via the standard Java-API call ResourceBundle.getBundle(..).

Our default metadata implementation queries the bundle using a known prefix and a set of well-known entries.

This is an example of an properties-file based resource bundle that contains an attribute declaration using the prefix "attribute.pir.":

    attribute.pir.VERSION.display-name=pir-version
    attribute.pir.VERSION.grouping=internal
    attribute.pir.VERSION.grouping.ordinal=9900
    attribute.pir.VERSION.ordinal=10
    attribute.pir.VERSION.description=
    attribute.pir.VERSION.deprecated=

The recognized attributes are:

The report designer allows users to edit the values of all declared attributes. When you want to use a attribute to bind data from your application onto an report-element, you usually do not want users to see or edit these attributes.

To declare a standard hidden attribute of type 'String', which gets persisted when the report is saved, use the following code:

// the class or resource-name for the resource-bundle that holds all human-readable
// texts. This follows the standard java way of declaring and loading resources.
String bundleLocation = "org.pentaho.reporting.platform.plugin.metadata";

// the prefix for attributes. See above.
String keyPrefix = "attribute.pir.";
// Compatibility version. Needed for compatibility mode. Set this
// to the version of the reporting engine your attribute was first added.
int version = ClassicEngineBoot.computeVersionId(3, 8, 0);

// replace NAMESPACE and ATTR_NAME with your own namespace and name values
DefaultAttributeMetaData metaData = new DefaultAttributeMetaData ("NAMESPACE", "ATTR_NAME", bundleLocation, keyPrefix, String.class, true, version);

// register the new attribute with the master-report element.
AttributeRegistry registry = ElementTypeRegistry.getInstance().getAttributeRegistry("master-report");
registry.putAttributeDescription (metaData);

3.2 Declaring attributes in XML

Instead of coding the registration, it can be easier to declare the metadata via xml-files. The XML-based metadata is parsed at the beginning of the boot-process. The main metadata xml files provides extension points for developers to inject additional attributes.

The xml-based configuration works with conventions around how metadata is declared.

Elements allow to define attributes on the element-tag itself and additionally pull in attribute declarations via attribute-groups. Each element has a attribute group named after its name. For example, to configure attributes for a master-report  element, use the 'master-report' attribute group.

In addition to the per-element groups, the metadata contains logical groups centred around common functions, like fields, rich-text support, etc. that is shared across several elements.

A typical attribute group declaration looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<meta-data xmlns="http://reporting.pentaho.org/namespaces/engine/classic/metadata/1.0">

   <attribute-group name="master-report">
       <attribute namespace="http://reporting.pentaho.org/namespaces/engine/attributes/pentaho/interactive-reporting"
                  namespace-prefix="pir"
                  name="VERSION"
                  mandatory="false"
                  expert="true"
                  hidden="true"
                  value-type="java.lang.String"
                  value-role="Value"
                  compatibility-level="3.8.0"/>
   </attribute-group>
</meta-data>

For attribute metadata declared in XML, the meta system expects localized content in a resource-bundle. The bundle is the same as for element attributes registered via code.

Attribute declarations in a shared group always use the fixed key prefix pattern 'attribute.<ns-prefix>.<name>.' to access properties.Attributes declared on an element declaration use the prefix pattern 'element.<type>.attribute.<ns-prefix>.<name>.' to access properties.
To inject a xml-based attribute-definition into the boot-process, you need to register the file within the module's configuration. A module's configuration is held in the 'configuration.properties' file next to the module class.

If you do not have a module, use the global configuration in the file '/classic-engine.properties', which must be placed in the root of your classpath.

Add the following key, and replace <your-id> with a unique identifier of your chosing.

org.pentaho.reporting.engine.classic.core.metadata.global-includes.<your-id>=res://com/your/company/package/metadata.properties

The configuration above assumes that the metadata is in your classpath in the package "com.your.company.package".