A document template defines the structure, layout, and
content of a report. Creating a successful template requires planning,
developing, testing, and storing the template.
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.
Determine the number of templates needed given these requirements.
You can name and describe each template block in the metadata attributes.
The name content displays in the template, and the description content
displays in the template element hint field.
- Viewing context
- How will someone view this document?
- Will it be printed? Viewed on screen? Both?
- Will it be run in an integrated product?
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.
4: Store the template
- Save the developed and tested templates on a central file server.
You can use the Central Management component as a storage location.
- 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):