Templates Using Layout Component References

Overview:

Templates can help ensure a consistent look and feel for standard reports built with Report Studio. Creating templates that use Layout Component References can minimize maintenance and allow necessary changes to be automatically reflected in reports that were created using the template.

Caveats:

  • Changing a component reference that is used in other reports will be automatically and immediately reflected in any reports that use it.
  • It is important to test any reports to ensure that template changes appear as expected and intended.

Understanding the Layout Component Reference Tool:

The Layout Component Reference object in the Report Studio toolbox allows a named object from the current report or another report to be referenced so that redundant authoring is minimized. Any changes to the source object will be automatically reflected in references to it.

For example, within a single report spec that has two pages, the header block on the first page can be named and re-used for the second page. Just apply a name property to the source object (the header block on the first page in this example). On the second page, drag in the layout component reference tool into the header. Specify the source as the named block on the first page and there you have it! If the header on the second page needs to be tweaked in some way, say a different title, just name that object in the source and then it can be referenced as an override in the component reference. For example, navigate to the title text object on page 1 and give it a name. Then on the reference object in page 2, click the overrides property and place a check next to that named item so it can be changed on page 2.

When the layout component reference tool is used, it can reference a named object in the same report or a named object in a different report. Referencing an item in a separate report is the method used for the technique described in this article.

Creating a Template - The Component Source Object:

This method is really nothing more than a report spec that can be opened and "saved as" another name. This provides a starting point for report development by having all common elements (headers, images, footers, disclaimer text, whatever) in place with consistent formatting and sizing.

Start by creating a component source report spec. This could have a block for the header. Within that block it may have a table to organize the title text, the date, logos, etc. where each has defined properties for size, font, and so on. The highest level (the block) should be named so it can be referenced later in the template report spec. It should also have the most granular elements named so they can be overridden to suit the needs of each report. Generally the title text would be overriden. So this source object might have a text item that says "Title Text Goes Here" with a name property such as "overrideTitleText".

Using "override" as part of the name makes it easy to find these later when the template is used. You may choose to name other elements even if they are not likely to be overridden if you want to ensure maximum flexibility for your authors. If something should NOT be overridden under any circumstance, don't name it. It is a good practice to name elements at the lowest granular level such as the text object instead of the table cell that contains the text object. This just makes alterations simple.

Once all the objects are created and named, save this spec with a name such as TemplateComponentSource. You might want to create one for portrait layout and another for landscape layout.

Creating a Template - The Template that references the Component Source:

Now create another report spec that has page size, orientation, margins, etc. defined as desired. Drag in a layout component reference from the toolbox into the header. Navigate to the component source report created earlier and reference the header object. Repeat this for any other areas of the report, such as the page footer. If your reports always have a second page in the spec for disclaimer information or a summary of prompt responses that were made when the report runs, create the second page and place the necessary component references there as well.

There is no need to override anything in this report spec. Its purpose is simply to point to the components and define basic page layout and sizing. This spec gets saved and will the starting point for report authors who will open it and "save as" to begin their development.

It is a good idea to save the component source spec and template spec in a folder under the package root. You can secure these so that developers can see just the template but not be allowed to alter it. Controlling template changes is important to ensure that it is done by someone who understands fully how and where the templates are used so that other's work is not adversely affected and so that appropriate testing can be planned.

Using the Template:

An author begins by opening the template report spec (not the component source spec). He or she should save it as a different name in the appropriate location. Click on the component object, say in the header, and then click the override property. A list of all named elements in the component source appears. The author can then check off those that need to be changed, such as the title text. If you named the objects that ought to be overridden with a name that includes the word override, these will be very easy to find.

Once overriden, the author can drag an item from the toolbox on top of the override and do with it as they please. In our title text example, simply dragging a text object from the toolbox on the override and entering the actual report title is all that is needed.

At this point, the author can get down to the real business of authoring by creating the main report content.

Why is this Better than a Manual Approach:

To compare this approach to doing it manually on every report, consider this:

  • Think about the time it would take to specify all the page size/layout properties, drag in objects to create the header, apply fonts, ensure all is lined up and matching to company standards, repeat for footers and other elements.
  • Every developer needs to do this manually for every report. Do you think they'll all be done exactly the same way and have the identical appearance?
  • Now assume the company gets taken over and the logo on all standard reports needs to be changed. Every spec needs to be opened, changed, tested, and migrated. Some of the original developers may have moved on, so someone else may have to make the same change on many reports, each of which is done with a slightly different structure of blocks, tables, etc.
  • Even if a standard object were copy/pasted into reports instead of setting up each one manually, necessary changes would still have to be applied to every report.
  • If the technique described in this article is used, the time it takes to set up the report is a matter of minutes at most.
  • Every report will have the exact same appearance and sizing, achieved in exactly the same manner.
  • When a change is needed, it only needs to be made once in the component source report spec. The only other effort is testing all existing reports and then migrating only the component source spec to subsequent environments.