Oracle Discoverer Oracle Discoverer 3i Viewer Configuration Guide for Oracle Internet Application Server for Unix Release 3.3.57.25 A86662-01 |
|  | Contents | Index

# 4
Customizing Oracle Discoverer 3i Viewer

Oracle Discoverer 3i Viewer is easily customized to fit in with your Web site look and feel, to incorporate your companies logo or other artwork, or to build custom Discoverer applications for the Web.

This chapter covers the following areas:

- Using Oracle Discoverer 3i Viewer for Customized Web Applications

- Customization Examples

## 4.1 Using Oracle Discoverer 3i Viewer for Customized Web Applications

Customize the general appearance

The appearance of Oracle Discoverer 3i Viewer can be customized by specifying HTML formatting attributes in a single customization file. Fonts, colors and graphics are all easily changed by anyone familiar with HTML formatting.

Customize the application

Oracle Discoverer 3i Viewer can be used to build complete custom Web applications or deliver data to other middle tier Web systems. It uses industry standard XML to represent data and application state, and the XSL stylesheet language to format the User Interface. Standard XSL tools can be used to customize the User Interface or to produce a complete embedded Business Intelligence application.

How the HTML is produced

All the HTML generated by Oracle Discoverer 3i Viewer is produced as a result of combining XML, which describes the information available, with XSL which defines how that information should be represented in HTML.

The XSL configuration file defines simple attributes, such as the fonts and colors to use, but it also defines the layout of each page, and the interactions with the user. By customizing the XSL, a specific Discoverer Application can be built and delivered on the Web.

#### Figure 4-1 - Oracle Discoverer 3I Viewer HTML Generation using XSL/HTML

### 4.1.1 Steps to Generate the HTML needed to build a specific Discoverer Application

#### 4.1.1.1 Step 1 Browser sends URL

After login, let's assume a Discoverer Viewer has asked for a list of workbooks that they are allowed to open in order to do some analysis of their business. The URL issued is:

http://myserver.mycompany.com/disco/disco3iv?us=video&db=Disco

The URL specifies the machine the Servlets are installed on, and the username and database connection string to use. The password is not normally shown on the URL for security reasons.

#### 4.1.1.2 Step 2 XML generation

The URL is processed by the Discoverer Servlet, and the Discoverer Services is instructed to check the security setting for this user and return details of the workbooks that this user is allowed to access. The security settings are held in the End User Layer tables in the database. After this information is returned from the server, the Servlet generates the following XML:

    <?xml version="1.0"?>
    <?xml-stylesheet type="text/xsl" href="example1.xsl"?>
    <discoverer version="3.3.x.x" login_method="discoverer">
       <request source="http://myserver.mycompany.com/servlets/viewer">
          <command name="_act">Connect</command>
          <command name="db">disco</command>
          <command name="in">dwb</command>
          <command name="_in">dwb</command>
          <command name="lc">true</command>
          <command name="us">VIDEO</command>
          <command name="JServSessionId">3fb75a688d4d3c68.97.951319520796</command>
       </request>
       <account>
          <user>VIDEO</user>
          <database>disco</database>
          <eul default="true" name="VIDEO">
             <workbook name="Annual Sales Report" ref="Annual+Sales+Report">
                <description>Shows yearly and quarterly sales of
    products</description>
             </workbook>
             <workbook name="Store and Band Analysis" ref="Store+and+Band+Analysis">
                <description>Shows sales by Store, broken into sales
    bands</description>
             </workbook>
             <workbook name="Video Sales Analysis" ref="Video+Sales+Analysis">
                <description>General purpose analysis of the Business </description>
             </workbook>
          </eul>
          <option name="qpw" enable="false">60</option>
          <option name="qrl" enable="false">10000</option>
          <option name="qtl" enable="false">1800</option>
          <option name="msa" enable="false">60</option>
          <option name="qif">250</option>
          <option name="qll">15</option>
          <option name="aq">true</option>
          <option name="nv">NULL</option>
          <option name="ftd">true</option>
          <option name="rpp">25</option>
       </account>
       <export name="xls" format="application.vnd.ms-excel">Microsoft Excel Workbook
    (*.xls)</export>
       <export name="htm" format="text.html">Hyper-Text Markup Language
    (*.htm)</export>
       <export name="txt" format="text.plain">Text (Tab delimited) (*.txt)</export>
       <export name="csv" format="text.plain">CSV (Comma delimited) (*.csv)</export>
       <export name="prn" format="text.plain">Formatted Text (Space delimited)
    (*.prn)</export>
       <export name="dcs" format="text.plain">DCS (Express Format) (*.dcs)</export>
       <export name="dif" format="application.vnd.ms-excel">DIF (Data Interchange
    Format) (*.dif)</export>
       <export name="slk" format="application.vnd.ms-excel">SYLK (Symbolic Link)
    (*.slk)</export>
       <export name="wks" format="application.vnd.ms-excel">WKS (Lotus 1-2-3)
    (*.wks)</export>
    </discoverer>

