10
Customizing Discoverer Viewer

10.1 Customizing Discoverer Viewer

This chapter explains how to provide a customized Discoverer Viewer look and feel to end users. For example, you might want to replace Discoverer's Oracle logo with your organization's logo, or change text colors and styles.

Note: Discoverer Viewer end users can also configure the user interface themselves on a per-session basis by setting their own presentation options (for more information, see "About presentation options").

This chapter contains the following topics:

• Section 10.2, "What is Discoverer Viewer customization?"

• Section 10.3, "What tools do you need to customize Discoverer Viewer?"

• Section 10.4, "About updating Discoverer Viewer CSS files"

• Section 10.5, "About updating Discoverer Viewer XML files"

• Section 10.6, "About presentation options"

• Section 10.7, "About presentation templates"

• Section 10.8, "About the sample browser look-and-feel file (blaf.htm)"

• Section 10.9, "How to change the default Discoverer Viewer look and feel"

• Section 10.10, "How to change the default Discoverer Viewer logo"

• Section 10.11, "How to remove Discoverer Viewer user interface options"

• Section 10.12, "How to create a presentation template"

• Section 10.13, "How to run Discoverer Viewer with Javascript disabled"

10.2 What is Discoverer Viewer customization?

You customize Discoverer Viewer to change the default look and feel that you provide to Discoverer Viewer end users, or to provide end users with pre-defined presentation templates. For example, you might want to:

• change Discoverer's font styles to match your organization's Internet look and feel (for more information, see "How to change the default Discoverer Viewer look and feel")

• change Discoverer's default logo to a logo or graphic of your choice (for more information, see "How to change the default Discoverer Viewer logo")

• provide presentation templates that add and remove user interface components (e.g. header and footers, drill icons, row numbers) from Discoverer Viewer (for more information, see "About presentation options" and "How to create a presentation template")

