#
BIRT Report Item Extension Point

###### Identifier:

org.eclipse.birt.model.reportItemModel

###### Since:

1.0

###### Description:

Report Item extension point allows the user to specify how the new report item should be represented and persisted in the ROM

###### Configuration Markup:

<!ELEMENT extension (reportItem)>

<!ATTLIST extension

point CDATA #REQUIRED

id CDATA #IMPLIED

name CDATA #IMPLIED>

<!ELEMENT reportItem (property* , propertyGroup* , styleProperty* , method* , propertyVisibility* , style?)>

<!ATTLIST reportItem

extensionName CDATA #REQUIRED

defaultStyle CDATA #IMPLIED

isNameRequired (true | false)

class CDATA #REQUIRED

displayNameID CDATA #IMPLIED>

Element definition

- extensionName - Internal unique name of the element
- defaultStyle - Predefined style to be used for the Report Item.
- isNameRequired - Field to indicate if the ReportItem instance name is required.
- class - Name of the java class, that implements the IReportItemFactory interface.
- displayNameID - Resource key for display name

<!ELEMENT styleProperty EMPTY>

<!ATTLIST styleProperty

name CDATA #REQUIRED>

- name -

<!ELEMENT property (choice*)>

<!ATTLIST property

name CDATA #REQUIRED

displayNameID CDATA #IMPLIED

type (string|number|integer|dimension|color|choice|boolean|expression|html|messageId|style|dataSet|points|uri|dateTime|xml|name|extends|dataSource|float|element|column)

canInherit (true | false) "true"

detailType CDATA #IMPLIED

defaultValue CDATA #IMPLIED

isEncryptable CDATA #IMPLIED

defaultDisplayName CDATA #IMPLIED>

- name -
- displayNameID -
- type -
- canInherit -
- detailType -
- defaultValue -
- isEncryptable - The flag indicating whether this property is encrypted.
- defaultDisplayName - The default display name, which is used if no localized display name is found with I18N.

<!ELEMENT propertyGroup (property+)>

<!ATTLIST propertyGroup

displayNameID CDATA #IMPLIED

name CDATA #REQUIRED

defaultDisplayName CDATA #IMPLIED>

- displayNameID -
- name -
- defaultDisplayName - The default display name, which is used if no localized display name is found with I18N.

<!ELEMENT method (argument)*>

<!ATTLIST method

name CDATA #REQUIRED

displayNameID CDATA #IMPLIED

toolTipID CDATA #IMPLIED

returnType CDATA #IMPLIED

isStatic (true | false) "false"

context CDATA #IMPLIED>

- name -
- displayNameID -
- toolTipID -
- returnType -
- isStatic -
- context -

<!ELEMENT argument EMPTY>

<!ATTLIST argument

name CDATA #REQUIRED

type CDATA #IMPLIED

tagID CDATA #IMPLIED>

- name -
- type -
- tagID -

<!ELEMENT choice EMPTY>

<!ATTLIST choice

name CDATA #REQUIRED

value CDATA #IMPLIED

displayNameID CDATA #IMPLIED

defaultDisplayName CDATA #IMPLIED>

- name -
- value -
- displayNameID -
- defaultDisplayName - The default display name, which is used if no localized display name is found with I18N.

<!ELEMENT propertyVisibility EMPTY>

<!ATTLIST propertyVisibility

name CDATA #REQUIRED

visibility CDATA #IMPLIED>

To set the visible level of this property when it is shown in the property sheet.

- name -
- visibility - Two options are: hide, readonly.

<!ELEMENT style EMPTY>

<!ATTLIST style

name CDATA #REQUIRED

displayNameID CDATA #IMPLIED>

Extension element default style -- selector.

- name -
- displayNameID -

###### Examples:

The following is an example of the Report Item extension.

    <extension point="org.eclipse.birt.report.engine.reportitemPresentation">

    <reportItem
     class="org.eclipse.test.ReportItemFactoryImpl"
     isNameRequired="true"
     extensionName="TestingMatrix"
     displayNameID="Element.TestingMatrix">

    <property
      defaultValue="default test&amp;&quot;&lt;"
      type="string"
      displayNameID="Element.TestingMatrix.test1"
      name="test1"/>
    <property type="integer"
      displayNameID="Element.TestingMatrix.test2"
      canInherit="false"
      name="test2"/>
    <property
         displayNameID="Element.TestingMatrix.test3"
         name="test3"
         type="xml"/>
    <property type="choice"
      displayNameID="Element.TestingMatrix.test5"
      canInherit="false"
      name="test5">
      <choice value="one"
       displayNameID="Choices.test5.choice1"
       name="choice1"/>
      <choice value="two"
       displayNameID="Choices.test5.choice2"
       name="choice2"/>
      <choice value="three"
       displayNameID="Choices.test5.choice3"
       name="choice3"/>
    </property>
    <propertyGroup name="group1"
      displayNameID="Element.TestingMatrix.group1">
      <property type="string"
       displayNameID="Element.TestingMatrix.test6"
       name="test6"/>
      <property type="integer"
       displayNameID="Element.TestingMatrix.test7"
       name="test7"/>
    </propertyGroup>
      <propertyVisibility name="bookmark" propertyVisibility="hide"/>
      <propertyVisibility name="InvalidProperty" propertyVisibility="hide"/>
      <propertyVisibility name="dataSet" propertyVisibility="readonly"/>
      <propertyVisibility name="test3" propertyVisibility="hide"/>
    </reportItem>
    </extension>

###### API Information:

If the extended Report Item stores properties in its own model; i.e its own way of storing data then it must satisfy the following requirements
- serialize/deserialize as part of the report design file
- support undo/redo
- support generic property sheet
In order to acheive this, the report item extension must implement some of the interfaces defined in the org.eclipse.birt.report.model.api.extension package. See the package's JavaDoc documentation and API interfaces for more information.
The classes/interfaces to be extend/implement are:
- ReportItem ( required )
- ReportItemFactory ( required )
- ElementCommand ( optional, extend this class to suport undo/redo operation ). Extend ElementCommand class and integrate with the command stack in the IReportItem::setProperty() method implementation
- IPropertyDefinition, IChoiceDefinition ( optional, implement this class to integrate with the generic property sheet in the designer )
- IMessages ( optional, implement this class to support externalized strings )

###### Supplied Implementation:

The plugin org.eclipse.birt.chart.reportitem, supplied with the BIRT installation, provides a good example for implementing an report item extension.

Copyright (c) 2005 Actuate Corporation. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html
Contributors: Actuate Corporation - initial API and implementation