Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports...

33
Advanced Web Publishing with Oracle Reports An Oracle Technical White Paper March 2000

Transcript of Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports...

Page 1: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsAn Oracle Technical White PaperMarch 2000

Page 2: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

2

INTRODUCTION

The proliferation of the Internet has meant that the web is the medium of choice for information dissemination and exchange

for many of today’s organizations – be it through an Intranet (i.e. within the organization), Extranet (between the organization

and it’s business partners), or even the Internet itself. When disseminating any kind of information, it is important from an

end-user (or information consumer) perspective that the content be well presented and (if applicable) easy to use; it naturally

makes sense to use any available technologies to facilitate this. The web is no exception, and the technologies of Java, and

Javascript, coupled with the many native features of HTML, mean that the information consumer’s experience can be

dramatically enhanced with content that is both well presented, and easy to use.

Oracle Reports is Oracle’s enterprise reporting tool for the web. It’s wizard driven, declarative development environment

permits IT developers to easily build any kind of highly complex enterprise report – the kinds of reports that organizations

depend upon. It’s middle-tier server provides a scalable and performant solution for deployment of these reports to the web.

This paper will demonstrate how various features within Oracle Reports may be used to build enterprise reports that are

aimed at the web – i.e. leverage the technologies available in that medium. The technical content of this paper is based

around Oracle Reports 6i (though the majority of the techniques are valid for Reports 2.5 - Developer Server 1.5.1 or later

with some modification) and is aimed at developers who are familiar with Oracle Reports.

Page 3: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

3

We will take a report that looks like this:

Figure 1: a ‘standard’ report

Page 4: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

4

And produce a web version that looks like this:

Figure 2: A web enhanced report

Page 5: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

5

IMPORTANT ORACLE REPORTS CONCEPTS

Before we start looking at the ‘web enhancing’ techniques, it is worth spending a little time revising the basic Reports

concepts that will become important later on.

REFERENCING DATA WITHIN A REPORT

It is often necessary to reference data in a report for use elsewhere within that same report (e.g. passing a primary key as a

parameter to another web application). This data may be the report parameters (system or user), the fetched data, or the

displayed data (which may not necessarily be the same as the fetched data). We can easily do this in Oracle Reports using the

ampersand (&) notation. Here is an example of using this:

Figure 3: Data reference in the Property Palette

We are setting the hyperlink property (available in Reports 3.0 or later) for an object in the report layout using the property

palette. The (highlighted) value in figure 3 instructs the report formatter to substitute the token &<ename> with the current

instance of the ename object. The ename object may be a data column as defined in the report data model which contains

Page 6: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

6

fetched or computed data. It may also be a field as defined in the report layout editor which contains the displayed data (it has

a data column as it’s source). A data model column and a field may sound synonymous, but consider the case when a data

value (e.g. ‘123’) is defined and fetched by the data model. A PL/SQL function in the report can manipulate this value and the

new value is what is actually displayed (e.g. ‘Product Id: 123-A’). Finally, the object referenced may be a parameter (either user

or system) and these are defined in the object navigator.

Note that in the case where an object is referring to another (as is the case here), that object must have a frequency either

identical to, or higher than the object being referenced (i.e. ename) to prevent frequency errors. This can be achieved using

repeating frames and query groups. Please refer to the Oracle Reports documentation for more information on frequency,

query groups, and repeating frames.

REFERENCING DATA WITHIN PL/SQL

For similar reasons, it is useful to be able to reference object values within PL/SQL – and for Reports that typically means

within formula columns or format triggers. This is done using a colon (:) in front of the object thus:

Figure 4: Data reference within PL/SQL

Page 7: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

7

As you can see here, we are checking the value of the ‘QTY’ data model object in a format trigger, and executing some code

based on that. It should be noted however that with PL/SQL only data model objects and parameters may be referenced.

LEXICAL REFERENCES

Lexical references are placeholders for text that you embed in a SELECT statement, and you can use lexical references to

