WebFOCUS HTML and PDF Report Design Part 2 By Mickey Grackin

In the first article about WebFOCUS HTML and PDF Report Design, I attempted to give some understanding about the differences between formatting for HTML and for PDF output formats by supplying many examples of code that demonstrated the differences.  This follow-up article builds on the information provided in the first article by focusing on additional formatting options.  The keywords used to control the position of field and text items in HEADINGs will be discussed in this article.  Some of the keywords that were discussed in the first article will be used in the examples in this article but will not be explained in detail.  Please also note that the styling applied to the HEADING in the examples will also work for FOOTINGs, SUBHEADs and SUBFOOTs.

Throughout this article there are two terms that will be used frequently.  Those terms are FIELD ITEM and TEXT ITEM.  These terms will be used to refer to two different types of objects in a HEADING and should not be confused with each other.  Please keep these definitions in mind when reading this article.

The term TEXT ITEM refers to static words or text that is written in the HEADING which does not change.  It also applies to Dialogue Manager variables that are included in the HEADING.  When a Dialogue Manager variable is resolved, the value for that variable is treated as static words or text in the HEADING.

The term FIELD ITEM refers to fields that are included in the HEADING which change based on the value of the field.

The usage of TEXT ITEMs in a HEADING will be discussed first and then the usage of FIELD ITEMs, and the differences in behavior, will be covered.

Where to Begin

To begin the discussion, run the following report request, generating a version of the report as an HTML document and one as a PDF document.

TABLE FILE CAR
PRINT DEALER_COST RETAIL_COST SALES
BY COUNTRY
BY CAR
BY MODEL
BY BODYTYPE
ON TABLE SET PAGE NOPAGE
ON TABLE SET HTMLCSS ON
ON TABLE PCHOLD FORMAT [HTML or PDF]
ON TABLE SET STYLE *
TYPE=REPORT, ORIENTATION=LANDSCAPE, GRID=OFF,$
ENDSTYLE
END

What appears is a basic tabular report.  Each output format looks basically the same.  The information on a report formatted like this can be useful but there is a lot more we can do to make this report shine.  Let’s begin by adding some HEADING information to better describe the information on the report.

Add the following commands to the report and then run the report for both the HTML and PDF output formats.

HEADING
"Where? General Car Information The Numbers # Sold"

As you will see, the text in the HEADING appears left justified and all together, which isn’t very appealing or useful.  All the words in the HEADING are treated as one text item.  How to split the text into multiple text items will be discussed a little later.

What we would like to do is split the HEADING text into four text items and then position each text item in the HEADING over specific columns so as to better describe the information in those columns.  There are a number of ways to position HEADING text items which varies depending on the output format, in this case HTML or PDF.  There are also some positioning keywords and concepts that need to be understood to effectively position text items in a HEADING.

The Styling Keyword "HEADALIGN"

By default, HEADING text items are left justified on each line and are not aligned with the columns of the report.  There is a styling keyword called HEADALIGN that is used to control how the text in a HEADING is positioned.  The HEADALIGN keyword may be set to NONE, INTERNAL or BODY.  The setting of NONE is the default which positions all text items on each line all together without aligning them with the columns.  The setting of INTERNAL is used to align the text items on each HEADING line in relation to the text items on the other HEADING lines.  Understanding how this setting works will become a lot clearer by experimenting with different report examples.  This article will not demonstrate the usage of the NONE and INTERNAL settings for HEADALIGN.  The third setting of BODY is used to position the text items in a HEADING in relation to the columns on the report.  The part of the report which contains the data columns and titles is referred to as the body of the report, hence the keyword setting of BODY.  The BODY setting is probably used more frequently than the other two settings and therefore the examples in this article will use this setting to demonstrate how to position text items.

Add the following commands to the report and then run the report for both the HTML and PDF output formats.

TYPE=REPORT, ORIENTATION=LANDSCAPE, GRID=OFF,$
TYPE=HEADING, HEADALIGN=BODY,$
ENDSTYLE

The Styling Keyword "<+0>"

The text that is in the HEADING is intended to be positioned over different columns, not just the first column.  The problem is that WebFOCUS has no way to know which parts of the text should be positioned over which columns.  By default, it treats all text as one text item.  The styling keyword <+0> is used to indicate a break between text items so that WebFOCUS knows to treat them as separate text items.

