Proven Practice

Ensuring consistent object

alignment in HTML and PDF
outputs
Product(s): IBM Cognos 8
Area of Interest: Reporting

Ensuring consistent object alignment in HTML and PDF outputs

Copyright
Copyright 2008 Cognos ULC (formerly Cognos Incorporated). Cognos ULC
is an IBM Company. While every attempt has been made to ensure that the
information in this document is accurate and complete, some typographical
errors or technical inaccuracies may exist. Cognos does not accept
responsibility for any kind of loss resulting from the use of information
contained in this document. This document shows the publication date. The
information contained in this document is subject to change without notice.
Any improvements or changes to the information contained in this document
will be documented in subsequent editions. This document contains
proprietary information of Cognos. All rights are reserved. No part of this
document may be copied, photocopied, reproduced, stored in a retrieval
system, transmitted in any form or by any means, or translated into another
language without the prior written consent of Cognos. Cognos and the
Cognos logo are trademarks of Cognos ULC (formerly Cognos Incorporated)
in the United States and/or other countries. IBM and the IBM logo are
trademarks of International Business Machines Corporation in the United
States, or other countries, or both. All other names are trademarks or
registered trademarks of their respective companies. Information about
Cognos products can be found at www.cognos.com
This document is maintained by the Best Practices, Product and Technology
team. You can send comments, suggestions, and additions to
cscogpp@ca.ibm.com .

IBM Cognos Proprietary Information

Ensuring consistent object alignment in HTML and PDF outputs

Contents

INTRODUCTION .......................................................................................4

1.1

Purpose ........................................................................................................................................4

1.2

Applicability................................................................................................................................4

1.3

Exclusions and Exceptions .........................................................................................................4

GENERAL AUTHORING TIPS..................................................................5

RULES OF PRACTICE .............................................................................8

APPENDIX A.................................................................................................12
Cascading Style Sheets, level 2 CSS2 Specification ........................................................................... 12

IBM Cognos Proprietary Information

Ensuring consistent object alignment in HTML and PDF outputs

1 Introduction
1.1

Purpose
The purpose of this document is to provide guidelines when authoring reports
to align report objects such as lists, crosstabs and tables to render
consistently in PDF as well as HTML formats.

1.2

Applicability
The content of this document is derived from testing in IBM Cognos 8.2, but
is based on standard rendering rules for PDF and HTML, and can be applied
to earlier versions of IBM Cognos 8 and IBM Cognos ReportNet.

1.3

Exclusions and Exceptions

Since ReportNet was not used for testing, some features described within this
document may not be available, or may behave slightly differently.

IBM Cognos Proprietary Information

Ensuring consistent object alignment in HTML and PDF outputs

2 General Authoring Tips

The following are general suggestions to keep in mind when authoring
reports with complex layouts, most of which applies to all report creation, but
is especially relevant in such cases where troubleshooting becomes difficult.
2.1.1 Create a query that uses one query container where possible.
Attempt to author the result set into a single query using one query container, in
stead of aligning multiple containers. This could be easily accomplished with
crosstabs in IBM Cognos 8. With Lists, an explicitly union can be applied.

2.1.2 Avoid unnecessary nesting of tables / blocks within tables.

These can unexpectedly add to the width or height alignment if the padding or
border properties are not set consistently for these containers.
Use a single table and merge cells when necessary along the horizontal axis for
alignment purposes
Note: Blocks can truncate data when rendered in PDF, as the overflow handling
within a block cannot display usable scrollbars in PDF output.

2.1.3 Apply styles (width / height / font) properties to parent objects

instead of lower-level items (children).
For example, use the List Column Body Style property instead of unlocking the layout
and applying font settings to each individual text item within the List. Define a
column width at the column title and column body rather than within the cell
properties of a header or footer.

2.1.4 Keep row count & order constant

Horizontal alignment of multiple query containers require that the same number of
rows and data order be maintained. The number of rows depends on the filters used
and modelling of the data (i.e. all fact tables must contain the same matching
records). The data order should be controlled using Advanced Sorting for Relational
queries and the order() function for dimensional queries.

2.1.5 Develop and test to make sure that data in the unformatted report
is correct before altering the layout.
Troubleshooting incorrect results is made more difficult when the report contains
complex layout/formatting "on top of" the results.