You can see information about three workbooks being returned - Store and Band Analysis, Video Sales Analysis and Annual Sales Report. Note there is NO information in the XML about how these workbooks names and descriptions should be displayed to the user, this is the function of the XSL file.

#### 4.1.1.3 Step 3 Apply XSL

XSL is the industry standard stylesheet language defined by the World Wide Web Consortium. It allows a selection of elements from an XML file to be combined with an HTML template to generate HTML output for a Web Browser. The Oracle Discoverer 3i Viewer User Interface is entirely defined in XSL, which means that it can be customized or copied to define alternative User Interface styles using standard Web development tools such as HTML and XSL editors. The XSL and XML is combined in an XSL processor, and HTML is generated.

#### 4.1.1.4 Step 4 Generate HTML

Given the XML above, the standard Oracle Discoverer 3i Viewer XSL configuration file would result in HTML being generated, which is then sent back to the browser in response to the initial URL. In Oracle Discoverer 3i Viewer, the HTML generated does not use frames or javascript, and therefore makes minimal demands on the browser or Internet device used. It also means that it is easy to integrate Oracle Discoverer 3i Viewer with other Web Applications or Portals.

## 4.2 Customization Examples

This section will help you carry out a customization of the Oracle Discoverer 3i Viewer user interface where you can either modify basic attributes such as fonts, colors and graphics or create your own look and feel with a custom user interface.

### 4.2.1 Files needed for customization

The files needed to carry out either a Quick or a Full customization can be found under the html/ directory shown below. These directories are created during the installation of Oracle Discoverer 3i Viewer in the root directory of the Web server.

disco3iv/
|  | disco3iv.jar
|  | html/
|  |  | disco3iv.xml
|  |  | disco3iv.xsl
|  |  | errors.xsl
|  |  | functions.xsl
|  |  | gui_components.xsl
|  |  | page_layouts.xsl
|  |  | style.xsl
|  |  | demos/ | Video Stores Demo
|  |  | help/ | HTML help files
|  |  | images/ | User inteface and help
|  | doc/ | Installation/Administration Doc

### 4.2.2 Quick Customization

Many users want to be able to simply modify fonts and colors to fit in with their corporate standards, or to display the company logo to add branding.

These global changes can be made in a single XSL stylesheet file `style.xsl'(found in the Servlet directory disco3iv/) that defines special `tags' for each style that can be modified.

You will need to be able to access the XSL files on the server.

#### 4.2.2.1 Quick customization attributes

Customizable attributes in the style.xsl file

- Company Logo

- Text Color

- Headings

- Fonts

- Styles

- Links

- Images

#### 4.2.2.2 Quick customization steps

To complete a Quick customization, take the following steps:

- Locate the file style.xsl in the Servlet directory \disco3iv\html.

- Open style.xsl in a text editor.

- Edit text within the >angle brackets< for each variable you want to change.
  For further information, read the detailed comments inside the file itself.

- Save your changes and exit.

#### 4.2.2.3 Example of editing the style.xsl file

Further comments on how to edit this file are included within the file itself.

To insert a logo

<xsl:variable name="logo_src"> </xsl:variable name>

is changed to

<xsl:variable name="logo_src"> http:www.mycompany.com/images/mylogo.gif </xsl:variable name>