replace the clauses appearing after SELECT. In the following case, we are using a parameter P_ORDER_BY to specify the

order-by clause of the select statement:

Figure 5: Using a lexical variable to specify an ORDER BY clause

The net effect of this is that by setting the value of the parameter P_ORDER_BY to a column name (or position), report

consumers can choose the sort order of the data they see. Note that the parameter requires a default value for the report to

compile and run at all, so a value of ‘1’ (i.e. order by the first column) can be used. Also, the Break Order property for

columns in the data model can override this ordering, so they should be switched off on all columns where possible.

THE CGI MAP FILE

Thanks to the Reports thin client web interfaces (the Reports CGI or Reports cartridge for OAS), running a report on the web

is simply a matter of entering a URL – just how you would fetch almost any document on the web. A single URL can specify

all the required information to run the report (i.e. what report to run, what format to produce the output in, what to do with

the output (eg print it) whether to schedule the report, etc. etc.) Whilst this is very powerful and gives developers the most

Page 8: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

8

flexibility, it can also lead to very long URLs which can be difficult to ask report consumers to type in, or to embed in other

Reports and HTML documents. Consider the example below:

http://pnarth-pc.us.oracle.com/ows -bin/rwcgi60.exe?module=d:\temp\emp1+desformat=html

+server=repsrv60+destype=cache+empdept=10

After automatically requesting the user’s authentication information, this will dynamically execute the emp1 report for

department 10, produce the output in HTMLCSS, and return the contents to the user’s browser (the plus is one of the

standard argument separators in URL’s).

To briefly split the URL apart into it’s constituent components, the machine hostname is ‘pnarth-pc.us.oracle.com’, and it’s

executing a CGI executable (‘rwcgi60.exe’) located in the ‘/ows-bin’ virtual directory. The rest of the URL comprises the

arguments to the CGI program to run the report. As you can see, the URL can become quite long! To get around this

problem, the CGI (or OAS) mapfile feature can be used. This file is set up by the report developer/administrator when they

are ready to deploy the report on the web. It holds all the command lines and a single keyword to refer to each command line

and is located by default in the filesystem in the directory: $ORACLE_HOME/report60/server. A sample command line in

the mapfile may look like the following:

emp_rep: report=d:\temp\emp1 server=repsrv60 desformat=html destype=cacheempdept=%1

The URL (which may be bookmarked, embedded in other reports/HTML documents, or typed in) now becomes:

http://pnarth-pc.us.oracle.com/ows -bin/rwcgi60.exe?emp_rep+10

The CGI or OAS interface expands the keyword to the full request and communicates it securely to the Reports Server which

dynamically runs the report as before. Note the ‘%1’ means replace the %1 in the mapfile entry with the first value passed to

the CGI after the key. In this case, since the key is ‘emp_rep’, %1 is replaced with ‘10’. The numbers 0 to 9 can be used in

this manner (0 being the key itself), and there is an ‘escape’ mechanism (‘%*’) which gives developers the ability to allow extra

information to be passed along particular URLs.

Consider the following mapping:

Page 9: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

9

emp_rep: report=d:\temp\emp1 server=repsrv60 desformat=html destype=cacheempdept=10 %*

This permits the following URL to be submitted:

http://pnarth-pc.us.oracle.com/ows -bin/rwcgi60.exe?emp_rep+10+ mynewparam=20

In this case, the report developer/administrator is allowing an extra parameter (‘mynewparam’) to be passed to the report with

a value of 20.

ENHANCING REPORTS FOR THE WEB

Now we have covered the pre-requisites, we will take a look at enhancing our reports for the web. First, it will help to outline

the scenario or context of our reports.

Let us assume that we have a report showing customer orders (see Figure 1 at the start of this paper). For each customer, we

will show the orders they have placed, and for each order we will show the item number, and quantity sold, and a few other

details that make up that order.

IMPLEMENTING DRILL-DOWN BETWEEN WEB REPORTS

Drill-down is perhaps the most common requirement of web-based reporting. In the paradigm of the web, hyperlinks are the

