WebFOCUS HTML and PDF Report Design Part 1 By Mickey Grackin

Have you got an hour or two? In this article I will attempt to tackle the daunting task of explaining many of the formatting options available for designing WebFOCUS reports using the HTML and PDF output formats and will discuss the differences between them. This task is daunting not because it is difficult to design great looking reports with WebFOCUS, but rather because WebFOCUS affords the report developer great flexibility and control over the design of a report. It would be impossible to discuss every single formatting option in an article like this. My goal here is to discuss as many features as I can without getting bogged down with covering too many bells and whistles. Hopefully this article will give you a good head start in understanding how to design reports for each output format and how your code will differ for generating each one.

Two Different Animals

The first thing to remember when considering the HTML and PDF output formats is that an HTML document is a very different animal than a PDF document. HTML was designed to present information in a browser window. In HTML there is no such thing as a page that we normally think of as the confines for presenting information. On the other hand, PDF documents do present information on pages, as we would normally expect. This one difference in formats accounts for a number of styling keyword differences in WebFOCUS.

The second thing to remember is, due to the fact that a browser displays the HTML document, there are many more neat tricks and styling you can do to an HTML document. Due to the dynamic nature of an HTML document, the browser can be given additional styling commands in the form of a Cascading Style Sheet (CSS) after WebFOCUS has created the HTML document and sent it back to the browser. There is no CSS equivalent for PDF documents. In this article, the term "style sheet" is used to refer to a WebFOCUS style sheet, not a CSS.

Keeping these two thoughts in mind, as we go through the examples, I will discuss some of the different styling keywords specific to each output format.

This article is designed to be an interactive experience, so you will need to have access to the CAR database and the ability to run hand-coded report FOCEXECs. For purposes of the examples, I will be using WebFOCUS 5.3.4 running on a Windows 2000 server.

Default Styling

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 NOLEAD
ON TABLE PCHOLD FORMAT [HTML or PDF]
END

Immediately you will notice a few differences. The HTML document has only one page whereas the PDF document has two pages. The HTML document has borders, referred to as a GRID, but the PDF document does not. The HTML document does not contain extra SPACES between columns of data, but the PDF document does. Lastly, if you reduce the width of your browser window for the HTML document you will see that the values in the "Model" and "Car" columns begin to word wrap within the cells of the GRID. This will not happen to the PDF document.

Since there are no style sheet commands included in my report request, the documents were generated with the default output styling appropriate for each output format. Let's discuss the differences individually and begin adding style sheet commands in order to demonstrate how these commands affect each output format. All WebFOCUS style sheet commands appear between the two following commands:

ON TABLE SET STYLE *

ENDSTYLE

The Styling Keyword "ORIENTATION"

One styling keyword that is used primarily for the PDF output format is ORIENTATION. There is no concept of page orientation for HTML documents. HTML documents, by default, are dynamically resized to fit within the browser window. If it does not fit within the window, the browser will begin to apply word wrapping to the HTML document to make it fit. The browser will eventually add horizontal scroll bars if it cannot reduce the width of the HTML document enough to fit it in the window. Because of this dynamic sizing behavior, the ORIENTATION keyword does not apply to the HTML output format.

Add the following commands to the report and then run the report using the PDF output format.

ON TABLE SET STYLE *
TYPE=REPORT, ORIENTATION=LANDSCAPE,$
ENDSTYLE

You will now see that the report appears all on one page in landscape.

The Styling Keyword "GRID"

There are a couple of ways to add a grid, or borders, to an HTML or PDF document. The easiest way to do this is to use the GRID styling keyword. Add the following syntax to the report and then run the report using the PDF output format.

ON TABLE SET STYLE *
TYPE=REPORT, ORIENTATION=LANDSCAPE, GRID=ON,$
ENDSTYLE

Notice the PDF document now contains a grid around the column titles and the data, just like the HTML document. However, the grid in the HTML document still looks slightly different. This is because the column titles and data are contained in an HTML TABLE object. The default behavior for an HTML TABLE object is to have two pixels between the cells, hence creating a different looking grid. We will look at how to change the look of the grid, or borders, a little later.