To change the color of the text:

<xsl:variable

name="text_color">#000000</xsl:variable>

is changed to add the appropriate color code.

Many global style changes can be made in this way, but the overall operation of the User Interface will remain unchanged.

Another way of customizing Oracle Discoverer 3i Viewer is by using XSL, which allows a complete customized application to be made, as the next section explains.

### 4.2.3 Full Customization

This section provides information to help you create a fully customized user interface to the Oracle Discoverer 3i Viewer Servlet. Creating your own `look and feel' with a custom user interface.

It consists of the following topics:

- Background

- Prerequisites

- File Structure

- Servlet Programming Interface

- Customizing Look and Feel - XML/XSL Example

- Customization Summary

#### 4.2.3.1 Background

Before you start creating a custom interface to the Oracle Discoverer 3i Viewer Servlet, it is useful to understand how it works.

The following steps describe the flow of data that occurs when a request is made:

- The request is sent from the client (Web browser) to the Servlet using HTTP.
  Usually the request is encoded on the URL but the Servlet also supports GET and POST actions.

- The Servlet interprets this request and retrieves the necessary data from the Discoverer Server.

- The Servlet reformats the data returned from the Discoverer Server as XML.

- This XML file is sent to the XSLT processor which transforms it into the final output (usually HTML) using XSL templates.

- The output is then streamed back to the client that originally made the request.

This model enables a clean separation between the application logic (handled by the Servlet) and the presentation logic (handled by the XSL files). It is therefore possible to completely change the appearance of the user interface by editing the XSL files.

Figure 4-2 illustrates the data flow in Oracle Discoverer 3i Viewer.

#### Figure 4-2 Oracle Discoverer 3i Viewer Data Flow

#### 4.2.3.2 Prerequisites

To be able to create your own custom user interface for Oracle Discoverer 3i Viewer, you need the following prerequisites:

- A knowledge of HTML

- A knowledge of XML, XSLT & XPath

- Access to the XSL files on the server.

- Access to the Servlet Configuration File

#### 4.2.3.3 File Structure

The Servlet Configuration File specifies the name and location of the XSL file that should be applied to the XML generated by the Servlet. This XSL file imports further XSL files which together contain all the templates that required for the presentation logic. These files are described below.

##### 4.2.3.3.1 disco3iv.xsl

This is the master XSL file. It performs the following functions:

- Gets the values of certain parameters set in the Servlet Configuration File.

- Gets the values of "Presentation" commands sent from the client.

- Imports the other XSL files.

- Examines the XML and chooses the most appropriate page layout for displaying the information.

##### 4.2.3.3.2 page_layouts.xsl

This file contains the definitions for each type of page that can be displayed. Each definition consists of a series of GUI components (in the order that they should appear on the page).

The following page layouts have been defined:

- Connect Page

- Reconnect Page

- Choose Oracle Applications Responsibility Page

- Options Page

- Choose Workbook Page

- Prepare to Run Query Page

- Modify Query Parameters Page

- Query Progress Page

- Data Available Page

- Export Worksheet Page

##### 4.2.3.3.3 gui_components.xsl

This file contains each of the GUI components (called by page_layouts.xsl) that are used to build a page. The following list provides a few examples of GUI components:

- Page Title

- Page FooterList of Worksheets

- Options Form

- Query Progress Meter

##### 4.2.3.3.4 style.xsl

This file acts as a "stylesheet" by defining how certain text (such as headings) and graphics should appear. For more information, see the comments inside the file itself.

##### 4.2.3.3.5 functions.xsl

This file contains a set of functions that perform common tasks. For example, building the href attribute when creating a hypertext link.

##### 4.2.3.3.6 errors.xsl

This file interprets any errors, warnings or messages generated by the Discoverer Server and displays more user friendly versions.

#### 4.2.3.4 Servlet Programming Interface

##### 4.2.3.4.1 Receiving data from the Servlet

There are two methods that the Servlet can use to pass information to the XSL files:

- XML
  The XML contains all the information returned by the Discoverer Server as a result of the end user's request.

- XSL Parameters
  This method is used to pass entries in the Servlet Configuration File and "Presentation" commands from the URL to the XSL.

##### 4.2.3.4.2 Sending data to the Servlet

As mentioned above, the Servlet is driven by the commands it receives from the client (Web browser). These commands are sent using HTTP by calling the Servlet with parameters on the URL or by creating HTML forms that define the Servlet as the "action".

You can create your own "Presentation" commands by simply preceding it with an underscore (_) character. Any commands that begin with an underscore character are passed straight through to the XSL files as an XSL parameter. For example, specifying _filter=sales as a parameter on the URL results in the Servlet setting the XSL parameter "url_filter" to "sales". You could use this parameter to filter a list of workbooks.

#### 4.2.3.5 Customizing Look and Feel - XML/XSL Example

XSL customization is best shown with an example. You can use the XML and XSL fragments below to experiment with customization in a Web Browser.

##### 4.2.3.5.1 Step 1 - The XML file

The data is a standard XML file, similar to the example below:

    <?xml version="1.0"?>

    <?xml-stylesheet type="text/xsl" href="example1.xsl"?>

    <discoverer3iv version="3.3.x.x" state="login"

    url="http://myserver.mycompany.com/disco/disco3iv" login_method="disco_
    login">
       <account nv="NULL" aq="confirm">
          <user>video</user>
          <database>disco</database>
          <eul>
             <name>VIDEO</name>
             <workbookinfo>
                <name>Store and Band Analysis</name>
                <description>Shows sales by Store, broken into sales
    bands</description>
             </workbookinfo>
             <workbookinfo>
                <name>Video Sales Analysis</name>
                <description>General purpose analysis of the Business
    </description>
             </workbookinfo>
             <workbookinfo>
                <name>Annual Sales Report</name>
                <description>Shows yearly and quarterly sales of
    products</description>
             </workbookinfo>
          </eul>
       </account>
    </discoverer3iv>

It starts by specifying the XML version. The 2nd line specifies the XSL file to be applied to process the data, "example1.xsl" and the rest of the file is generated from the Oracle Discoverer 3i Viewer. The first two lines have been added here so you can type the text into a file using a text editor and then open it in a Web Browser to see the results visually as the XSL is changed. Save the file with the extension "xml" if you want to try this.

##### 4.2.3.5.2 Step 2 - The XSL file

The XSL file "example1.xsl" looks like this:

    <?xml version='1.0'?>
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/TR/WD-xsl">
      <xsl:template match="/">
        <HTML>
          <BODY bgcolor="#FFFFFF" link="#663300" text="#000000">
            <b><i>Choose a Workbook :</i>	</b><P></P>
            <TABLE BORDER="2">
              <xsl:for-each select="discoverer/account/eul/workbook">
                <TR>
                  <TD width="242"><font face="Arial"><b><a href="link.htm">
                    <xsl:value-of select="./@name"/></a></b></font>
                  </TD>
                  <TD>
                    <xsl:value-of select="description"/>
                  </TD>
                </TR>
              </xsl:for-each>
            </TABLE>
          </BODY>
        </HTML>
      </xsl:template>
    </xsl:stylesheet>

##### 4.2.3.5.3 Step 3 - XML+XSL = HTML

When the XML file is opened in a Web Browser, it reads in the XSL stylesheet and generates HTML which looks like this:

#### Figure 4-3 List of workbooks using XML + XSL example

Examining the XSL file shows how the HTML is generated. Again the file starts by specifying the XML version, and the 2nd line says that this file is a stylesheet. The HTML template starts with the <HTML> tag on line 4.

<BODY bgcolor="#FFFFFF" link="#663300" text="#000000">

This line defines the colors to be used.

<b><i>Choose a Workbook:</i></b><P></P>

This is just HTML, it sets a bold italic font and inserts the text "Choose a workbook"

<TABLE BORDER="2">

<xsl:for-each select="discoverer/account/eul/workbook">

Now an HTML table is started, with a 2 line border. The next line is the first real XSL to appear - it means:

Go through the XML data file and for each workbook tag perform all the following steps until you reach the end tag: </xsl:for-each>

So for every workbook that appears in the XML file the following XSL is processed, and a row is inserted into the HTML table for every workbook found:

                <TR>
                  <TD width="242"><font face="Arial"><b><a href="link.htm">
                    <xsl:value-of select="./@name"/></a></b></font>
                  </TD>
                  <TD>
                    <xsl:value-of select="description"/>
                  </TD>
                </TR>

<TR> starts a new row in the table, and <TD defines the table data that is to be inserted for the first column. The width of the column is set to 242 pixels and the font is set to Arial. Next a hyperlink is defined that will go to the file "link.htm" when clicked. In fact in Discoverer 3i this link target is generated dynamically, but it is shown as a static link here for simplicity.

    <xsl:value-of select="./@name"/></a></b></font>

This XSL line inserts the text from the XML file for the <NAME> tag under each workbook section.

                   <TD>
                    <xsl:value-of select="description"/>
                   </TD>

These lines define the 2nd column in the HTML table and insert the text for the workbook description using the <DESCRIPTION> tab in the XML file. So each row in the HTML table will contain the workbook name, made into a link to click on, and the workbook description as text. Since there are three workbooks in the XML file, there will be three rows in the table.

Note that this example is not exactly how the Oracle Discoverer 3i Viewer shows the list of workbooks, it has been simplified here for clarity, but it illustrates how the XSL controls the appearance of the output. Also note that in Oracle Discoverer 3i Viewer, the XML and XSL are combined in the XSL processor on the middle tier, and not in the Web Browser.

##### 4.2.3.5.4 Step 4 - Customize the XSL

We can modify the XSL file to appear as follows:

    <?xml version='1.0'?>
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/TR/WD-xsl">
      <xsl:template match="/">
        <HTML>
          <BODY bgcolor="#FFFFFF" link="#663300" text="#000000">
            <b><i>Choose a Workbook :</i></b><P></P>
            <TABLE BORDER="0">
              <TR>
                <TD width="500" height="100" background="../../images/disco_
    banner.gif">
                  <font face="Arial"><b>Performance Reports</b></font>
                </TD>
              </TR>
            </TABLE>
            <TABLE border="0">
              <xsl:for-each select="discoverer/account/eul/workbook">
                <TR>
                  <TD width="242">
                    <a href="link.htm">
                      <img src="../../images/start1.gif">
                        <xsl:attribute name="alt">
                          <xsl:value-of select="description"/>
                        </xsl:attribute>
                      </img>
                    </a>
                  </TD>
                  <TD>
                    <font face="Arial">
                      <xsl:value-of select="./@name"/>
                    </font>
                  </TD>
                  <TD>
                    <xsl:value-of select="description"/>
                  </TD>
                </TR>
              </xsl:for-each>
            </TABLE>
          </BODY>
        </HTML>
      </xsl:template>
    </xsl:stylesheet>

When this file is combined with the same XML, is appears as:

#### Figure 4-4 List of workbooks using the same XML with a modified XSL stylesheet

Now the appearance of the User Interface is completely different, as it takes on a more graphical look and feel. Instead of text links there are graphical buttons for running the reports, each with a dynamic `tool tip' that pops up when you position the mouse over the button.