Change the HEADING text line to look like the following and then run the request again for both the HTML and PDF output formats.

HEADING
"Where?<+0>General Car Information<+0>The Numbers<+0># Sold"

The Styling Keywords "LINE, OBJECT and ITEM"

Now that we have separated each text item of the HEADING, we can now control the positioning of each piece individually.  To identify a specific text item in a HEADING, the two styling keywords OBJECT and ITEM are used.  The styling keyword OBJECT is used to identify the type of item in a HEADING to which the styling is to be applied.  There are two possible types of items in a HEADING.  As mentioned at the beginning of this article, they are FIELD and TEXT.  So far we have only included text in our HEADING so we only have TEXT ITEMs in our HEADING.  If a field is included in a HEADING then setting the styling keyword OBJECT to FIELD would be used to identify field type items.

When there are multiple field items or text items in a HEADING, the styling keyword ITEM is used to identify the specific field item or text item to which the styling is to be applied.    The styling keyword ITEM may be used alone or in conjunction with the OBJECT keyword to identify a particular field item or text item in a HEADING.

The styling keyword LINE is used to indicate on which line of the HEADING to look for the particular OBJECT and ITEM.

Add the following commands to the report.  There is no need to run the report yet since we have not added any additional commands that would affect the output of the report.

TYPE=HEADING, HEADALIGN=BODY,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=2,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=3,$
ENDSTYLE

The Styling Keyword "COLSPAN"

Add the following commands to the report and run the report for the HTML output format.

TYPE=HEADING, HEADALIGN=BODY,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=2, COLSPAN=3,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=3, COLSPAN=2,$
ENDSTYLE

If this report is run for the PDF output format, you will notice that these commands still have no affect on the PDF output format.

The Styling Keyword "JUSTIFY"

As mentioned earlier, the default behavior for text items in a HEADING is to be left justified.  The styling keyword JUSTIFY is used to specify the justification of a text item in a HEADING.  The styling keyword JUSTIFY may be set to LEFT, CENTER or RIGHT.

Add the following commands to the report and run the report for the HTML output format.

TYPE=HEADING, HEADALIGN=BODY,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=2, COLSPAN=3,
  JUSTIFY=CENTER,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=3, COLSPAN=2,
  JUSTIFY=CENTER,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=4,
  JUSTIFY=RIGHT,$
ENDSTYLE

Notice the second text item “General Car Information” now appears centered across the top of the CAR, MODEL and BODYTYPE columns. You will also notice that the third text item “The Numbers” now appears centered across the top of the DEALER_COST and RETAIL_COST columns. Lastly, the third text item “# Sold” appears right justified over the SALES column.

Once again, if this report is run for the PDF output format, you will notice that these commands have no affect on the PDF output format.

The Styling Keyword "POSITION"

There are two styling keywords used to control the positioning of HEADING text items for the PDF output format.  One of these styling keywords is POSITION.  There are many ways to use the styling keyword POSITION.

The easiest way to use the styling keyword POSITION is to set it to the position of the column over which the text item is to be placed.  For example, setting POSITION to P2 will place the text item over column two of the report.  Setting POSITION to P5 will place the text item over column five.  This method is referred to as column notation.  The P refers to the printed columns on the report.  Other methods of column notation would include B, C and N.  Each of these methods of column notation is used to identify columns in a report request in slightly different ways.  For example, B refers to the vertical (BY) sort fields only.  For purposes of this article, the examples will demonstrate the usage of the P method of column notation only. You may also set POSITION to a fieldname such as CAR or DEALER_COST.  Another way to use the styling keyword POSITION is to set it to a numeric value such as 1.25 or 5.  This is referred to as absolute positioning.

Remove the command containing the HEADALIGN setting from the report request.  Next, remove the COLSPAN and JUSTIFY keyword settings from the report request and then add the following commands to the request.  Run the report for the PDF output format.

TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=2, POSITION=P2,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=3, POSITION=P5,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=4, POSITION=SALES,$
ENDSTYLE

As expected, each text item appears over the column to which it was positioned.  However, notice what happens with the text item "General Car Information".  The text item still crosses over to the MODEL column even though it was positioned over the CAR column.  In short, the POSITION setting indicates over which column a HEADING text item should start but it does not constrain the text item to the width of the column it is over.

