Tips and tricks
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 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 elementsBecause 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.
- Select an element and move your cursor or drag an element into the Template Content editor.
- Move the cursor to the top or bottom of the template content editor, depending on which direction you want to scroll.
- Pause at the edge of the Template Content editor. The editor begins to scroll.
- Move your cursor back into the Template Content editor when the location you want to place the element is visible.
- 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:
- Template style sheets, if any
- Template styles, if any
- 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.
Searching within a template
- Customizing the Search window
In Document Studio, click to open the Search window. The use of the File Search and JavaScript Search tabs is not supported. You can click Customize and deselect the RPE Reference Search or JavaScript Search tabs to remove them from the Search window.
- Locating a query or attribute in the Data Source View from the template content editor
You can locate a query or attribute in the Data Source View from the element it is applied to by right-clicking an element and selecting . The Data Source View opens and the query or attribute is highlighted.
- Searching for data references in an element
You can search for a list of queries and attributes by right-clicking an element and selecting . The Search view opens and a list of queries and attributes displays. You can double-click a query or attribute in the results to edit its content.
- Searching for variable assignments in an element
You can search for a list of variable assignments used in an element by right-clicking the element the variable is assigned to and selecting . The Search view opens and a list of variable assignments displays. You can double-click a variable assignment in the results to edit it.
- Searching for all references in an element
You can search for a list of variable assignments, attributes, and queries used in an element by right-clicking an element and selecting . The Search view opens and a list displays. You can double-click an item in the results to edit it.
- Searching for query or attribute references in a template
You can search for a list of elements that use a specific query or attribute in a template by right-clicking the query or attribute in the Data Source View and selecting Search data references. The Search view opens and a list of occurrences displays. You can double-click an occurrence in the results to edit it.
- Customizing the Search view
After you perform a search, you can click a column heading to sort the results.
- Search resultsThe search results display in the Search view. The results include the following columns:
- Result value: The name as entered in the Properties view for the entity.
- Search type: The search type match as selected in step 4. Data source includes both queries and attributes.
- Element: The element type as selected from the Palette view.
- Used in: The location of the entity, which might be in the element content, condition, variable assignment, or properties.
- Element name: The name as entered in the General tab of the Properties view for the element.
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.