You can also turn off the grid for each output format by changing the GRID setting to OFF. Please notice that, as a side effect of setting the GRID to OFF, the HTML document will no longer apply word wrapping to the column values in the cells. This is because without the grid, the HTML document may become confusing if the column values word wrap within the cells. Change the GRID setting in the style sheet and run the report using the HTML output format.

ON TABLE SET STYLE *
TYPE=REPORT, ORIENTATION=LANDSCAPE, GRID=OFF,$
ENDSTYLE

Change the browser window width to see how the HTML document behaves.

Column Widths and Spacing

There is a lot more to working with spacing than meets the eye. We will discuss the three main styling keywords used to change the column widths and spacing on reports. Those keywords are SPACES, SQUEEZE, and WRAP.

A Brief History Lesson

Putting spaces between columns is traditional FOCUS language behavior. The default is to put two spaces between columns on a report. The styling keyword SPACES allows you to change this to between one and eight spaces. However, in the WebFOCUS world, this keyword is only used in conjunction with the HTML output format when the STYLEMODE is set to FIXED. In addition, setting SPACES has no effect on PDF documents. There are additional styling keywords to change the column spacing for PDF documents which we will discuss a little later. Due to its limited application, we will not use the keyword SPACES in our examples and you probably will not find yourself using this keyword for your own reports.

Another traditional behavior of the FOCUS language is to create columns with a width equal to the field format length or the column title length, whichever is longer. If you look at the Master File Description for the CAR database, you will see that the format length for the field "Car" is sixteen. Therefore, the FOCUS language would normally create a column of sixteen characters wide even though the longest data value, "ALFA ROMEO" is only 10 characters long.

Now that we have a brief understanding of traditional FOCUS language behavior, let's look at what happens with the HTML and PDF documents.

The WebFOCUS World

If you look at the HTML document, you will see that the traditional behavior of column widths and column spacing does not occur. This is because the default behavior for HTML documents is for all extra spaces to be reduced to one space. This is a browser behavior, not a WebFOCUS behavior. Since the data appears in an HTML TABLE object, the cell borders, or gridlines, are considered the delineator between columns of data. This is why the setting for SPACES does not apply. However, there are ways to mimic the traditional column width behavior in an HTML document.

The PDF document maintains the traditional behavior of column widths but does not have the traditional two spaces between each column. It may appear that there are two spaces between columns but this is actually called the GAP. There are additional styling keywords for PDF documents such as LEFTGAP, RIGHTGAP, TOPGAP, and BOTTOMGAP, which allow you to control the space between columns. We will discuss these more a little later.

The Styling Keyword "SQUEEZE"

The first and easiest way to mimic the traditional column width behavior in HTML and PDF documents is to use the styling keyword SQUEEZE. Setting SQUEEZE to OFF causes the HTML code " " to be inserted into the HTML document for each blank space in a column. The " " forces the browser to display blank spaces instead of reducing all the spaces to one. For example, 10 " " codes in a row will display as 10 spaces.

Add the following syntax to the report and then run the report using the HTML output format.

ON TABLE SET STYLE *
TYPE=REPORT, ORIENTATION=LANDSCAPE, GRID=OFF,
  SQUEEZE=OFF,$
ENDSTYLE

You will see that the columns are now much wider. View the source code for the HTML document and you will see all the " " codes that were inserted. Again, you will notice that, as a side effect of setting the SQUEEZE to OFF, the HTML document will no longer apply word wrapping to the column values in the cells.

The PDF document will be affected in the same manner when SQUEEZE is set to OFF. Run the report using the PDF output format and you will see that the columns appear wider as well.

The Styling Keyword "WRAP"