There are a couple of other things to note here.  The first text item always defaults to being positioned over the first column so it is not necessary to explicitly do this in the report request.  Also, be sure to explicitly position all text items on a line if positioning any of the text items on the line.  This is because if a text item is not explicitly positioned, it will begin immediately after the previous text item.  To see an example of this behavior, remove the following command from the report request and then run it for the PDF output format.

TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=3, POSITION=P5,$

Notice the third text item "The Numbers" appears immediately after the second text item.  Add the above command back into the request before continuing.

The Styling Keyword "WIDTH"

We already discussed using the styling keyword COLSPAN to make a text item span across multiple columns when creating an HTML output format report.  To do the equivalent in a PDF output format, use the styling keyword WIDTH.  As implied by its name, the styling keyword WIDTH sets the width of the area which a text item should span.  The rule mentioned about using the styling keyword POSITION for all text items applies for the usage of WIDTH as well.  If the WIDTH styling keyword is used to control the width of one text item on a line, set the WIDTH for all text items on that same line.  The styling keywords POSITION and WIDTH are not intended to be used together to position field or text items on the same line in a report request.  However, the exception to this rule is when the styling keyword POSTION is used with absolute positioning instead of with column notation or fieldnames.  See the bonus example at the end of the article using all positioning styling keywords.
 
In order to demonstrate the usage of WIDTH more effectively, change the report request to look like the following.  We will then add the WIDTH setting for each text item to create the same report in PDF as we previously created in HTML with the second and third text items centered over multiple columns.

TABLE FILE CAR
PRINT DEALER_COST RETAIL_COST SALES
BY COUNTRY
BY CAR
BY MODEL
BY BODYTYPE
HEADING
"Where?<+0>General Car Information<+0>The Numbers<+0># Sold"
ON TABLE SET PAGE NOPAGE
ON TABLE SET HTMLCSS ON
ON TABLE PCHOLD FORMAT PDF
ON TABLE SET STYLE *
TYPE=REPORT, ORIENTATION=LANDSCAPE, GRID=OFF,$
TYPE=REPORT, COLUMN=COUNTRY    , WRAP=1.00,$
TYPE=REPORT, COLUMN=CAR        , WRAP=1.00,$
TYPE=REPORT, COLUMN=MODEL      , WRAP=2.00,$
TYPE=REPORT, COLUMN=BODYTYPE   , WRAP=1.25,$
TYPE=REPORT, COLUMN=DEALER_COST, WRAP=1.25,$
TYPE=REPORT, COLUMN=RETAIL_COST, WRAP=1.25,$
TYPE=REPORT, COLUMN=SALES      , WRAP=1.00,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=1,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=2, POSITION=P2,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=3, POSITION=P5,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=4, POSITION=SALES,$
ENDSTYLE
END

When positioning HEADING text items over specific columns, the width of the columns should remain the same for every execution of the report request.  The styling keyword WRAP will make sure the column widths do not change.  The styling keyword WRAP is discussed in the first article about WebFOCUS HTML and PDF Report Design.

The WRAP value for the COUNTRY column is fixed at 1.00 so the width for the HEADING text item "Where?" that is to appear over that column should be set to 1.00.  The HEADING text item "General Car Information" should appear over the CAR, MODEL and BODYTYPE columns so the width for this HEADING text item should be set to 4.25 which is the total (1.00 + 2.00 + 1.25) of the WRAP values for these three columns.  The values of WRAP for the next two columns (1.25 + 1.25) are added together to determine the WIDTH value (2.50) for the next HEADING text item and so on.

Remove the styling keyword settings for POSITION and then add the following to the report request. Run the report request for the PDF output format.

TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=1, WIDTH=1.00,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=2, WIDTH=4.25,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=3, WIDTH=2.50,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=4, WIDTH=1.00,$

Notice anything strange?  The HEADING text items do not line up with the columns.  This is because when a PDF output format document is created, each column of data is padded with a LEFTGAP and RIGHTGAP spacing value. The styling keywords LEFTGAP and RIGHTGAP are discussed in the first article about WebFOCUS HTML and PDF Report Design.  When calculating the width of a column in the PDF output format, the values for LEFTGAP and RIGHTGAP need to be accounted for.  The default value for both the LEFTGAP and RIGHTGAP is 0.10.  Therefore, a value of 0.20 (LEFTGAP + RIGHTGAP) must be added to the WIDTH value for each column a HEADING text item is to be placed over.  The exceptions to this formula are the first and last columns of the report.  The first column does not get a LEFTGAP and the last column of the report does not get a RIGHTGAP.