• run Discoverer Viewer with Javascript disabled (for more information, see "How to run Discoverer Viewer with Javascript disabled"

You customize Discoverer Viewer by changing values stored in the following types of industry standard files that Discoverer uses to configure the user interface.

• Cascading Style Sheet (CSS)

• Extensible Markup Language (XML)

Notes:

• If you do customize Discoverer Viewer, you are responsible for migrating customizations across Discoverer versions.

• You can also provide a customized Discoverer Viewer look and feel by providing a bookmarked URL to end users. The URL contains presentation option settings that you set in the original Discoverer session.

• For more information about XML files, refer to the W3C World Wide Web Consortium Web site at http://www.w3.org/.

• If your organization does not allow browsers to work with Javascript enabled, you can also disable Javascript. You can disable Javascript in two ways:
  • on a per-browser basis - for more information, refer to your browser's Help to find out about disabling Javascript

  • on a global basic for all users - for more information, see "How to run Discoverer Viewer with Javascript disabled"

10.3 What tools do you need to customize Discoverer Viewer?

To customize Discoverer Viewer, you need to edit text files on the Discoverer Web server using one of the following:

• a simple text editor

• a dedicated XML editor (e.g. Altova's XML Spy)

Note: Dedicated XML editors are preferable because they make XML files easier to navigate and amend.

10.4 About updating Discoverer Viewer CSS files

The Discoverer Viewer CSS file contains tags for each component of the Discoverer Viewer user interface that you can customize. The figure below shows an example of a blaf.css file.

Figure 10-1 An example of a blaf.css file displayed in an XML editor

Text description of the illustration cust_7.gif

Key to figure:

1. A blaf.css file opened in a dedicated XML editor

2. A tag (OraBGGreyVeryDark) for one of the Discoverer Viewer background colors.

3. The value of the tag (#333333), which is the RGB code for the color.

4. Tags for other Discoverer Viewer styles.

To customize Discoverer Viewer, you change the value of the tags.

Notes

• For more information about RGB color codes, refer to any standard HTML reference manual.

• For more uniform results, use colors consistent across different browser types (i.e. safe colors) when customizing font styles.

• For more information about using the Discoverer Viewer cascading style sheet and its accompanying look-and-feel sample HTML file, see "About the sample browser look-and-feel file (blaf.htm)".

10.5 About updating Discoverer Viewer XML files

The Discoverer Viewer XML files contain tags for each component of the Discoverer Viewer user interface that you can customize (for more information, see "About presentation options"). The figure below shows an example of a ui_config.xml file.

Figure 10-2 An example of a ui_config.xml file displayed in an XML editor

Text description of the illustration cust_2.gif

Key to figure:

1. A ui_config.xml file opened in a dedicated XML editor.

2. A copy of the Corporate Look presentation template, called My Look.

3. A tab called 'log', which determines when the Discoverer Viewer logo is displayed.

4. The value of the 'log' tag (false), which means that the Discoverer Viewer logo or customized organization logo is not displayed. To change this tag value to true, double click the value field and choose 'true' from the drop down list.

If you use a dedicated XML editor, the XML tags are displayed in a structured way that you can expand or contract, and you can choose values using drop-down lists.

If you use a simple text editor to edit an XML file, tags are displayed in plain text format, without additional formatting.

Figure 10-3 The ui_config.xml file displayed in a simple text editor

Text description of the illustration cust_3.gif

To update a tag value, simply replace the tag value with a new value. For example, to hide a user interface component, change its tag value from to 'true' to 'false'.

Note: The ui_config.xml file contains additional comments and tag labels to help you when making amendments. Comments are enclosed in the following tags: <!-- Comments -->

10.6 About presentation options

Presentation options define areas of the Discoverer Viewer user interface, such as headers, page areas, and footers. For example, in the worksheet area, you might not want to display worksheet headings or drill icons to Discoverer Viewer end users.

Figure 10-4 Discoverer Viewer customization using presentation options

Text description of the illustration cust_10.gif

In the figure above, Discoverer Viewer has been customized by removing the Discoverer logo, New Connection button, Open Workbook button, page footer, and export option.

You can also store presentation options in presentation templates and make them available to Discoverer end users (for more information, see Section 10.7, "About presentation templates").

Note: You can also remove Discoverer UI components by editing the ui_config.xml file (for more information, see Section 10.11, "How to remove Discoverer Viewer user interface options").

10.7 About presentation templates

Presentation templates are sets of pre-defined presentation options, and are used to enable Discoverer Viewer end users to customize the Discoverer Viewer UI with a single click.

Note: Discoverer Viewer end users can also set their own presentation options on a per-session basis using the Presentation Options page in Discoverer Viewer.

Figure 10-5 Discoverer Viewer Presentation Options page

Text description of the illustration cust_4.gif

Key to figure:

1. Presentation options, which determine which Discoverer Viewer components are displayed. For example, the List Of Worksheets is turned off, and the Page Header Logo is turned off.

2. Presentation templates, which apply pre-defined presentation options. In this example, two presentation templates are available to Discoverer Viewer end users (Corporate Look and Money Portal Look). To apply the Money Portal Look presentation options to Discoverer Viewer, the user clicks the Money Portal Look option. The presentation options are then updated with the values stored in the ui_config.xml file.

Figure 10-6 The ui_config.xml file and the Presentation Options page

Text description of the illustration cust_5.gif

In the figure above, the state of the presentation options (i.e. true or false) is used to determine whether user interface components are displayed. These options are represented by check boxes on the Presentation Options page. For information about how to create presentation templates, see "How to create a presentation template".

Note: You can also remove Discoverer UI components globally by editing the ui_config.xml file (for more information, see Section 10.11, "How to remove Discoverer Viewer user interface options").

10.8 About the sample browser look-and-feel file (blaf.htm)

To help you customize Discoverer Viewer's look-and-feel, Discoverer is installed with a sample browser look-and-feel file (blaf.htm). The blaf.htm file displays the current look-and-feel settings for each display tag defined in the Discoverer Viewer cascading stylesheet (blaf.css).

Note: For more information about the location of configuration files, see Section A.2, "List of Discoverer file locations".

If you update the display tags in blaf.css, you can see changes reflected immediately in blaf.htm. You can use blaf.htm to find out which browser look-and-feel tags you need to change.

In the example below, the tag names in brackets or in the Tables section (e.g. OraHeader) are the display tags that you change in blaf.css.

Figure 10-7 Discoverer Viewer sample HTML file (blaf.htm)

Text description of the illustration testcard.gif

10.9 How to change the default Discoverer Viewer look and feel

You change the default Discoverer Viewer look and feel when you want to provide a customized Discoverer Viewer look and feel to end users. For example, you might want to change the background UI color or UI fonts.

To change the default Discoverer Viewer look and feel:

1. Using a text editor or XML editor, open the blaf.css file (for more information about the location of configuration files, see Section A.2, "List of Discoverer file locations").

   You can update any of the tag values in the blaf.css file.

2. Update the values in the blaf.css file as required.

   For example, to change the paragraph style from black to blue, change the .OraBody{background-color:#000000} tag to .OraBody{background-color:#0000FF}

   Tip: Use the blaf.htm file to find out which tags to change in blaf.css (for more information, see "About the sample browser look-and-feel file (blaf.htm)".

3. Save the blaf.css file.

   Tip: Use the blaf.htm file to preview changes that you make in the blaf.css file (for more information, see "About the sample browser look-and-feel file (blaf.htm)".

4. Run Discoverer Viewer and open a workbook.

Hint: If you have an existing Discoverer Viewer session running, refresh the browser to update Discoverer Viewer with changes that you have made.

The look and feel changes that you made will be applied.

Notes:

• In Japanese installations, blaf.css is called blafjp.css.

10.10 How to change the default Discoverer Viewer logo

You change the default Discoverer Viewer logo when you want to replace it with a logo or graphic of your choice. For example, you might want to change the logo displayed by Discoverer Viewer.

To change the default Discoverer Viewer logo:

1. Using a text editor or XML editor, open the ui_config.xml file (for more information about the location of configuration files, see Section A.2, "List of Discoverer file locations").

2. Locate the logo tag in the configuration\appearance section of the ui_config.xml file.

   Figure 10-8 A ui_config.xml file showing the presentation templates area expanded

   
   
   Text description of the illustration logofile.gif

3. Update the logo tag attributes as required.

   To insert a logo, insert the URL of the graphic into the src attribute value field. For example, to replace the default Oracle logo with a logo stored in <ORACLE_HOME>/j2ee/OC4J_BI_Forms/applications/discoverer/web/common/xsl/my_logo.gif, the URL of the logo file can be either be 'common/xsl/my_logo.gif' (i.e. using a relative path), or 'http://www.server.com:777/discoverer/common/xsl/clock.gif' (i.e. an absolute path).

4. Save the ui_config.xml file.

5. Run Discoverer Viewer and open a workbook.

Note: If you have an existing Discoverer Viewer session running, refresh the browser to update Discoverer Viewer with changes that you have made.

The logo or graphic that you specified will appear in Discoverer Viewer.

10.11 How to remove Discoverer Viewer user interface options

If you want to deploy a basic Discoverer Viewer interface without particular user interface (UI) options (e.g. Rerun Query or Presentation Options), you might change which options are displayed. For example, you may want to remove the Presentation Options link so that end users cannot change the Discoverer Viewer UI options displayed.

To remove Discoverer Viewer options:

1. Using a text editor or XML editor, open the ui_config.xml file (for more information about the location of configuration files, see Section A.2, "List of Discoverer file locations").

2. Locate the configuration\appearance section of the ui_config.xml file.

   
   
   Text description of the illustration cust_11.gif

3. Update the configuration\appearance tag attributes as required.

   For example:

   • to hide the Rerun Query link, change the value of the display_rerun_query_link attribute to 'false'.

   • to hide the Presentation Options link, change the value of the display_rerun_presentation_options_link attribute to 'false'.

4. Save the ui_config.xml file.

5. Run Discoverer Viewer and open a workbook.

Note: If you have an existing Discoverer Viewer session running, refresh the browser to update Discoverer Viewer with changes that you have made.

The logo or graphic that you specified will appear in Discoverer Viewer.

Note: Discoverer Viewer end users can also remove Discoverer UI components on a per-session basis using presentation options (for more information, see Section 10.6, "About presentation options").

10.12 How to create a presentation template

You create a presentation template when you want to enable end users to configure the Discoverer Viewer user interface themselves using pre-defined presentation options. For more information about presentation options and presentation templates, see "About presentation options" and "About presentation templates".

The easiest way to create a presentation template is to cut and paste the Corporate Look template that is included in the ui_config.xml file, then edit the copy to suit your needs.

To create a presentation template:

1. Using a text editor or XML editor, open the ui_config.xml file (for more information about the location of configuration files, see Section A.2, "List of Discoverer file locations").

2. Locate the Corporate Look presentation template in the configuration section of the ui_config.xml file.

   Figure 10-9 A ui_config.xml file showing the presentation templates area expanded

   
   
   Text description of the illustration cust_8.gif

3. Select the Corporate Look presentation template.

4. Cut and paste the Corporate Look presentation template into the ui_config.xml file, immediately after the original Corporate Look presentation template.

   You should now have two presentation templates, both called Corporate Look.

   Note: If you are using a simple text editor, copy all of the text between the tags <look name="Corporate Look"> and the first </look> tag that follows. For example:

   <look name="Corporate Look">
   <!-- Logo-->
   <component name="log" state="false"/>
   etc.
   .
   .
   </look>
   

5. In the second copied version of Corporate Look, change the name value to your preferred template name (note that the name you specify will be visible to users). For example, change <look name="Corporate Look"> to <look name="Money Portal look">.

6. Change the various component values of the new presentation template to true or false as required. You can update all of the tags located beneath the new presentation template.

   For example:

   • to display the Discoverer Viewer logo, set the log value to true

   • to remove the New Connection button from the user interface, set the con value to false

   Note: To help you identify tags in the ui_config.xml file, each tag has a comment label that tells you which part of the Discoverer Viewer user interface the tag relates to.

7. Save the ui_config.xml file.

8. Re-start the Web server that runs Discoverer.

   Re-starting the Web server ensures that the latest version of the customization file is stored in the cache.

   Note: If the stylesheet_pool 'maximum' value is set to zero in your configuration.xml file, omit this step. When the 'maximum' value is set to zero, pages are not cached, which means that changes are applied immediately.

Discoverer Viewer is updated with the presentation options that you have selected.

Notes:

• Discoverer Viewer end users can now select the new presentation template as follows:
  1. Run Discoverer Viewer and open a workbook.

  2. Click Presentation Options to display the Presentation Options page.

     The available Presentation templates are displayed at the right hand side of the page below the Uncheck All option (see Figure 10-5, "Discoverer Viewer Presentation Options page").

  3. At the right hand side of the page, click the presentation template name of the look and feel that you want to use.

  4. Click Apply.

10.13 How to run Discoverer Viewer with Javascript disabled

In order to increase Web security, some organizations only run Discoverer Viewer in pure HTML mode with Javascript disabled. This means that Javascript code cannot be used to change the HTML being displayed, or interfere with data. For more information about the Javascript enhanced user interface, see Section 4.4, "How to stop standalone Oracle9iAS Discoverer components in Unix".

To run Discoverer Viewer with Javascript disabled:

1. Using a text editor or XML editor, open the ui_config.xml file (for more information about the location of configuration files, see Section A.2, "List of Discoverer file locations").

2. Locate the configuration.appearance.option.use_javascript_enhanced_ui tag.

   Figure 10-10 A ui_config.xml file showing the use_javascript_enhanced_ui tag

   
   
   Text description of the illustration cust_9.gif

3. Change the use_javascript_enhanced_ui tag value from 'true' to 'false'.

4. Save the ui_config.xml file.

5. Re-start the Web server that runs Discoverer.

   Re-starting the Web server ensures that the latest version of the customization file is stored in the cache.

   Note: If the stylesheet_pool 'maximum' value is set to zero in your configuration.xml file, omit this step. When the 'maximum' value is set to zero, pages are not cached, which means that changes are applied immediately.