The other styling keyword to control column width behavior is WRAP. WRAP controls the word wrapping of column values for both HTML and PDF output formats. As discussed earlier, we saw that the wrapping of column values was on or off, by default, depending on the setting for GRID and SQUEEZE. If you recall, for HTML documents word wrapping occurs when GRID is set to ON. However, word wrapping does not occur when GRID is set to OFF.

Let's discuss additional settings for the SQUEEZE and WRAP styling keywords and then look at some examples.

Setting "SQUEEZE" or "WRAP" to a Number

In addition to being able to turn SQUEEZE and WRAP on or off, each of these may be set to a number. Setting SQUEEZE or WRAP to a number allows you to control the column width for all columns or individual columns for both HTML and PDF documents. One additional statement needs to be added to our report in order to set SQUEEZE or WRAP to a number when creating HTML documents.

Add the following statement to the report before continuing.

ON TABLE SET HTMLCSS ON

Setting HTMLCSS to ON will cause an internal Cascading Style Sheet to be created for and included into HTML documents. Cascading Style Sheets, or CSS, are a much more robust way to control the display of an HTML document in a browser. CSS is an HTML formatting language. There is no CSS equivalent for PDF documents and therefore this statement will have no affect on them.

Squeezing and Wrapping an HTML Document

Adjust your report request so that it looks like the following.

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

Okay, this is where it gets a little fuzzy for HTML documents. It is very important to remember that the HTML document that WebFOCUS creates is displayed by the browser and therefore is subject to the rules of the browser. Let's look at some examples to see what happens.

Add the following statement to the report and then run the report using the HTML output format.

TYPE=REPORT, COLUMN=CAR, SQUEEZE=2,$

This statement sets the width of the "Car" column to two of whatever UNITS is set to. If UNITS is set to INCHES then the width becomes two inches for the "Car" column. Well, this is almost accurate. For HTML documents, if WRAP is still set to ON, this actually sets the maximum width for the "Car" column to two. To understand what this means, reduce the width of the browser window containing the HTML document. You will notice that if the report does not fit in the browser window, it will still shrink the width of the "Car" column and even word wrap the column values if necessary. If you increase the width of the browser window, you will notice that the "Car" column expands to a maximum width of two and then stops expanding.

To force the column width to stay at two, no matter how wide or narrow the browser window gets, add the following syntax to the statement.

TYPE=REPORT, COLUMN=CAR, SQUEEZE=2, WRAP=OFF,$

Run the report again using the HTML output format and resize the browser window to see that the "Car" column now stays at the specified width while the other columns still experience word wrapping.

Move the WRAP command up to the first style sheet statement and then run the report again using the HTML output format.

TYPE=REPORT, ORIENTATION=LANDSCAPE, GRID=ON, WRAP=OFF,$
TYPE=REPORT, COLUMN=CAR, SQUEEZE=2,$

Word wrapping will now be turned off for all columns and the width of the "Car" column will be fixed at two.

Here's a twist. Change the COLUMN setting to MODEL and run the report again using the HTML output format.

TYPE=REPORT, ORIENTATION=LANDSCAPE, GRID=ON, WRAP=OFF,$
TYPE=REPORT, COLUMN=MODEL, SQUEEZE=2,$

Notice what happens. The width of the "Model" column is fixed at two but any column values longer than two are word wrapped. Resize the browser window to see that the column widths do not change since WRAP is set to OFF for the entire report. This is an example of how you can set a fixed column width and still experience word wrapping. Confused yet?

Now, for one last HTML output format example, change the word SQUEEZE to the word WRAP and then run the report one more time using the HTML output format.

TYPE=REPORT, ORIENTATION=LANDSCAPE, GRID=ON, WRAP=OFF,$
TYPE=REPORT, COLUMN=MODEL, WRAP=2,$

Resize the browser window to see that the "Model" column now experiences dynamic word wrapping but never exceeds a width of two. All other column widths do not change since WRAP is set to OFF for the entire report.

Enough with the HTML document examples. Let's move on to the PDF output format and discuss how it is affected by SQUEEZE and WRAP.

Squeezing and Wrapping a PDF Document