IBM Cognos Proprietary Information

Ensuring consistent object alignment in HTML and PDF outputs

2.1.6 Increase the report complexity gradually (phased approach), with

frequent testing in all required output formats.
Its much easier to make incremental adjustments along the way. Developing /
testing a complex layout in just one output type is very hard to fix if problems were
introduced along the way (as is often the case with HTML and PDF output).

2.1.7 Document steps

Keep record of the steps taken in order to create a repeatable best practice, given
the individual layout requirements for each organization. This will save much time in
future when similar reports are being constructed.

2.1.8 Create report templates, once the basic building blocks are in place.

IBM Cognos Proprietary Information

Ensuring consistent object alignment in HTML and PDF outputs

2.1.9 Information on the property Collapse Borders:

When this property is checked, the border of a cell will be absorbed into the border
of the next cell, affecting the total height / width of objects.
HTML example: If a row has a height of 20 pixels, and a border of 1 pixel, the total
row height will be 20 pixels, and the white space inside will be 18 pixels (1 pixel
border on top and bottom).
When another row is added, the white space in the first row will increase in height by
1 pixel, as its border is collapsed into the next row. Thus the last row will always be
slightly smaller, but negligible to the naked eye.
Calculation example for the image of HTML output below:

Top border = 1 px
1st row White space = 19 px
Center border = 1 px
2nd row White space = 18 px
Bottom border = 1 px
Total height = 40 px.
It is important to understand this behaviour when stacking 2 (or more) separate
tables on the left, for example, and aligning them with 1 object on the right, as the
HTML output on the left will appear shorter than on the right side.
This does not happen for PDF output - all rows are equal in white space. Using the
example table object, the result on PDF will be 1 px larger than specified, as the
border at the bottom will be pushed out. The total height will thus be 41 pixels in
PDF, and 40 pixels in HTML.

IBM Cognos Proprietary Information

Ensuring consistent object alignment in HTML and PDF outputs

3 Rules of Practice
3.1.1 RULE #1: For PDF output, do not use percentage sizes for width /
height.
Always specify size in pixels, or fixed measure units. If percentage sizing for HTML
output is a critical requirement, use conditional layouts based on the output format to
generate one layout for PDF and one for HTML.

3.1.2 RULE #2: Do not use Box Type of None to hide elements.
When elements must be hidden, remove the contents of the container and set the
class to none, or set the visible property to false. This will make the object invisible,
without removing its control over the height or width settings.
Example: List Column Titles - set the Column Titles property to hidden.

IBM Cognos Proprietary Information

Ensuring consistent object alignment in HTML and PDF outputs

3.1.3 RULE #3: Set White Space to No Wrap

If items must line up side-by-side, ensure that White Space for table cells / list
columns are set to No Wrap, for row heights to be the same between containers.

3.1.4 RULE #4: Check "Fixed Size" property in the "Table Properties"
Fixed Size will ensure that the size values in the object properties are honoured, and
Report Studio will show a true reflection of what to expect in an HTML output. This is
required for consistent results between different output formats.

IBM Cognos Proprietary Information

Ensuring consistent object alignment in HTML and PDF outputs

10

3.1.5 RULE #5: Set Borders explicitly

Borders affect an objects width and height. If no border is specified, then the default
border is inherited, which could have unpredictable results. Dont use Default:

Set Style to None, and click the black square (below Preview) to remove borders,
while retaining size properties. Ensure the dotted lines are visible:

IBM Cognos Proprietary Information

Ensuring consistent object alignment in HTML and PDF outputs

11

3.1.6 RULE #6: Set Padding and margin settings explicitly

Padding in the cell, table and row / column will affect the overall size and placement
of objects. If these must be applied, then they have to be consistent between
containers. When ever possible, set this at the parent level to ease future updates
and maintenance of the report.

IBM Cognos Proprietary Information

Ensuring consistent object alignment in HTML and PDF outputs

12

Appendix A
Cascading Style Sheets, level 2 CSS2 Specification
Detailed explanations of all the key elements involved when dealing with HTML tables
can be found at the following W3C reference site:
W3C Recommendation 12-May-1998 http://www.w3.org/TR/REC-CSS2/tables.html

IBM Cognos Proprietary Information