<?xml version="1.0" encoding="UTF-8"?>

<sample>

  <name>genericelement</name>
  <title>Generic Element Sample</title>
  <description>Shows how generic elements embedded in reports can be managed at export time by custom handlers.</description>

  <mainFeature ref="genericelements"/>
  
  <!-- genericelements -->
  
  <feature name="genericelements" title="Generic Elements">
    <description>
How to implement and use generic elements to embed custom content into reports.
    </description>
    <since>3.1.0</since>
    <documentedBy>
      <author>
    	<name>Sanda Zaharia</name>
    	<email>shertage@users.sourceforge.net</email>
      </author>
    </documentedBy>
    <content>
<subtitle name="overview">Generic Elements - Overview</subtitle>
<br/>
<br/>
Generic elements are built-in placeholders to be declared in a report template at report design time, in order to reserve space for 
special content available only at export time, generated in a specific manner by different exporters. At report filling time generic 
elements are processed into generic print elements that reserve room for their future content and evaluate report element expressions. 
Expression results will be stored as parameter values in the generic print element.
<br/>
The necessity of generic elements comes from the fact that some output formats do provide dedicated support for embedding various 
objects that are not available in the JasperReports built-in elements gallery. Such an example is the case of embedding Flash 
movies in reports when they are exported to HTML format. JasperReports deals naturally with displaying text, shapes and images, 
but there is no built-in element for displaying Flash movies. When exporting to HTML, the empty space reserved by the generic element 
can be filled with specific Flash movie content generated by the HTML export handler registered for Flash movies type.
<br/>
<br/>
<subtitle name="schema">Generic Elements - Schema</subtitle>
<br/>
<br/>
Below is the schema of a generic element:
<pre><![CDATA[
<element name="genericElement">
  <annotation>
    <documentation></documentation>
  </annotation>
  <complexType>
    <sequence>
      <element ref="jr:reportElement"/>
      <element ref="jr:genericElementType"/>
      <element ref="jr:genericElementParameter" minOccurs="0" maxOccurs="unbounded"/>
    </sequence>
    <attribute name="evaluationTime" use="optional" default="Now" type="jr:complexEvaluationTime">
      <annotation>
        <documentation></documentation>
      </annotation>
    </attribute>
    <attribute name="evaluationGroup" type="string" use="optional">
      <annotation>
        <documentation></documentation>
      </annotation>
    </attribute>
  </complexType>
</element>

<element name="genericElementType">
  <annotation>
    <documentation></documentation>
  </annotation>
  <complexType>
    <attribute name="namespace" type="string" use="required">
      <annotation>
        <documentation></documentation>
      </annotation>
    </attribute>
    <attribute name="name" type="string" use="required">
      <annotation>
        <documentation></documentation>
      </annotation>
    </attribute>
  </complexType>
</element>

<element name="genericElementParameter">
  <annotation>
    <documentation></documentation>
  </annotation>
  <complexType>
    <sequence>
      <element name="valueExpression" minOccurs="0" maxOccurs="1">
        <annotation>
          <documentation>Indicates the specific <code>&lt;valueExpression&gt;</code> tag for generic element parameters. 
          Unlike other <code>&lt;valueExpression&gt;</code> elements, it contains a <code>class</code> attribute.</documentation>
        </annotation>
        <complexType mixed="true">
          <attribute name="class" type="string" use="optional" default="java.lang.Object">
            <annotation>
	          <documentation></documentation>
            </annotation>
          </attribute>
        </complexType>
      </element>
    </sequence>
    <attribute name="name" type="string" use="required">
      <annotation>
        <documentation></documentation>
      </annotation>
    </attribute>
    <attribute name="skipWhenNull" type="boolean" use="optional" default="false">
      <annotation>
        <documentation></documentation>
      </annotation>
    </attribute>
  </complexType>
</element>]]></pre>
In order to be well defined, a generic element must contain:
<ul>
<li>a <code>reportElement</code> definition, like any other JR element</li>
<li>a <code>genericElementType</code> - that identifies the class/type the generic element belongs to. Export element handlers 
are registered with generic element types, in order to handle uniformly elements of the same type. Types are characterized by:
<ul>
<li><code>namespace</code> - usually an URI associated with an organization or a product</li>
<li><code>name</code> - the name of the class/type</li>
</ul></li>
<li>any number of <code>genericElementParameter</code>s to store parameter values to be used by the export element handlers 
to produce the required output in the exported report.</li>
</ul>
Notice also the <code>evaluationTime</code> and <code>evaluationGroup</code> attributes, with the same meanings as in other JR 
report elements.
<br/>
<br/>
<subtitle name="handlers">Export Element Handlers</subtitle>
<br/>
<br/>
Export element handlers provide the mechanism able to generate specific content associated with a given generic element type at 
export time. Usually handlers that share the same type namespace are packed together in a handler bundle. Handler bundles are 
deployed as JasperReports extensions, using the 
<api href="net/sf/jasperreports/engine/export/GenericElementHandlerBundle.html">GenericElementHandlerBundle</api> 
as extension type.
<br/>
Generic element handlers are also specific to a report exporter. Currently only the HTML exporter features support for generic 
elements. A generic element handler that has to be used for the HTML exporter would implement the 
<api href="net/sf/jasperreports/engine/export/GenericElementHtmlHandler.html">GenericElementHtmlHandler</api> interface.
<br/>
<br/>
<subtitle name="sample">Generic Elements Sample</subtitle>
<br/>
<br/>
This sample shows how to embed a special HTML snippet into a report to show content coming from a public website. The 
<code>GenericElementReport.jrxml</code> file contains two generic elements configured to embed specific statistics 
widgets for the JasperReports project, provided by the <a href="http://ohloh.net" target="_blank">ohloh.net</a> site.
<pre><![CDATA[
<genericElement>
  <reportElement x="0" y="100" width="400" height="200" style="widget1"/>
  <genericElementType namespace="http://jasperreports.sourceforge.net/jasperreports/ohloh" name="languages"/>
  <genericElementParameter name="ProjectID">
    <valueExpression class="java.lang.Integer"><![CDATA[$P{JRProjectID}]] ></valueExpression>
  </genericElementParameter>
</genericElement>
<genericElement>
  <reportElement x="420" y="100" width="400" height="200"/>
  <genericElementType namespace="http://jasperreports.sourceforge.net/jasperreports/ohloh" name="stats"/>
  <genericElementParameter name="ProjectID">
    <valueExpression class="java.lang.Integer"><![CDATA[$P{JRProjectID}]] ></valueExpression>
  </genericElementParameter>
</genericElement>]]></pre>
Both generic elements share the same <code>namespace</code>, but they have different names. This means that there are two 
different types (<code>languages</code> and <code>stats</code>) to be processed at export time using specific export handlers.
<br/>
In our example both <code>languages</code> and <code>stats</code> types are processed identically, using the same handler. One can see the handler class in the <code>src/net/sf/jasperreports/ohloh</code> directory:
<ul>
<li><code>OhlohWidgetHtmlHandler</code> - registered for the HTML output format</li>
</ul>
To register these handlers, two properties were defined in the <code>jasperreports_extension.properties</code> file:
<ul>
<li><code>net.sf.jasperreports.extension.registry.factory.jr.statistics=net.sf.jasperreports.extensions.SpringExtensionsRegistryFactory</code> - 
indicates that the extensions registry factory for <code>jr.statistics</code> is based on the Spring framework.</li>
<li><code>net.sf.jasperreports.extension.jr.statistics.spring.beans.resource=net/sf/jasperreports/ohloh/beans.xml</code> - 
is pointing to the Spring <code>beans.xml</code> XML bundle.</li>
</ul>
In the <code>beans.xml</code> file is configured the export handlers bundle associated with the <code>http://jasperreports.sourceforge.net/jasperreports/ohloh</code> 
namespace:
<pre><![CDATA[
<bean id="ohlohExportHandlerBundle" 
    class="net.sf.jasperreports.engine.export.DefaultElementHandlerBundle">
  <property name="namespace" value="http://jasperreports.sourceforge.net/jasperreports/ohloh"/>
  <property name="elementHandlers">
    <map>
      <entry key="languages">
        <map>
          <entry key="net.sf.jasperreports.html">
            <ref bean="languagesHtmlExportHandler"/>
          </entry>
        </map>
      </entry>
      <entry key="stats">
        <map>
          <entry key="net.sf.jasperreports.html">
            <ref bean="statsHtmlExportHandler"/>
          </entry>
        </map>
      </entry>
    </map>
  </property>
</bean>

<bean id="baseHtmlExportHandler" class="net.sf.jasperreports.ohloh.OhlohWidgetHtmlHandler"
    abstract="true">
  <property name="projectIDParameter" value="ProjectID"/>
</bean>

<bean id="languagesHtmlExportHandler" class="net.sf.jasperreports.ohloh.OhlohWidgetHtmlHandler"
    parent="baseHtmlExportHandler">
  <property name="widgetName" value="project_languages"/>
</bean>

<bean id="statsHtmlExportHandler" class="net.sf.jasperreports.ohloh.OhlohWidgetHtmlHandler"
    parent="baseHtmlExportHandler">
  <property name="widgetName" value="project_basic_stats"/>
</bean>]]></pre>
Notice the <code>languages</code> and <code>stats</code> keys in the exporter bundle map, each one providing a handler for the HTML format. 
<br/>
Also notice the Spring bean property <code>widgetName</code> defined for all export handlers, in order to store the widget name required 
at export time.
<br/>
Further, one can see that 
<code>net.sf.jasperreports.ohloh.OhlohWidgetHtmlHandler</code> class handles both <code>languages</code> and <code>stats</code> for the 
HTML output, preparing a &lt;script/&gt; snippet to be included in the generated HTML document, in order to request a specific widget from 
the <a href="http://ohloh.net" target="_blank">ohloh.net</a> site.
<br/>
<br/>
Now it's time go back to generic elements in the JRXML file. The only two parameters required by the <a href="http://ohloh.net" target="_blank">ohloh.net</a> 
site in order to process the requested statistics, are the project ID and the widget name. Therefore, both generic elements in the JRXML contain the following generic 
element parameter:
<pre><![CDATA[
<genericElementParameter name="ProjectID">
  <valueExpression class="java.lang.Integer"><![CDATA[$P{JRProjectID}]] ></valueExpression>
</genericElementParameter>]]></pre>
The widget name parameter is injected as Spring bean property, as shown above. 
<br/>
<br/>
<b>Running the Sample</b>
<br/>
<br/>
Running the sample requires the <a href="http://ant.apache.org/">Apache Ant</a> library. Make sure that <code>ant</code> is already installed on your system (version 1.5 or later).
<br/>
In a command prompt/terminal window set the current folder to <code>demo/samples/genericelement</code> within the JasperReports source project and run the <code>&gt; ant test view</code> command.
<br/>
It will generate the HTML pages containing the sample report in the <code>demo/samples/genericelement/build/reports</code> directory. 
<br/>
Then the report will open in the JasperReports internal viewer.
    </content>
  </feature>

</sample>