Adjust your report request again so that it looks like the following and then run the report using the PDF output format.

TABLE FILE CAR
PRINT DEALER_COST RETAIL_COST SALES
BY COUNTRY
BY CAR
BY MODEL
BY BODYTYPE
ON TABLE SET PAGE NOLEAD
ON TABLE PCHOLD FORMAT PDF
ON TABLE SET STYLE *
TYPE=REPORT, ORIENTATION=LANDSCAPE, GRID=ON,$
ENDSTYLE
END

Let's make the same style sheet command additions as we did for the HTML documents and discuss how these commands affect the PDF documents.

Add the following statement to the report and then run the report using the PDF output format.

TYPE=REPORT, COLUMN=CAR, SQUEEZE=2,$

Just like it did for the HTML documents, this command sets the width of the "Car" column to two of whatever UNITS is set to. There is one difference to note here. The width of the "Car" column will not change if the width of the window for the PDF document is reduced. The dynamic word wrapping behavior seen with HTML documents will not occur with the PDF documents. The width of the "Car" column is fixed at two even when WRAP is not set to OFF.

Now change the COLUMN setting to MODEL and run the report again using the PDF output format.

TYPE=REPORT, ORIENTATION=LANDSCAPE, GRID=ON,$
TYPE=REPORT, COLUMN=MODEL, SQUEEZE=2,$

Look at the row in the "Model" column where the value "COROLLA 4 DOOR DIX AUTO" would appear. You will notice that the word "AUTO" is missing and a "!" symbol appears. This demonstrates how the SQUEEZE styling keyword behaves differently between the two output formats. For HTML documents the browser applied word wrapping to the column values when necessary. However, in PDF documents word wrapping will not be applied automatically. Therefore, if a column value does not fit within the column width, it will be truncated and the "!" symbol will be added to indicate this has occurred.

Change the word SQUEEZE to the word WRAP and then run the report one more time using the PDF output format.

TYPE=REPORT, ORIENTATION=LANDSCAPE, GRID=ON,$
TYPE=REPORT, COLUMN=MODEL, WRAP=2,$

Look again at the row in the "Model" column where the value "COROLLA 4 DOOR DIX AUTO" would appear. The value is no longer truncated. Word wrapping has been applied to the column value and the word "AUTO" now appears on a second line.

Change the word WRAP back to the word SQUEEZE. Move the SQUEEZE command up to the first style sheet statement and delete the style sheet command for the "Model" column. Run the report again using the PDF output format.

TYPE=REPORT, ORIENTATION=LANDSCAPE, GRID=ON,
  SQUEEZE=2,$

The width of every column on the report is now fixed at two.

Now, for one last PDF output format example, change the word SQUEEZE again to the word WRAP and set its value to one and a half instead of two. Run the report one more time using the PDF output format.

TYPE=REPORT, ORIENTATION=LANDSCAPE, GRID=ON,
  WRAP=1.5,$

The width of every column on the report is now set to one and a half and word wrapping is applied to each column value when necessary.

After reading this article, try experimenting with additional combinations of the SQUEEZE and WRAP settings to learn more about how they work together.

While we are working with PDF documents, let's get back to discussing the column spacing topic.

The Styling Keywords to Control the "GAP"

As mentioned earlier, the space between column values on a PDF document is actually referred to as the GAP. In reality, there are no SPACES between the columns on either a PDF or an HTML document. The GAP is the space between the column values and the border, or gridlines, that surround it. The GAP may be changed using the LEFTGAP, RIGHTGAP, TOPGAP, and BOTTOMGAP styling keywords.

Adjust your report request to look like the following and then run the report using the PDF output format.

TABLE FILE CAR
PRINT DEALER_COST RETAIL_COST SALES
BY COUNTRY
BY CAR
BY MODEL
BY BODYTYPE
ON TABLE SET PAGE NOLEAD
ON TABLE PCHOLD FORMAT PDF
ON TABLE SET STYLE *
TYPE=REPORT, ORIENTATION=LANDSCAPE, GRID=ON,$
ENDSTYLE
END

