Tips and tricks

Review this list of tips and tricks for generating reports with Rational® Publishing Engine.

Working in multiple templates

  • You can open multiple templates in the same instance of the Document Studio application. Each template appears as a separate tab in the template content editor.
  • Each template is associated with one document specification. A document specification can have more than one template specified within it.
  • You can copy and paste elements from one template to another if they are opened as tabs within one instance of the Document Studio application. The data applied to the elements is also copied. If the data comes from a source that does not exist in the template you are pasting it into, such as a variable or a data source schema, you are prompted to create it in the second template. When you are copying a query from a schema that has the same name in both templates, but contains different attributes, a second schema is created in the template you are pasting the content into. You cannot copy from one template and paste the elements into a template opened in another instance of the Document Studio application.
    Note: After you copy and paste elements and new data source schemas are added to the template, manually set the Default URI, Configuration required, and Description properties for those data source schemas.

Working with elements

  • Cursor selection

    When you select a Palette element, it remains selected by default in the template content editor until you select a new tool. You can either continue by using this default setting and click the Select element to return to your cursor, or you can change the preference for this setting to disable it. Click Window > Preferences > RPE > Document design and for the Keep current palette tool selected after insertion in template preference, select No.

  • Enter names and descriptions for elements

    If you have a fairly complex template, you can describe each block in the template using Name and Description properties. The name and description fields are empty by default, the name content displays in the template, and the description content can be displayed in the template element hint field. This can help others reuse the template.

  • Editing element content

    You can edit the content for Text, Styled text, Image, Include file, Bookmark, Comment, Template comment, and Hyperlink elements. Double-click the element from the template content editor to open the content editor window for the element.

  • First line of content displays in the template content editor

    By design, only the first line of content entered for elements that use the Content property display in the template content editor. Subsequent lines of text are hidden so that the template designer can focus on the structure of the template at a given time rather than the content of individual elements.

  • Auto-scrolling to place elements
    Because Rational Publishing Engine is an Eclipse application, you can use the auto-scroll feature to place elements into locations in the template that are not visible in the Template Content editor.
    1. Select an element and move your cursor or drag an element into the Template Content editor.
    2. Move the cursor to the top or bottom of the template content editor, depending on which direction you want to scroll.
    3. Pause at the edge of the Template Content editor. The editor begins to scroll.
    4. Move your cursor back into the Template Content editor when the location you want to place the element is visible.
    5. Place or release the element in the template.
  • Incorrect formatting values

    If an incorrect value is entered for a property, the incorrect values are replaced with correct values when possible or ignored during document generation. The Console view also displays a warning containing text such as: Value is not in the list of accepted values. There are two possible reasons for the warning:
    • Some properties have scripted values, which are predefined non-numeric values. For example, the values for the bold property of a text element have the scripted values, true or false. If you enter a number value such as 1, Rational Publishing Engine displays a warning that the script expression cannot be evaluated.
    • Some properties have a predefined range. For example, on the Font tab for the Text properties, the Size value range is 1 - 1638. If a value entered is outside of this defined range such as 1640, then Rational Publishing Engine displays a warning that the value is not in the list of accepted values and is above the accepted maximum value of 1638.
  • Tooltips

    If you hover your cursor on the field for a selected property, a tooltip displays to give you additional information about the permitted values.

  • Merged tables

    In the Microsoft Word and PDF output formats, consecutive tables appear as a single table in the generated output. The columns do not have the same width across these merged tables unless the col width property is set for each of the tables. When tables are merged, it is possible that the same row might display multiple times if the same data is displaying for multiple tables. You can use the once per table property to remove the duplicate rows.

  • Queries

    Reports that have queries on tables might not display the data as you expect. Add queries to rows for consistent display.

    When clearing information from queries, Clear queries and Clear all work differently. Clear queries is only available when you select an element that has a query. Clear all removes all of the queries, attributes, filters, sorts, and conditions on the element you have selected and its child elements, if they also have queries or attributes assigned to them. Master pages, styles, and formatting properties are not removed.

  • Sorts

    Use native sorts whenever possible. Native sorts are more effective and generate documents faster than Rational Publishing Engine sorts.

  • Filters

    Use native filters whenever possible. Native filters are more effective and generate document faster than Rational Publishing Engine filters.

  • Renaming variables

    If you rename a variable, the name is not updated in a script expression or native filter and creates a reference error. When you rename a variable, ensure that you revise the name in the script expressions and native filters as well.

  • Included files
    • Include File elements are handled differently depending on the output format. For PDF, HTML, and XSL-FO outputs, the included file displays as a hyperlink to the document, while for Microsoft Word output, an INCLUDE TEXT field is generated.
    • If you move an included file in the file system, the links used in the templates cannot be resolved. You can run the “Break links” feature (Alt+E+K in Office 2007) in Microsoft Word or run the includeLinkedFiles macro provided with Rational Publishing Engine to fix broken links.

Working with styles

  • Styles are applied in the following order:
    1. Template style sheets, if any
    2. Template styles, if any
    3. The formatting properties you define for the template elements, if any
  • If you find that a style is not being applied as expected, it might be for one of the following reasons:

    • The styles set in the formatting properties might be causing the styles that are applied earlier to be reset.
    • The name of the style might already exist in the Rational Publishing Engine default style sheet. For example, the Title style already exists. The Title style in the default style sheet overrides a style you create and name Title.
  • Multiple methods of styling

    Avoid using more than one of the three methods for applying styles in a template. You might get mixed results in the output and have difficulty troubleshooting. When you must apply additional styling to an element that uses a particular style, apply the customization to a child element. For example, you might want to change the color of a single paragraph that uses a style. Apply the style to the paragraph element and change the color property for the text element that the paragraph contains.
  • Table properties in styles are not supported. Some of the properties set in table styles in *.dot files do not work when processed by Rational Publishing Engine. You can only set resize to fit contents and fixed cell width by setting those properties in the template.

Testing templates

  • Create small input sources for testing

    Create special versions of the input sources and keep changing them to evaluate conditions contained in the templates.

  • Preview large input sources

    Processing of a template is made faster, by limiting the amount of data returned by each query. You can configure the number of data objects per query in the preferences. For example, instead of showing the a complete module with 100 objects, only the first 10 objects are processed.

  • Test multiple input sources individually

    Input sources can be deactivated by, in the document specification, selecting the data source and in the Properties view, set the ignored property to true. Test a template with single input sources first before testing it with all input sources simultaneously.

Generating output

  • Relative paths

    You can use relative paths, HTTP paths , or HTTPS paths to related resources in document specifications. When you use relative paths, you can change the directory structure of your files or move them to the central asset management system and still access the files necessary to generate documents. You are prompted to choose between using relative paths or absolute paths when the document specification is saved, when the template is in the same folder as the document specification, when the template is in a child folder of the folder that contains the document specification, or when the template is in a parent folder of the folder that contains the document specification. You cannot specify a relative path to a parent folder of a parent folder.

  • Previewing data

    From the Document Specification view, you can right-click a data source and select Preview data to see the XML data that will be included in your report before you generate it.


Feedback