The XSL file is now different:

    <TABLE BORDER="0">
              <TR>
                <TD width="500" height="100" background="../../images/disco_
    banner.gif">
                  <font face="Arial"><b>Performance Reports</b></font>
                </TD>
              </TR>
            </TABLE>
            <TABLE border="0">

These lines create a table and insert a graphic and the heading "Performance Reports"

    <TABLE BORDER="0">
              <xsl:for-each select="discoverer/account/eul/workbook">
    </TABLE>

This starts the main table that the workbook names will be displayed in, as before, but now there is no border around the table and the rows are defined differently:

                  <TD width="242">
                    <a href="link.htm">
                      <img src="../../images/start1.gif">
                        <xsl:attribute name="alt">
                          <xsl:value-of select="description"/>
                        </xsl:attribute>
                      </img>
                    </a>
                  </TD>

The first table data column is defined as a hyperlink again, but this time with the image "start1.gif" as an image, rather than a text link. To get a "tooltip" to appear over an image the HTML "ALT" attribute is used.

Normally the ALT attribute is used with a simple text string:

    <img src="start1.gif" alt="Tooltip text to appear when a mouse is
    over the image">

but since we want the tool tip to be dynamic we generate the ALT tag by getting the text from the <DESCRIPTION> tab in the XML file. The <XSL:ATTRIBUTE> tag is used to do this.

