...
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:
property | description |
|---|---|
name | A internal name, used to retrieve metadata from the registry |
namespace | A internal namespace, used to retrieve metadata from the registry. The name and namespace is also needed by the API. |
target-type | The expected target type for the attribute. This is the name of a Java-Class. This is a hint used when parsing and writing PRPT files. |
display-name | The display-name is used to name the attribute in the user-interface. This property is localized. |
description | The description is used to describe the attribute in the user-interface. Use the description to provide text for tool-tips. This property is localized. |
grouping | The grouping property organizes attributes and includes them in a logical grouping of similar attributes. The Pentaho Report Designer uses grouping in the user-interface to make large number of attributes more accessible. |
ordinal, grouping-ordinal | Ordinals are numeric properties that define the order of properties and groups. Although they are stored in the resource bundle, they should not be localized. Grouping ordinals must be the same for the same group-localization, as the grouping text as well as the grouping ordinal are used for it. |
deprecated | Deprecation is a mechanism to mark properties are obsolete. These properties will go away in the future. We mark properties as deprecated if their meaning is fundamentally broken and cannot be safely fixed. Use the deprecated-message property to give an explanation for the user. |
expert | A flag indicating that the feature is for advanced users. The Report Designer can filter expert options out. |
preferred | A flag marking common properties that should be highlighted to make them stand out to the user. |
hidden | A flag indicating that the properties should never be shown to the user. This is usually an internal property. |
experimental | A flag indicating that the property or feature is not supported. It is part of the code to test it out or to deliver it to the community. Such features may change at any time and we do not guarantee their existence or backward compatibility. |
mandatory | A flag indicating that the property must have a value and cannot be <null>. |
computed | A flag indicating that the property is computed by the system and therefore the value assigned can be lost at any time. |
transient | A flag indicating that the property should be omitted from serialization and writing into a PRPT file. This is usually combined with the computed property. |
bulk | A flag indicating that the attribute contains large data and should be written as CDATA-element instead of XML-attribute. This does not affect the runtime, but marking properties as bulk can help make PRPT contents easier to debug. |
design-time-value | A flag indicating that the attribute is only modified in the design-time tools. A design-time property does not have attribute-expressions. |
property-editor | Specifies the class that implements a custom property editor. Property editors allow the report-designer to specify how values are presented to the user. |
value-role | A design-time hint for string-attributes. The value role can be one of "Value", "Resource", "Content", "Field", "Group", "Query", "Message", "Bundle-Key", "Bundle-Name", "Name", "ElementName", "DateFormat", "NumberFormat". |
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.":
...
| Code Block |
|---|
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=
{code}
|
The
...
recognized
...
attributes
...
are:
...
name | description |
|---|---|
display-name |
...
a |
...
human-readable |
...
name |
...
for |
...
display |
...
in |
...
the |
...
user |
...
interface |
...
of |
...
design-tools |
...
grouping | a human-readable |
...
name |
...
for |
...
groupings. |
...
All |
...
group |
...
elements |
...
must |
...
share |
...
the |
...
same |
...
name |
...
to |
...
be |
...
considered |
...
part |
...
of |
...
the |
...
same |
...
group. |
...
grouping.ordinal |
...
an |
...
numeric |
...
ordinal |
...
to |
...
define |
...
the |
...
group's |
...
display |
...
order. |
...
This |
...
is |
...
relative |
...
to |
...
all |
...
other |
...
groups |
...
within |
...
the |
...
same |
...
element. |
...
ordinal | an numeric ordinal to define the attribute's |
...
display |
...
order |
...
in |
...
the |
...
UI. |
...
This |
...
value |
...
is |
...
relative |
...
to |
...
all |
...
other |
...
attributes |
...
within |
...
the |
...
same |
...
group |
...
within |
...
the |
...
same |
...
element. |
...
description | A human-readable |
...
description, |
...
usually |
...
used |
...
for |
...
tool-tips. |
...
deprecated | (Only |
...
applicable |
...
if |
...
the |
...
attribute |
...
is |
...
marked |
...
'deprecated'): |
...
A |
...
human-readable |
...
message |
...
describing |
...
the |
...
reason |
...
for |
...
deprecating |
...
the |
...
element |
...
and |
...
details |
...
on |
...
which |
...
attribute |
...
or |
...
method |
...
should |
...
be |
...
used |
...
instead. |
               Â
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:
| Code Block |
|---|
// 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. 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 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); {code} h2. |
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:
...
| Code Block |
|---|
<?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" expert="true" hidden="true" value-type="java.lang.String" " value-role="Value" "Value" compatibility-level="3.8.0"/> </attribute-group> </meta-data> {code} |
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.
...
| Code Block |
|---|
org.pentaho.reporting.engine.classic.core.metadata.global-includes.<your-id>=res://com/your/company/package/metadata.properties{code}
|
The
...
configuration
...
above
...
assumes
...
that
...
the
...
metadata
...
is
...
in
...
your
...
classpath
...
in
...
the
...
package
...
"com.your.company.package".