Designing document templates
A document template defines the structure, layout, and
content of a report. Creating a successful template requires planning,
developing, testing, and storing the template.
Procedure
If you are providing the template for use in an integrated application, see the Creating reports for use in integrated applications scenario.
Supporting
concepts
- Getting started with Rational Publishing Engine: Reporting roles and responsibilities in Rational® Publishing Engine
To create a document template, complete the following
steps:
1: Gather requirements
Different needs require different designs. Determine the business needs and practical requirements of the document before you start designing your template(s).
- Data elements
- There are a variety of template elements that display different
types of information. What information is required by the person(s)
who will be viewing the document? Once you know that, you can start
to determine data elements:
- Which template elements display that data? What will it look like in the final document?
- Is there more than one way to display the information? If so, which display is best suited to the context in which the document will be viewed?
- How much data is necessary? You might be able to filter out unnecessary data, which can save time when generating the report output.
- Output type
- Consider which output type would best serve the needs of the person(s) who will be viewing the document. The template you design might look different when it is generated into different output types. Some elements are optimized for displaying in a particular format, and some are not supported in certain formats. Familiarize yourself with the way template elements are displayed in different output formats. This allows you to select elements and output type that work best together.
- One template vs. many templates
- Is this a single-use template or could you reuse some of the pieces in other templates?
- One template: You can use one template to contain all the different portions of the document design. This means that everything is in one place and no merging is required.
- Many templates: You can use a modular approach, creating multiple templates that can then be merged together to create a complete document. For example, you can have a table of contents template, front cover template, data template, index template and back cover template. These templates can be reused in generating different documents.
- Viewing context
- How will someone view this document?
- Will it be printed? Viewed on screen? Both?
- Will it be run in an integrated product?
Supporting concepts
2: Design a template
When designing a template, the following tactics can help you use your time efficiently.- Implement the overall structure of the template using a top-down approach. Start with the most general elements and then incrementally narrow down to the details.
- Validate data generation before focusing on formatting details. If you spend a lot of time formatting and then discover that your data is not generating correctly, you might have to reformat. See 3. Test the template for details.
- Polish the details and add more detailed requirements one by one. Leave less important details or difficult ones to implement later. Consider the relevance of requirements that are difficult to realize, like you would in a cost-benefit analysis.
- Consider using scripts to extract information into a format that Rational Publishing Engine can efficiently consume.
- A template can be designed to provide specific page layout properties, such as the page size, orientation, margins, number of columns, and styles for the types of paragraphs that are most likely to be used in documents.
- A template can contain:
- Document structure elements, such as paragraphs, tables, lists, and a table of contents.
- Document layout blocks, such as master pages, style sheets, headers, and footers.
- Internal and external user defined styles, such as text or paragraph formatting. Text formatting includes bold, italic, underline, font size, and font color. Paragraph formatting includes margins, borders, indentation, and scripting parameters in the form of JavaScript.
- Embedded template content, such as images, static text, and references to static files and style sheets.
- Data elements, such as attributes, conditions, and dynamic data elements.
- Data extraction in the form of queries and filters.
- External variables that receive values at run time and internal variables that are used for calculations. Creating external variables is preferable to hardcoding data source URLs in your template. If you hardcode URLs and the server name changes, then you must update the URLs in every template. With external variables, you can override the URLs at run time. For templates that are embedded in other products, use the special variables that are recognized by those products when they are referencing data.
- Start Document Studio.
- Create a new template, from scratch or based on an existing template.
- Add the data source schema.
- Add elements.
- Add formatting to elements.
- Define dynamic content.
- Optional: Refine the data with filters, sorts, or conditions.
3: Test the template
- Testing is done incrementally during development. Save often and save with unique names. Verify the output frequently using a small set of test data. Do not add more elements until what you already have is working.
- After developing most of the document, perform load testing to check for performance issues. Use the Preview tool to limit the size of the data being used. The generated report is still accurate, but runs more quickly because the default maximum records per query that Rational Publishing Engine retrieves is 10 records. When testing conditions, it is possible that no record from the first 10 matches the condition. In this case, use the Run tool instead of the Preview tool or change the value for the maximum records per query in the Preferences.
- Test the template in different output formats. You might find that one output type does not display your template as well as another output type.
- Run the verification tool.
- Generate a preview.
Supporting task:
4: Store the template
- Save the developed and tested templates in Document Builder.
- Make sure to provide some information in the template metadata so others know how to reuse the template. Some sample data and sample document specification information for the project data helps in effectively reusing these templates.
Next steps
After you have created and tested the template(s):- Optional: Create and consolidate additional templates. Repeat steps 2-4 for any additional templates that you need to create, then merge them.
- Define document configurations
- Create archives
- Publish documents