customary way of obtaining more information on a particular bit of content. This is very easy to implement in Oracle Reports.

For our application, we would like the ability to drill down for a particular order item and see what exactly that product is.

The first thing to do is to write a report that will give the full product information (and perhaps an image) for a particular

product. Since each item has a unique identifier (a product id) we need to create a user parameter (‘p_prodid’) in the report

definition and parameterize the query so that it will returns the item information for a given item number (or p_prodid). The

query looks like the following:

select * from items where prodid = :p_prodid

Page 10: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

10

Once this report is written, we can create the following mapfile entry:

item: report=d:\app\item server=repsrv60 desformat=html destype=cachep_prodid=%1

and we can run this report on the web by entering the following URL in a browser:

http://pnarth-pc.us.oracle.com/ows -bin/rwcgi60.exe?item+100871

By changing the last argument in the above URL, we can obtain item information about different items since it is passed

through as the value of the p_prodid parameter, and thus used in the query.

Now we need to embed this URL in the master report which shows the customer orders, but make it sensitive for a particular

product id. A point to note here is that it is not required to embed the hostname. We are calling this URL from another, and

thus when the browser sees a virtual URL for a hyperlink (such as /ows-bin/rwcgi60.exe?item+100871), it will

append the current host.

The 'prodid' column is being fetched as part of the order information (essentially a foreign key). After opening the master

report in the report builder, we select the column from where it is appropriate for us to drill-down on. In this case it’s the

product id field in the order.

Page 11: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

11

Figure 6: Drill-down candidate field

As illustrated, we open the property palette for this field, and scroll down to the hyperlink property where we simply add the

hyperlink. Of course it needs to be sensitive to the change in PRODID, and thus we need to pass &<PRODID> as the

product id argument in the URL:

Page 12: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

12

Figure 7: Adding a drill-down report hyperlink

Running this report now on the web, we are able to drill down from the master report containing the order information to a

particular detail report.

CHART HYPERLINKING AND DRILL-DOWN

It can often be easier to understand (as well as being more aesthetically pleasing) to view a chart or graph, rather than a table

of data. Introduced with Reports 6.0 is the ability to add a hyperlink to charts that are embedded within a report. More

Page 13: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

13

specifically, you can specify the hyperlink to be different for each chart section. For example, suppose there is a pie chart

showing the total product sales (where each slice represents the quantity of each product sold). A report consumer may click

on a particular slice and drill-down to another report to see the particular product in question. Once again, this can be

achieved by setting a property for the chart object, as is illustrated:

Figure 8: Using chart hyperlinks

Note that we are able to pass data in exactly the same way (using the & notation) as we did when adding a hyperlink to a field.

Page 14: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

14

PROMOTING PORTABILITY

The hyperlink properties that have been set in these examples now contain the virtual path, the command to run a report, as

well as the keymap name to that report (as well as the data column name). Whilst the column may not change all that often

(and if so will require a major change to the report query, etc.), it is conceivable that the report may be copied and run on a

different host. This new host may very well have different virtual directories defined, a different executable to run a report,

and possibly a different keymap entry. To eliminate the hard-coding of these elements of the hyperlink and make the reports

easily portable, extra parameters should be set up in the report.

E.g.:

p_runrep = /ows-bin/rwcgi60.exe

p_detail_report_name = item

The hyperlink URLs that are included are now set up with these parameters:

Page 15: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

15

Figure 9: Using parameters for hyperlink portability

The parameter values (containing the virtual directory, keymap, etc.) can be either specified in the mapfile, specified as default

parameter values in the report, or fetched from a database table or even a text file.

IMPLEMENTING SORTING

Something often seen on web pages today is the ability to sort a table of data by simply clicking on a column name. Given the

concepts that we have already explored, this can be implemented in a manner virtually identical to drill-down hyperlinks –

except the ‘drill’ in this case is back to the same report. By adding a lexical reference (i.e. parameter) to the query for an