Change the WIDTH settings in the report request to the following and run the report again for the PDF output format.

TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=1, WIDTH=1.10,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=2, WIDTH=4.85,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=3, WIDTH=2.90,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=4, WIDTH=1.10,$

HEADING text item one is set to 1.10 since the first column of the report only has a RIGHTGAP.  Therefore only 0.10 is added to the width.  The second HEADING text item is to span across three columns so 0.60 is added to the width value.  This is to account for both the LEFTGAP and the RIGHTGAP for three columns ((0.10 + 0.10) * 3).  The third HEADING text item is to span across two columns so 0.40 is added to the width value.  Finally, the forth HEADING text item is to appear over the last column of the report so only the LEFTGAP (0.10) is added to the width value.

Add the following commands to the report and run the report again for the PDF output format.  The PDF output format should look identical to the HTML output format created earlier.

TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=1, WIDTH=1.10,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=2, WIDTH=4.85,
  JUSTIFY=CENTER,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=3, WIDTH=2.90,
  JUSTIFY=CENTER,$
TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=4, WIDTH=1.10,
  JUSTIFY=RIGHT,$

Field Items in a HEADING

Field items in a HEADING behave the same way as text items except in one way.  The WRAP setting may be applied to a field item in a HEADING.  The field values will respect the boundaries of the WRAP setting where as text items will not.

The following report request contains an example of a field item in a HEADING and also demonstrates the usage of absolute positioning with the styling keyword POSITION.

Run the following request to see how field items behave in a HEADING.

TABLE FILE CAR
PRINT DEALER_COST RETAIL_COST SALES
COMPUTE CNTYTEXT/A20='Country: ' | COUNTRY; NOPRINT
BY COUNTRY NOPRINT PAGE-BREAK
BY CAR
BY MODEL
BY BODYTYPE
HEADING
"<CNTYTEXT>"
"General Car Information<+0>The Numbers<+0># Sold"
-*"Where?<+0>General Car Information<+0>The Numbers<+0># Sold"
ON TABLE SET PAGE NOPAGE
ON TABLE SET HTMLCSS ON
ON TABLE PCHOLD FORMAT PDF
ON TABLE SET STYLE *
TYPE=REPORT, ORIENTATION=LANDSCAPE, GRID=OFF,$
-*TYPE=REPORT, COLUMN=COUNTRY    , WRAP=1.00,$
TYPE=REPORT, COLUMN=CAR        , WRAP=1.00,$
TYPE=REPORT, COLUMN=MODEL      , WRAP=2.00,$
TYPE=REPORT, COLUMN=BODYTYPE   , WRAP=1.25,$
TYPE=REPORT, COLUMN=DEALER_COST, WRAP=1.25,$
TYPE=REPORT, COLUMN=RETAIL_COST, WRAP=1.25,$
TYPE=REPORT, COLUMN=SALES      , WRAP=1.00,$
-*TYPE=HEADING, LINE=1, OBJECT=TEXT, ITEM=1, WIDTH=1.10,$
TYPE=HEADING, LINE=1, OBJECT=FIELD, ITEM=1, POSITION=2.00,
  WRAP=1.10,$
TYPE=HEADING, LINE=2, OBJECT=TEXT, ITEM=1, WIDTH=4.75,
  JUSTIFY=CENTER,$
TYPE=HEADING, LINE=2, OBJECT=TEXT, ITEM=2, WIDTH=2.90,
  JUSTIFY=CENTER,$
TYPE=HEADING, LINE=2, OBJECT=TEXT, ITEM=3, WIDTH=1.10,
  JUSTIFY=RIGHT,$
ENDSTYLE
END

Exceptions to the Rules

Before concluding this article, there are a couple of additional things to keep in mind.  Hopefully knowing the exceptions to the rules will help rather than confuse you more.

The first thing to note is the LEFTGAP and RIGHTGAP rules change when there is a GRID or BORDERs on the PDF output format report.  For example, many reports will have a GRID or BORDERs around the TITLEs or DATA.  The first and the last columns of the PDF output format report will have a LEFTGAP and RIGHTGAP when there is a GRID or BORDERs on the report around the TITLEs or DATA.