Finally:

                 <TD>
                   <font face="Arial">
                   <xsl:value-of select="./@name"/></font>
                 </TD>

The second column in the table simply selects the name of the workbook to display, by using XSL to get it from the XML file as before.

### 4.2.4 Video Stores Demo - an example of an alternative user interface

The Video Stores demo is installed with Oracle Discoverer 3i Viewer and can be viewed following completion of a number of setup steps.

Once Oracle Discoverer 3i Viewer has been fully installed you can configure your Web server to run the Video Stores demo.

The Video Stores demo illustrates how the Oracle Discoverer 3i Viewer user interface could be customized for an imaginary Video Store chain. You will be able to see the details which lie behind the user interface.

#### 4.2.4.1 What is installed

During installation, the Video Stores demo directory demos/video, its sub directories and files are created. The /demos/video directory is installed under the [Disco3iv_Home]/disco3iv/html directory.

In the Video Stores demo directory /demos/video the following files are installed:

- disco3iv.xml
  You may need to edit this file to ensure that it refers to the correct session name.
  The disco3iv.xml file contains configuration information such as where to find images for the user interface (See disco3iv.xml for details).

- video.xsl
  You can edit this file to create the new user interface.
  This file contains all the definitions which control the `look and feel' of the user interface, such as the fonts, images, background, and spacial details.

- Workbooks - These are used in the Video Stores Demo (See Section 4.2.4.2, "Set up steps")
  - Food and Drink.dis
  - Games.dis
  - Movies.dis

The \demos\video\images directory contains all the images used in the Video Stores user interface. This is where you would place any new images the user interface needs to use.

#### 4.2.4.2 Set up steps

You need to carry out the following steps:

- Create a Video Stores Demo database user
  (See the Oracle Discoverer 3.1 Administration Guide for details about how to create a new database user).

- Install the Video Stores Tutorial into the Video Stores Demo user created in the previous step.
  (See the Oracle Discoverer 3.1 Administration Guide, section on installing the Tutorial for details).

- Using Oracle Discoverer Plus, save the three Video Stores Demo workbooks into the database as the Video Stores Demo user.

- Edit the video.xsl file to point the username, password and database name to the newly created Video Stores Demo user. The video.xsl file is currently set up to point to a username us=videodemo, password ps=videodemo and database db=disco.
  This is the only change that you need to make to video.xsl.

#### 4.2.4.3 Set up Web Server

The Web server needs to be configured with the `Zone' name. You need to set up a new zone for the Video Stores Demo to specify the location of the \demos\video\disco3iv.xml (Video Stores Demo configuration file)

#### 4.2.4.4 Run the Video Stores demo

Open a Web browser and enter the following URL:

- http://yourmachineURL/'Your new Video Demo Zone'

The Video Stores demo will be displayed:

#### Figure 4-5 The Video Store demo

#### 4.2.4.5 Modify the video.xsl file

The video.xsl file located in [Disco3iv_Home]/disco3iv/html/demos/video/ specifies the `look and feel' for the Video Stores Customization of Oracle Discoverer 3i Viewer.

For example, you can edit the video.xsl file to replace any of the images displayed, including the background. You can also specify the workbooks you want to display in the Demo.

The ability to alter almost everything displayed by editing the video.xsl file illustrates how you can create not only a look and feel for your organization, but also define unique views of your data.

### 4.2.5 Customization Summary

XML and XSL provides a powerful customization environment for Oracle Discoverer 3i Viewer. Simple global formatting changes are made to a single style sheet file, while more sophisticated custom applications can be made by using completely alternative XSL processing. In this way Oracle Discoverer 3i Viewer provides the way to integrate Business Intelligence directly into other Web applications.

| Copyright © 2000 Oracle Corporation. All Rights Reserved. |
|  | Contents | Index