ORDER BY clause, we can code the hyperlink to the (boilerplate) column header to pass the column name as the ORDER

BY parameter value to re-run the same report, and thus achieve user-driven sorting.

Page 16: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

16

CUSTOMIZING PAGE-ON-DEMAND

Page-on-demand is a feature of the reports server where, when report is run to the web using the report server, the first page

plus a navigation toolbar are sent back to the browser. Normally the entire document would be sent back and this may take

some time to load in the case of a large report. Report consumers are given the ability to easily move to the first, last, next, or

previous page, or they may enter a page number they wish to jump directly to. The page-on-demand feature can be ‘switched

on’ by simply adding the argument:

pagestream=yes

to either the URL or mapfile entry. This generates the following toolbar:

Figure 10: Default page-on-demand toolbar

The code (HTML and Javascript) that generates the default page-on-demand toolbar can be viewed and customized. It is a

module-level property entitled ‘Page Navigation Control Value’. One simple change that is useful for report consumers when

navigating the pages, is to know how the total number of pages there are in the complete report. This can be achieved very

easily by changing the default code contained in the property. Where the following code is to be found:

<td> <INPUT NAME="reqpage" VALUE="1" SIZE=2>

<td> <INPUT TYPE="button" VALUE=" > " onClick="forward(this.form)">

<td> <INPUT TYPE="button" VALUE=" >>" onClick="last(this.form)">

add a line so that it becomes:

<td> <INPUT NAME="reqpage" VALUE="1" SIZE=2>

<td> of &TotalPages

<td> <INPUT TYPE="button" VALUE=" > " onClick="forward(this.form)">

Page 17: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

17

<td> <INPUT TYPE="button" VALUE=" >>" onClick="last(this.form)">

By using the &TotalPages reserved parameter, we are able very easily to add meaningful information.

Figure 11: customized page-on-demand toolbar

By spending a little more time, the complete look and feel of the toolbar can be changed:

Figure 12: Further customized page-on-demand toolbar

This further customized toolbar code (and icons) is available with the Reports 6i demos and may be incorporated in other

reports.

CREATING BOOKMARKS

Just as we have implemented hyperlinks to permit report consumers to go to the information the most interests them,

bookmarks are another web concept that can be used to help consumers find the data they are looking for – essentially to

prevent ‘information overload’. In the case of our Customer Order report, it would greatly help report consumers if they were

able to navigate not only on a page basis, but be able to navigate to a particular customer’s data. This may be achieved by

setting the ‘Bookmark’ property for the object in question (in this case the customer name). Setting bookmarks causes a frame

to appear along the left hand side of the report output with the data that has been bookmarked, as illustrated:

Page 18: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

18

Figure 13: Bookmarks in action

The property may be set to a column value (e.g. &<NAME>) in which case just the data value will appear. Alternatively, it

may be set to a value in the form of x#y (where x is an outline number and y is a column value). Then the bookmarks will be

rendered with indentation. This is useful when there are multiple items to put in the bookmarks.

Page 19: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

19

For example:

Customer A

Order 1

Order 2

Order 3

.

.

Customer B

Order 1

Order 2

.

.

The outline number that is required needs to be incremented (since it is also used to define the order that the bookmarks are

displayed in). The best way of achieving this is to create a summary column in the data model in the same group as the data

column you wish to bookmark. This summary column should be defined to count on the column that you wish to bookmark

(and reset at Report level). The resulting bookmark property would look something like &<CS_NAME>.#&<NAME>

(where CS_NAME is the summary column, and NAME is the actual data column).

In the case of a group report (i.e. a report that contains break groups) such as our Customer Orders report, one easy way for

the report developer to create bookmarks is to simply invoke the Web Wizard. In the Customer Orders report, the Web

Wizard examines the report definition and recognizes that we are breaking by customer and then by order (i.e. for each

customer we are showing multiple orders, and for each order we are showing multiple items). It then offers the report

developer the choice of suitable bookmark columns:

Page 20: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

