genericelement Generic Element Sample Shows how generic elements embedded in reports can be managed at export time by custom handlers. How to implement and use generic elements to embed custom content into reports. 3.1.0 Sanda Zaharia shertage@users.sourceforge.net Generic Elements - Overview

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.
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.

Generic Elements - Schema

Below is the schema of a generic element: 

  
    
  
  
    
      
      
      
    
    
      
        
      
    
    
      
        
      
    
  



  
    
  
  
    
      
        
      
    
    
      
        
      
    
  



  
    
  
  
    
      
        
          Indicates the specific <valueExpression> tag for generic element parameters. 
          Unlike other <valueExpression> elements, it contains a class attribute.
        
        
          
            
	          
            
          
        
      
    
    
      
        
      
    
    
      
        
      
    
  
]]>
In order to be well defined, a generic element must contain:
  • a reportElement definition, like any other JR element
  • a genericElementType - 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:
    • namespace - usually an URI associated with an organization or a product
    • name - the name of the class/type
  • any number of genericElementParameters to store parameter values to be used by the export element handlers to produce the required output in the exported report.
Notice also the evaluationTime and evaluationGroup attributes, with the same meanings as in other JR report elements.

Export Element Handlers

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 GenericElementHandlerBundle as extension type.
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 GenericElementHtmlHandler interface.

Generic Elements Sample

This sample shows how to embed a special HTML snippet into a report to show content coming from a public website. The GenericElementReport.jrxml file contains two generic elements configured to embed specific statistics widgets for the JasperReports project, provided by the ohloh.net site. 

  
  
  
    
  


  
  
  
    
  
]]>
Both generic elements share the same namespace, but they have different names. This means that there are two different types (languages and stats) to be processed at export time using specific export handlers.
In our example both languages and stats types are processed identically, using the same handler, but still depending on the output format. One can see two handler classes in the src/net/sf/jasperreports/ohloh directory:
  • OhlohWidgetHtmlHandler - registered for the HTML output format
  • OhlohWidgetXhtmlHandler - registered for the XHTML output format
To register these handlers, two properties were defined in the jasperreports_extension.properties file:
  • net.sf.jasperreports.extension.registry.factory.jr.statistics=net.sf.jasperreports.extensions.SpringExtensionsRegistryFactory - indicates that the extensions registry factory for jr.statistics is based on the Spring framework.
  • net.sf.jasperreports.extension.jr.statistics.spring.beans.resource=net/sf/jasperreports/ohloh/beans.xml - is pointing to the Spring beans.xml XML bundle.
In the beans.xml file is configured the export handlers bundle associated with the http://jasperreports.sourceforge.net/jasperreports/ohloh namespace: 

  
  
    
      
        
          
            
          
          
            
          
        
      
      
        
          
            
          
          
            
          
        
      
    
  



  



  



  



  



  
]]>
Notice the languages and stats keys in the exporter bundle map, each one providing two different handlers: one for the HTML format, the other for the XHTML format.
Also notice the Spring bean property widgetName defined for all export handlers, in order to store the widget name required at export time.
Further, one can see that net.sf.jasperreports.ohloh.OhlohWidgetHtmlHandler class handles both languages and stats for the HTML output, preparing a <script/> snippet to be included in the generated HTML document, in order to request a specific widget from the ohloh.net site.
The net.sf.jasperreports.ohloh.OhlohWidgetXhtmlHandler class prepares the results for the XHTML output, including additional layout information for the generic element along with the <script/> snippet.

Now it's time go back to generic elements in the JRXML file. The only two parameters required by the ohloh.net 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: 

  
]]>
The widget name parameter is injected as Spring bean property, as shown above.

Running the Sample

Running the sample requires the Apache Ant library. Make sure that ant is already installed on your system (version 1.5 or later).
In a command prompt/terminal window set the current folder to demo/samples/genericelement within the JasperReports source project and run the > ant test view command.
It will generate the HTML and XHTML pages containing the sample report in the demo/samples/genericelement/build/reports directory.
Then the report will open in the JasperReports internal viewer.