Notice the small amount of space to the left and the right of each value. Add the following syntax to the report to change the LEFTGAP and then run the report using the PDF output format.

TYPE=REPORT, ORIENTATION=LANDSCAPE, GRID=ON,
  LEFTGAP=0,$

The values of each column that are left justified now appear next to the left side gridline because the left side gap is now set to zero.

Next, add the following syntax to the report to change the BOTTOMGAP and then run the report using the PDF output format.

TYPE=REPORT, ORIENTATION=LANDSCAPE, GRID=ON,
  LEFTGAP=0, BOTTOMGAP=.25,$

There is now additional space between the column values and the bottom gridline under each value.

These four styling commands may also be used to change the gaps on HTML documents. Add the HTMLCSS setting to the report again, change the LEFTGAP setting to one and then run the report using the HTML output format.

ON TABLE SET HTMLCSS ON
ON TABLE PCHOLD FORMAT HTML
ON TABLE SET STYLE *
TYPE=REPORT, ORIENTATION=LANDSCAPE, GRID=ON,
  LEFTGAP=1, BOTTOMGAP=.25,$
ENDSTYLE

Just to reiterate, the concept of SPACES between columns does not apply for HTML and PDF output formats. Use the GAP settings to spread out the column values.

Styling the GRID and BORDERs

The last thing we will discuss in this article is how to change the GRID and BORDERs on a report. There are some additional styling keywords that apply to both the HTML and PDF output formats. Once again, adjust your report request to look like to following and then run the report using the HTML output format.

TABLE FILE CAR
PRINT DEALER_COST RETAIL_COST SALES
BY COUNTRY
BY CAR
BY MODEL
BY BODYTYPE
ON TABLE SET PAGE NOLEAD
ON TABLE SET HTMLCSS ON
ON TABLE PCHOLD FORMAT HTML
ON TABLE SET STYLE *
TYPE=REPORT, ORIENTATION=LANDSCAPE, SQUEEZE=ON,$
ENDSTYLE
END

Now add the following syntax to change the look of the gridlines on the report and then run the report using the HTML output format.

TYPE=REPORT, ORIENTATION=LANDSCAPE, SQUEEZE=ON,
  BORDER=LIGHT,$

You will notice that the gridlines on the report now look identical to the gridlines for the PDF output format. If you change the setting for BORDER to HEAVY the gridlines will appear thicker for both the HTML and PDF documents.

You may also change the STYLE and COLOR of the gridlines and each gridline may be changed individually if you desire to do so.

Add the following syntax to your report and then run the report using both the HTML and PDF output formats.

TYPE=REPORT, ORIENTATION=LANDSCAPE, SQUEEZE=ON,
  BORDER-LEFT=HEAVY, BORDER-LEFT-STYLE=DASHED,
  BORDER-LEFT-COLOR=RGB(255 0 255),$

If the "-LEFT" is removed from each BORDER setting, all gridlines will be added to the report with the specified settings. Make the following syntax changes to your report and then run the report using both the HTML and PDF output formats.

TYPE=REPORT, ORIENTATION=LANDSCAPE, SQUEEZE=ON,
  BORDER=HEAVY, BORDER-STYLE=DASHED,
  BORDER-COLOR=RGB(255 0 255),$

You probably already guessed that the RIGHT, TOP and BOTTOM gridlines may be changed individually as well by using the BORDER-RIGHT…, BORDER-TOP…, or BORDER-BOTTOM… commands.

In Summary

This is just the tip of the iceberg. We have seen just some of the styling keywords available in WebFOCUS that allow you to control the look of a report for the HTML and PDF output formats. There are other nifty styling keywords we didn't cover that allow you to control document MARGINs and the POSITION of items in HEADINGs and FOOTINGs and the like. Hopefully this article has shed some light on the powerful styling keywords WebFOCUS makes available to developers like you and why HTML and PDF documents appear and behave slightly differently when these styling keywords are used.