20

Figure 14: the Web Wizard

Once the developer picks the column(s), the properties are set against these objects and any necessary summary columns are

created.

ADDING ANIMATED GIFS (GIF89A)

Another common component in web pages is the animated GIF (also known as a GIF89a image). These are a set of GIF

images put together in a sequence, and can be eye-catching and generally enhance the appearance of the page. These can be

added to the report using the Link file tool, and specifying the source of the link file to be of type ‘Image URL’. The source

filename then becomes the URL to the animated GIF, and like virtually every other component it can be hyperlinked (with

parameter or data values specified using the ampersand notation). The following screen-shot shows this:

Page 21: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

21

Figure 15: Using Image URL to add animated GIF

Here, an animated GIF called Mail.gif is located in the virtual directory specified by the parameter p_image_locn. When the

report is run on the web, it will be fetched and put into space reserved for it by the white box. When clicked, it will open up

the browser’s mailer with the ‘To:’ field automatically populated with the value of the email data column/parameter

ADDING JAVASCRIPT

Javascript is a powerful browser-side scripting language. It can be used to perform such things as conditional logic, trap

events like mouse movements, and open windows. It is common to find web pages with some sort of Javascript embedded in

the page, and for our example report, we are going to pop-up a dialog box with the customer’s credit rating. This will appear

when the report consumer clicks the customer name.

Page 22: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

22

First, we need to write the Javascript code and embed it. There is a Javascript function called ‘alert’ which will pop-up a

dialog with some user-specified text, and we can create a function that accepts one argument and calls this alert routine. The

Javascript code needs to be embedded in the web page, and traditionally it is embedded at the top. We can do this in Reports

by editing the report-level property ‘Before Report value’ which contains the HTML used at the top of the report. We can

change it from:

<HTML><body dir=&Direction bgcolor="#ffffff">

to:

<HTML>

<HEAD>

<SCRIPT LANGUAGE = "JavaScript">

function showmyalert(themessage)

{alert(themessage);}

</SCRIPT>

</HEAD>

<body dir=&Direction bgcolor="#ffffff">

When the report is run, this code with the Javascript function defined will be at the top of the report. It can now be called

from a hyperlink as follows:

javascript:showmyalert(‘hello’);

This would pop-up a dialog that said ‘hello’. To put this in the context of our example, the hyperlink against the Customer

Name field will be:

javascript:showmyalert('Credit Limit: $&< creditlimit>')

once again we are able to reference parameter and data column data. When run on the web, this will look as follows:

Page 23: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

23

Figure 16: Invoking a Javascript function in a Report

ADDING JAVA APPLETS

Java applets are small browser-side compiled programs written in the Java language. These are different to Javascript and are

even more powerful – they can be entire applications in themselves. To embed a Java applet in an HTML page, a special set

of HTML tags need to be written into the HTML page.

For our example, we have a field in the database with our comments on various customers. We also have a Java applet that

can scroll a given piece of text. We want the customer comments (which vary between customers) to scroll across the screen

when we are looking at the appropriate customer.

Page 24: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

24

The first thing we need to do embed the Java applet in the HTML layout. We do this by defining a formula column in the

data model, which returns a string:

Figure 17: Adding a formula column to the data model

Then we add the HTML text that will invoke the applet as the return value of the function:

function CF_applet_textFormula return Char is

begin

Page 25: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

25

