Using Shared Elements

Logi Info, Report 22 May 2009

Developers often find that they're using the same elements or groups of elements repeatedly in multiple report definitions. Report headers and footers are good examples. Rather than adding these elements individually into numerous report definitions, and being faced with maintaining them , developers can instead use shared elements. Shared elements provide an opportunity to create "re-usable code", with its traditional benefit of single instance maintenance. This document discusses shared elements; topics include:

• About Shared Elements
• Creating a Shared Element Definition
• Adding Shared Elements to a Report
• Shared Element Usage Tips

 

About Shared Elements

Shared elements are very simple to create and include in your report definitions. At runtime, the Logi Server Engine evaluates the shared element placeholders you add to your report definitions and inserts the corresponding shared elements before the report HTML is generated.

As "reusable code", any changes made to your shared elements ripple through to every report that uses them, which makes maintenance very easy.

Many of the Sample Applications available on DevNet use shared elements and you can refer to them for implementation examples. Look for a sample app that has a "menu" of links across the top of the page, just below the banner image, such as the Animated Charts sample. The menu links are created using shared elements.

The examples below are from the Template Modifier Files sample application. Please read this document carefully as the words "shared" and "element" appear many times in many ways and can be confusing.

  Back to the top

 

Creating a Shared Element Definition

Using shared elements begins by creating a definition. Shared elements can be defined in any report definition but the recommended practice is to create a separate report definition just to hold shared elements:
 

In the example shown above, a separate definition named "sharedElements" has been created to hold the shared elements. This approach has several benefits, including the possibility of copying the definition file itself to other Logi applications, extending the reusability concept and enforcing consistency.

 

In the sharedElements definition, as shown above, a shared element definition is started by adding a Shared Element element. This is the basic container for one or more elements that you want to share. Be sure to give this element the required unique ID.

A definition file can hold many Shared Element elements, each containing one or more elements to be shared.
 

As shown above, a variety of elements can be added beneath the Shared Element element. These can include any element available for report definitions. In the example, elements have been added to create a common header for several reports.

Your shared elements are now available to any report definition in your application.

   Back to the top

 

Adding Shared Elements to a Report

Adding your shared elements to a report definition is very simple:
 

1. Add an Include Shared Element element to your report definition, as shown above, beneath the Report Header element.
2. Set its Definition File attribute value by selecting the sharedElements definition from the drop-down list of definitions.
3. Set its Shared Element ID attribute value by selecting the sharedHeader definition from the drop-down list of shared elements in the previously selected definition.
4. Set its ID attribute to an arbitrary unique value.

Include Shared Element elements can be added anywhere in your report definition, and the same shared element can be used multiple times in the same definition if necessary.

Repeating steps 1-4 above for every report definition in an application will result in the same header appearing on every report.
 

The resulting report is shown above. The highlighted area at the top is the content created by the shared element.

  Back to the top

 

Shared Element Usage Tips

• Multiple Shared Element elements can be placed in the same definition:
   

The example shown above is from the definition file for the DevNet web site and shows multiple Shared Element elements in a single definition file.

• Style Sheets apply to shared elements in several ways. If the shared elements do not include a style sheet of their own then the style sheet of the definition using the shared elements is applied. If the a style sheet is included as one of the shared elements, then any style classes with the same name in both it and the report definition's style sheet will cascade.
   
• Both the Definition File and Shared Element ID attribute values of the Include Shared Element element can be specified using tokens.
   
• If a shared element definition file becomes very large, it may be useful and may improve performance, to create multiple shared element definition files. Some developers group their shared elements into different definition files based on their function or purpose.
   
• Action.ShowElement cannot be used to show/hide an Include Shared Element element, although use of Division elements can achieve conditional inclusion of shared elements.
   
• Shared elements are embedded into a report definition when the report runs, so any Request parameters that are passed to the report can be used in the shared elements. Similarly, shared elements can work with data from a datalayer in a parent report definition, but they must be in scope; i.e. beneath the chart or table that's the parent of the datalayer. The exception to this is data from LocalData, which can be used throughout the report and shared elements.
   
• Logi Info developers can also use shared elements in Process definitions.

 

  Back to the top