The second thing to note is the GRID and BORDER lines themselves take up a small amount of space on the report.  Remember to account for this when positioning HEADING text items on PDF output format reports that have a GRID or BORDERs.

The last thing to note is that the first and last columns of a PDF output format report will have a LEFTGAP and RIGHTGAP when the LEFTGAP and RIGHTGAP are explicitly set for the entire report.  This is done by using the LEFTGAP and RIGHTGAP styling keywords in a TYPE=REPORT statement.  If either of these is explicitly set, regardless of whether or not there is a GRID or BORDERs on the report, the first and last columns will have the gaps as well.

Final Comments

Hopefully this article has given you a better understanding of the different styling keywords that are used to create the same report for both the HTML and PDF output formats. Being aware of the slight behavioral differences and knowing how to position HEADING text items on a report for both HTML and PDF output formats should give you a strong foundation for creating WebFOCUS reports that shine!

Bonus Example

The following demonstrates many of the styling keywords discussed in both articles.

TABLE FILE CAR
PRINT DEALER_COST AS '' RETAIL_COST AS '' SALES AS ''
COMPUTE CNTYTEXT/A20='Country: ' | COUNTRY; NOPRINT
BY COUNTRY NOPRINT NOSPLIT
BY CAR AS ''
BY MODEL AS ''
BY BODYTYPE AS ''
ON COUNTRY SUBHEAD
" "
"<CNTYTEXT>"
"General Car Information<+0>The Numbers"
"Maker<+0>Model<+0>Body Type<+0>Dealer Cost<+0>Retail Cost<+0># Sold"
ON TABLE SET PAGE NOPAGE
ON TABLE SET HTMLCSS ON
ON TABLE PCHOLD FORMAT PDF
ON TABLE SET STYLE *
TYPE=REPORT, ORIENTATION=LANDSCAPE, SQUEEZE=ON, GRID=OFF,
  LEFTGAP=0.125, RIGHTGAP=0.125, BOTTOMGAP=0.075,
  LEFTMARGIN=0.750, FONT='ARIAL',$
TYPE=REPORT, COLUMN=CAR        , WRAP=1.00,$
TYPE=REPORT, COLUMN=MODEL      , WRAP=2.00,$
TYPE=REPORT, COLUMN=BODYTYPE   , WRAP=1.25,$
TYPE=REPORT, COLUMN=DEALER_COST, WRAP=1.25,$
TYPE=REPORT, COLUMN=RETAIL_COST, WRAP=1.25,$
TYPE=REPORT, COLUMN=SALES      , WRAP=1.00,$
TYPE=SUBHEAD, LINE=2, OBJECT=FIELD, ITEM=1, POSITION=0.125,
  WRAP=1.000, COLOR=BLUE, STYLE=BOLD,$
TYPE=SUBHEAD, LINE=3, BACKCOLOR=RGB(0 73 132), COLOR=WHITE,$
TYPE=SUBHEAD, LINE=3, OBJECT=TEXT, ITEM=1, POSITION=0.000,
  WIDTH=5.000, JUSTIFY=CENTER,$
TYPE=SUBHEAD, LINE=3, OBJECT=TEXT, ITEM=2, POSITION=5.000,
  WIDTH=3.000, JUSTIFY=CENTER,$
TYPE=SUBHEAD, LINE=4, BACKCOLOR=RGB(51 0 153), COLOR=WHITE,$
TYPE=SUBHEAD, LINE=4, ITEM=1, POSITION=P1,$
TYPE=SUBHEAD, LINE=4, ITEM=2, POSITION=P2,$
TYPE=SUBHEAD, LINE=4, ITEM=3, POSITION=P3,$
TYPE=SUBHEAD, LINE=4, ITEM=4, POSITION=P4, JUSTIFY=RIGHT,$
TYPE=SUBHEAD, LINE=4, ITEM=5, POSITION=P5, JUSTIFY=RIGHT,$
TYPE=SUBHEAD, LINE=4, ITEM=6, POSITION=P6, JUSTIFY=RIGHT,$
TYPE=DATA, GRID=ON, BACKCOLOR=RGB(255 255 224),$
ENDSTYLE
END