return('

<APPLET CODEBASE="'||:p_webcomponents||'/"CODE="MyScrollingApplet.class"

WIDTH=&objectwidth HEIGHT=&objectheight>

<PARAM NAME=text VALUE="'||:comments||'">

<PARAM NAME=textColor VALUE="black">

<PARAM NAME=backgroundColor VALUE="white">

</APPLET>

');

end;

This function constructs the required HTML string to invoke the applet. Since it’s in the data model at the same frequency as

the customer columns, it will be executed once for each customer retrieved.

Notice the use of parameters (in bold). The value of ‘p_webcomponents’ is the virtual directory containing the applet, and is

being concatenated into the string. The value of the ‘comments’ data model column (containing the customer comments) is

also being added. The two reserved keywords &Objectwidth and &Objectheight relate to the size of the applet and will be

explained shortly. We now need to tell Reports where to display the applet. We do this by creating a field in the Layout

Editor as illustrated below:

Page 26: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

26

Figure 18: Adding a field to the layout editor

For the field, we specify the source as the formula column we just created, and since this column contains HTML tags we

need to change the property ‘Contains HTML Tags’ to Yes. This basically tells Reports not to format the HTML for that area

of the layout – i.e. the report developer has temporarily taken control of the output.

The field is stretched to the size we want the applet to appear in. By setting the WIDTH and HEGHT parameters in the

APPLET HTML tag, we are telling the browser how much room to reserve for the applet on screen. However, Reports is

carefully calculating all the space that is required in the layout so it can determine where various objects in the report layout

should be placed. Having specified the size of the area where we want the applet tag to appear (by sizing the field), we

obviously want this correctly rendered. However - we have just told Reports that we are taking control of that part of the

screen by setting the ‘Contains HTML Tags’ property to Yes! The solution is to use two reserved variables - &ObjectWidth

Page 27: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

27

and &ObjectHeight. Reports will format the output with our tags, and then replace these two tokens with the height and

width of the associated layout object. In this way we do not mess up the geometry management that Reports is doing, but are

able to put in our own tags.

INTERNATIONALIZATION OF REPORT OUTPUT

As organizations become more global in scope there is an increasing need for a single corporate application to be used by the

global audience. Data in multiple languages can be stored in the Oracle database using a characterset (i.e. a character

encoding scheme to represent the characters). There are many charactersets defined and if data is not displayed in the

appropriate one, it will appear corrupted. Take the following example:

Figure 19: Cyrillic text rendered in the Western European characterset

This is actually some Cyrillic text. It is being rendered using the Western European characterset (ISO8859-1), and since it

does not contain the Cyrillic characters (even though the font is capable of displaying characters in that range), the output

appears corrupted. Oracle Reports supports all the charactersets that the Oracle 8i database supports (including Unicode). If

Page 28: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

28

the reports are being deployed in a truly multi-national organization on the web (and thus there are no national boundaries),

then one report consumer may have an English characterset as their default, the next consumer may have Cyrillic, the next

may have Japanese, etc. etc. In this way, reports being generated in a particular characterset and then viewed around the

world may appear to be corrupted to some consumers, and yet perfectly clear to others. For a while consumers had to obtain

the web report generated in a compatible characterset, or know to manually switch the browser. However, browser technology

has improved with time, and now by simply adding a line at the start of the Report HTML, it is possible to automatically

switch the characterset the browser is operating in. Following on from our Cryllic example, here is the appropriate tag (usually

placed within the <HEAD> and </HEAD> tags):

<META CONTENT="text/html; charset=windows-1251" HTTP- EQUIV=Content-Type >

With the above line, the browser will change the character set it is running in to the Windows-1251 characterset (which does

support Cyrillic) and thus will render the text properly:

Figure 20: Cyrillic text rendered in the Windows-1251 characterset

Page 29: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

29

Report developers can find out the character set the report is being generated under by obtaining the value of the

NLS_LANG environment variable. This is of the form LANGUAGE_TERRITORY.CHARACTERSET and an example of

this is: AMERICAN_AMERICA.WE8ISO8859P1. The last argument is the characterset. Because Oracle charactersets were

defined many years ago and it is only now that they are being defined and standardized upon (by such bodies as the IANA),

there are slightly different names between the Oracle charactersets and the 'standardized' ones. The browsers only understand

the standardized ones and so the Oracle characterset must be changed to the standard one. In appendix A, there is a list of

some of the more common standard web charactersets, and their Oracle equivalent.

CONCLUSION

It is important for Report developers to consider the medium in which their reports will be run. They should take advantage

of any features that it offers that may improve the functionality or the ‘look and feel’ of their reports.

This paper has detailed various techniques that developers may use for building enterprise-class Oracle Reports for the web,

combining powerful, unlimited data formatting with it’s advanced web publishing capabilities.

Page 30: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

30

APPENDIX A - NLS

IANA CHARACTER SET TO ORACLE CHARACTER SET CONVERSION TABLE

Please note this a list of the most common character sets and their Oracle equivalents – but it is by no means a definitive list.

− IANA character set Oracle character set

− US-ASCII US7ASCII

− ISO-8859-1 WE8ISO8859P1

− ISO-8859-2 EE8ISO8859P2

− ISO-8859-3 SE8ISO8859P3

− ISO-8859-4 NEE8ISO8859P4

− ISO-8859-5 CL8ISO8859P5

− ISO-8859-6 AR8ISO8859P6

− ISO-8859-7 EL8ISO8859P7

− ISO-8859-8 IW8ISO8859P8

− ISO-8859-9 WE8ISO8859P9

− windows-1250 EE8MSWIN1250

− windows-1251 CL8MSWIN1251

− windows-1253 EL8MSWIN1253

− windows-1254 TR8MSWIN1254

− windows-1255 IW8MSWIN1255

− windows-1256 AR8MSWIN1256

− windows-1257 BLT8MSWIN1257

− windows-1258 VN8MSWIN1258

Page 31: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

31

− EUC-JP JA16EUC

− Shift_JIS JA16SJIS

− EUC-KR KO16KSC5601

− GB2312 ZHS16CGB231280

− Big5 ZHT16BIG5

IMPLEMENTING THE ORACLE REPORTS 6I UTILITY TO CONVERT ORACLE CHARACTER SET TO IANACHARACTER SET.

The above table has been implemented as a PL/SQL function supplied with Oracle Reports 6i demos. It takes an argument in

the form of NLS_LANG (i.e.: LANGUAGE_TERRITORY.CHARACTERSET such as

AMERICAN_AMERICA.WE8ISO8859P1) as an argument, and returns the appropriate IANA character set (in this example,

ISO-8859-1). This is then applied to the generated HTML (or XML) in the following manner in an After-Parameter-Form-

Trigger:

function AfterPForm return boolean is

reports_nls_lang varchar2(255);

encoding varchar2(30);

begin

-- read the NLS_LANG env. variable

tool_env.getvar('NLS_LANG',reports_nls_lang);

-- Obtain equivalent IANA character set

encoding:=web_nls.encoding( reports_nls_lang);

srw.set_xml_prolog( srw.text_escape,

'<?xml version="1.0" encoding="'||ENCODING||'"?>');

Page 32: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Advanced Web Publishing with Oracle ReportsMarch 2000

32

SRW.SET_BEFORE_REPORT_HTML(SRW.TEXT_ESCAPE,

'<html>

<META HTTP- EQUIV="Content-Type" CONTENT="text/html;charset='||encoding||'">

<body dir=&Direction bgcolor="#ffffff">');

return (TRUE);

end;

Page 33: Advanced Web Publishing with Oracle Reports€¦ · Advanced Web Publishing with Oracle Reports March 2000 2 INTRODUCTION The proliferation of the Internet has meant that the web

Oracle CorporationWorld Headquarters500 Oracle ParkwayRedwood Shores, CA 94065U.S.A.

Worldwide Inquiries:+1.650.506.7000Fax +1.650.506.7200http://www.oracle.com/

Copyright © Oracle Corporation 1999All Rights Reserved

This document is provided for informational purposes only, and the information herein is subjectto change without notice. Please report any errors herein to Oracle Corporation. OracleCorporation does not provide any warranties covering and specifically disclaims any liability inconnection with this document.

Oracle is a registered trademark, and Oracle8i, Oracle8, PL/SQL, and Oracle Expert are trademarksof Oracle Corporation. All other company and product names mentioned are used foridentification purposes only and may be trademarks of their respective owners.