22 Customizing the Oracle BI Web User Interface

This chapter describes how to customize the appearance of the Oracle BI Presentation Services user interface in a Web browser.

This chapter contains the following sections:

22.1 Tips for Customizing the Web User Interface

As you plan to customize the web user interface, keep the following points in mind:

  • When customizing, you often copy files that are installed with Oracle Business Intelligence into a directory in which you can modify them. By modifying files in this directory, you prevent your modifications from being overwritten when the software is upgraded.

    For performance reasons, copy only those files that you plan to modify, due to the lookup process for files. Oracle BI EE first looks for files in the directories that have been specified for your modifications, then it looks in the directories in which it installed standard files.

  • In Oracle BI Presentation Services, customization of user interface elements and appearance is accomplished by modifying XML message files, and styles and skins, and not with JavaScript. You should not modify JavaScript files that are located in the ORACLE_HOME\bifoundation\web\app\res directory. This is because the objects and methods in these scripts might change, and because these files might be replaced when upgrading.

    (In a dashboard, users with the appropriate permissions can customize an individual dashboard section by adding HTML to it. This HTML can include JavaScript. For more information, see Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.)

  • You can adapt the Oracle BI EE deployment to a particular language. For information, see Chapter 16, "Localizing Oracle Business Intelligence".

22.2 What are Skins and Styles?

You can control the way that the interface for Oracle BI EE is displayed to users by creating skins and styles. The primary difference between skins and styles is that skins can be automatically assigned to a user at login time, while users can select styles at run time to control things such as table formatting, and so on. The default skins and styles are located in the application resources directory (ORACLE_HOME\bifoundation\web\app\res) in the sk_* and s_* directories.

A "skin" is assigned based on the value of the SKIN system session variable. The user can then alter certain elements, such as fonts, colors, various attributes of tables and graphs, and so on, by picking a "style" for analysis results (or a dashboard) when they are logged into Oracle BI EE. Skins consist of non-alterable elements, such as corporate logos or other graphics.

A "style" controls how dashboards and results are formatted for display, such as the color of text and links, the font and size of text, the borders in tables, the colors and attributes of graphs, and so on. Styles consist of alterable elements, often combined into style sheets.

While skins and styles are typically used to customize the look and feel of analyses and dashboards by providing logos, color schemes, fonts, table borders, and other elements, they can also be used to control the position and justification of various elements by including specialized style tags in the relevant style sheet (.css) file.

22.2.1 Using the SKIN Variable

The SKIN variable points to a directory that contains non-alterable elements. Such directories are located in the ORACLE_HOME\bifoundation\web\app\res directory and begin with "sk_". For example, if a directory were called sk_MyCompany, the SKIN variable would be set to MyCompany. Styles are organized into similar directories that contain the alterable elements. Style folders and style sheets are located in the resources directory in directories that begin with "s_". For example, if a directory were called s_MyCompanyStyle, then the style name would be My CompanyStyle.

Both skin and style directories can contain Cascading Style Sheets (files with a .css extension), images, and graph templates. You can create new styles and skins by creating new style and new skin directories.

Note:

Style and skin names cannot include underscores.

22.3 Modifying Oracle BI Presentation Services User Interface Styles

You can modify the Cascading Style Sheets (CSS) files and the images that are stored in the default installation directory to create a custom user interface. The default images and style sheets are located in the ORACLE_HOME\bifoundation\web\app\res directory. The relevant subdirectories are contained in this directory for the current Oracle Business Intelligence style.

Cascading style sheets provide control over any object within Oracle Business Intelligence. You can change images, backgrounds, font colors and sizes, table cell gridlines and cell padding, and so on. For more information about cascading style sheets, consult a resource such as the Microsoft Developer Network (MSDN).

This section contains the following topics:

22.3.1 Creating a New Dashboard Style

The easiest way to create a style is to copy the ORACLE_HOME\bifoundation\web\app\res\s_blafp and \sk_blafp directories and paste them into the ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\res directory. Copying to this directory rather than to the main installation directory prevents any customized CSS files and images from being overwritten during a software upgrade.

The b_mozilla directory contains the important files for making quick changes to the dashboards.

To create a style:

  1. Copy the s_blafp and sk_blafp subdirectories of the ORACLE_HOME\bifoundation\web\app\res directory.

  2. Paste them to the ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\res directory.

  3. Make and save your modifications.

  4. Restart the service for Oracle BI Presentation Services to display the style sheet name in the Dashboard Properties dialog.

22.3.2 Specifying Defaults for Styles and Skins

You can specify which style and skin to use when users choose the default style in the Dashboard Properties dialog, using the DefaultStyle and DefaultSkin elements in the instanceconfig.xml file.

You can specify which style folder to use in the ORACLE_HOME\bifoundation\web\app\res directory when users select the Default option from the Styles list in the Dashboard Properties dialog. If the style folder begins with the characters s_, such as s_TestStyle, then omit those characters when specifying the value for the DefaultStyle element.

To specify the skins folder that is paired with the style folder, use the DefaultSkin element. If the skins folder begins with the characters sk_, such as sk_TestSkin, then omit those characters from the value.

If users do not make a choice or if these entries are not present in the instanceconfig.xml file, then the styles and skins that are installed with Oracle BI EE are used. These styles and skins are located in the ORACLE_HOME\bifoundation\web\app\res directory. The default value for both elements is blafp.

Before you begin this procedure, ensure that you are familiar with the information in Section 3.4, "Using a Text Editor to Update Oracle Business Intelligence Configuration Settings".

To manually edit the settings that controls the default styles and skins:

  1. Open the instanceconfig.xml file for editing, as described in Section 3.6, "Where are Configuration Files Located?"

  2. Locate the section in which you must add the DefaultStyle and DefaultSkin elements.

  3. Include the elements and their ancestor elements as appropriate, as shown in the following example:

    <ServerInstance>
        <DefaultStyle>myStyle</DefaultStyle>
        <DefaultSkin>mySkin</DefaultSkin>
    </ServerInstance>
    
  4. Save your changes and close the file.

  5. Restart Presentation Services.

22.4 Customizing Language Selections and Other Components

You can customize various aspects of the user interface, including the following ones:

22.4.1 Customizing a Language Selection

The Oracle Business Intelligence sign-in page and the My Account dialog each include a language selection list, where users select the language in which they want to work. If a language that users want to select is not displayed in the list, then you can add it.

To add a language to the selection list on the sign-in page and the My Account dialog:

  1. Add the l_xx directory to the ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\msgdb\messages directory, where xx is the language extension for the language to add (for example, en for english-usa).

  2. Copy the languagenames.xml file in the ORACLE_HOME\bifoundation\web\msgdb\messages directory to the ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\msgdb\messages directory. (The languagenames.xml file contains the list of languages that are acceptable for the language selection lists.

  3. Use a text editor to open the languagenames.xml file in the ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\msgdb\messages directory.

  4. Ensure that the language to add is not listed in the file. If it is not listed, then make the following entry to add the language:

    <WebMessage name="kmsgLanguageName_xx">
    <TEXT>LanguageName</TEXT>
    </WebMessage>
    

    where xx is the language extension (for example, ar) and LanguageName is the name of the language (for example, Arabic).

For more information on languages and localization, see Chapter 16, "Localizing Oracle Business Intelligence".

22.4.2 Customizing the Appearance of the Sign-In Page

Users first enter the appropriate URL in a Web browser, then they see the sign-in page for Oracle Business Intelligence. Users must sign in to Oracle Business Intelligence with an appropriate user name and password to gain access to the various editors and components. When sign-in is successful, users generally see their default dashboard.

You can customize the sign-in page to suit the needs of your organization. You cannot control how users are actually authenticated. For information about authentication options, see Appendix C, "Managing Security for Dashboards and Analyses."

To customize the appearance of the sign-in page:

  1. Copy the logoncontrolmessages.xml file in the ORACLE_HOME\bifoundation\web\msgdb\messages directory to the ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\msgdb\messages directory.

  2. Edit the logoncontrolmessages.xml file as appropriate. Save your changes and close the file.

  3. Copy the files to modify from the ORACLE_HOME\bifoundation\web\msgdb\pages\common directory to the ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\msgdb\pages\common directory.

  4. Edit the files in the \pages\common directory as appropriate, keeping the following points in mind:

    • The files all end with the .html suffix. However, these are actually XML-based files. When editing the files, use an editor that supports XML and ensure that the resulting files are saved as valid XML.

    • The Not Logged On page (kmsgAuthenticateNotLoggedOn), used for session timeout, is displayed only when users are not logged on and attempt to access a URL that does not support direct logon. For example, suppose a user accesses Oracle BI Answers and clicks the Log Off link. If the user clicks the browser's Back button and then clicks the My Account link, then the user receives the Not Logged On page.

  5. Save your changes and close the file.

For general information about customizing the user interfaces, see Section 22.5, "Customizing the User Interface Using XML Message Files".

22.4.3 Customizing Non-Dashboard Components

Non-dashboard components include the Analysis editor, the agent editor, and the Oracle BI Presentation Services Administration page. The CSS files for these components are stored in the sk_ directory within the main installation directory (ORACLE_HOME\bifoundation\web\app\analyticsRes). The b_mozilla_4 directory contains the relevant CSS files that correspond to these components.

Use the same logic that is described in Section 22.3, "Modifying Oracle BI Presentation Services User Interface Styles" to make modifications to the non-dashboard components of the user interface.

The non-dashboard components are controlled globally. Users cannot toggle between multiple user interfaces for the non-dashboard components.

22.5 Customizing the User Interface Using XML Message Files

This section explains how to customize text elements in message files to manage the default appearance and behavior of the Oracle BI Presentation Services user interface using XML strings.

Note:

The intent of this section is to allow organizations that have XML expertise to perform additional customization. If you do not have this expertise, then enlist the assistance of a third party to help you with customization.

This section contains the following topics:

Note:

Other topics in this guide describe additional customizations that you can perform by customizing text elements in message files, such as Section 19.7, "Specifying View Defaults for Analyses and Dashboards."

22.5.1 User Interface XML Message Files

You can customize many of the text elements that are displayed in the Analysis editor, the agents editor, and on dashboard pages. Examples of text elements include the content of text strings, the text for prompts such as the names of links and buttons, and the text of error and informational messages that are displayed to users as the result of their work.

These text elements are contained in external message files that are installed with Oracle Business Intelligence. The message files are in XML format. Language-specific messages are located in the ORACLE_HOME\bifoundation\web\msgdb\l_xx\messages directory, where xx is the language identifier of the selected locale (for example, for english-usa, the identifier is en). Language-independent messages are located in the ORACLE_HOME\bifoundation\web\msgdb\messages directory.

You should not edit the message files directly because any changes would not be retained when you install newer versions or service releases. For more information, see Section 22.5.3, "Customizing XML Messages."

22.5.2 Structure of XML Message Files

The name of a particular message file indicates the kind of content that it holds. For example, messages in the logonmessages.xml file hold message content that relates to the act of signing in and out of the application. Within each XML file, the WebMessage name= elements define the names of the messages. These elements are called message identifiers.

A particular message might also reference the content of another message by using a MessageRef element. For example, the following message in the logonmessages.xml file references the value of another message:

<WebMessage name="kmsgAuthenticateNotLoggedOnToLogOnClickHere">
 <HTML>
  You are not currently logged in to the
  <MessageRef name="kmsgProductServer" />

The entry <MessageRef name="kmsgProductServer" /> in the previous message indicates that the name of the server is taken from the value of the kmsgProductServer message identifier. This message is located in the productmessages.xml file, and its value is Oracle BI Server:

<WebMessage name="kmsgProductServer" CRC="nnnnnnnnnnnnnnnnnnnn">
 <TEXT>Oracle BI Server</TEXT>

Some messages, such as those that contain copyright information and product names, are protected and cannot be changed. The productmessages.xml file contains text preceding the WebMessage elements that indicates that the associated names cannot be changed.

22.5.3 Customizing XML Messages

This section explains how to change the content of unprotected messages and provides several examples. The intent is to show you how to alter the text of messages, and not to teach you XML.

To customize messages:

  1. Create message identifiers with similar names and customize their text.

  2. Create a custom messages directory named customMessages.

    Note:

    Organizations that have Oracle Business Intelligence applications might have a file present in this directory. This file enables Oracle Business Intelligence support for Oracle Business Intelligence applications, and should not be modified, moved, or deleted.
  3. Place the messages in one or more XML files in the customMessages directory, and then place the customMessages directory in this location:

    ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\msgdb\l_xx

    where xx is the language identifier of the selected locale (for example, for english-usa, the identifier is en).

    If you are not concerned with multiple languages, then place the directory in the l_en directory. Messages default to l_en if a language-specific version is not found. You must create the l_xx directory in the ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\msgdb directory.

  4. Restart Oracle BI Presentation Services.

You can create multiple XML files in the customMessages directory, or you can create a single XML file that holds customized messages, for example, custommessages.xml. This is because the application accesses the customMessages directory and reads every file that has an XML extension, regardless of the file's name. If you create many customized messages, then you might prefer to organize them into separate files.

Note:

If you intend to support multiple languages, then place control messages (which are messages that are not translated) into one file named customcontrolmessages.xml. Place messages that are translated into another file named, for example, customuimessages.xml. This places localized versions of the customuimessages.xml file in each language directory as appropriate, such as ORACLE_HOME\bifoundation\web\msgdb\l_de\customMessages, ORACLE_HOME\bifoundation\web\msgdb\l_fr\customMessages, and so on.

Links are a special case. Modifications made to link text are displayed as expected in dashboards and the agents editor. To make these same modifications be displayed in the Analysis editor, you must modify the kuiAnswersMainBar message.

To edit a custom message file:

  1. Make a backup of the original file in a separate directory.

  2. Make a development copy in a different directory.

  3. Edit the development version of the file in a text or XML editor.

  4. Replace the original file in the customMessages directory with the newly edited file.

  5. Test the new file.

  6. (Optional) Delete the backup and development copies.

22.5.4 Resolution of XML Message Name Elements

During initialization, WebMessage name default text is replaced with text from equivalently named elements in any customized XML file, based on the following precedence order, from highest to lowest:

  • XML in ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\msgdb\l_xx\customMessages directory, which are language-specific directories.

  • XML in ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\msgdb\l_en\customMessages directory, for language-specific user sign-ins if WebMessage name elements reside here, but are not in language-specific files.

  • XML in ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\msgdb\customMessages directory.

  • XML in ORACLE_HOME\bifoundation\web\msgdb\l_xx\messages directory.

  • XML in ORACLE_HOME\bifoundation\web\msgdb\messages directory.

As an example, when Oracle BI Presentation Services starts, it first reads the messages in the ORACLE_HOME\bifoundation\web\msgdb\l_xx\messages directory, and then reads the messages in the ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\msgdb\l_xx\customMessages directory. It replaces the default text for those messages with the customized text. If you attempt to alter the text of a protected message, then a message is displayed in its place that indicates that you attempted this.

22.5.5 Sample XML Template

The following is a sample template for a custommessages.xml file in the ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\msgdb\l_xx\customMessages directory. An example custommessages.xml file follows the template.

Every message begins with a <WebMessage name=> tag and ends with a </WebMessage> tag. The message text that you can customize is contained with the TEXT elements or HTML element. To suppress the display, delete the text between the start and end tags.

    <?xml version="1.0" encoding="utf-8"?>
    <WebMessageTables>
         <WebMessageTable system="Custom Messages">
         <!-- The name of a message must match the name of the message you are overriding. -->
         <WebMessage name="kmsgExampleOverrideMessage">
         <!-- A message can have TEXT and HTML versions of it. It is not necessary to have both. (TEXT is automatically converted to HTML when necessary). -->
         <TEXT>Example message.</TEXT> <!-- Format used in a text only output -->
         <HTML><b>Example message with bold HTML tags.</b></HTML> <!-- Format used in an HTML output -->
    </WebMessage>
</WebMessageTable>
</WebMessageTables>

To create a sample template:

  1. Replicate the sample template in a text editor.

  2. Name the file custommessages.xml (or any name you choose that ends with .xml).

  3. Place the file in the customMessages directory that you created in the appropriate ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\msgdb\l_xx directory.

22.5.6 Sample custommessages.xml File

The following example shows four customized messages placed in the custommessages.xml file.

    <?xml version="1.0" encoding="utf-8"?>
    <WebMessageTables>
   <WebMessageTable system="Custom Messages">
    <!-- First message -->
         <WebMessage name="kmsgAuthenticateRemembermyIDandpassword">
         <TEXT>Remember my sign-in name and password.</TEXT>
    </WebMessage>
    <!-- Second message -->
         <WebMessage name="kkmsgPrivilegeDisplayerAccountUnknown">
         <TEXT>Unknown Account (<Param insert="1"/>). Call the Help Desk at extension 9999 to set up a new account.</TEXT>
    </WebMessage>
    <!-- Third message --
         <WebMessage name="kmsgWelcomeFrameCreateNewRequest">
         <HTML>Create a <b>new analysis</b> by clicking on a Subject Area below. After creating the analysis, click the <b>Done</b> button at the bottom of the page.</HTML>
    </WebMessage>
    <!-- Fourth message -->
         <WebMessage name="kmsgUIAdmin">
         <HTML></HTML>
    </WebMessage>
</WebMessageTable>
</WebMessageTables>
  • The message identifier of the first message being customized is "kmsgAuthenticateRemembermyIDandpassword". The default text for this message is located in the file logonmessages.xml in the ORACLE_HOME\bifoundation\web\msgdb\l_xx\messages directory.

  • The message identifier of the second message being customized is "kmsgPrivilegeDisplayerAccountUnknown". The default text for this message is located in the file viewmessages.xml in the ORACLE_HOME\bifoundation\web\msgdb\l_xx\messages directory. This message contains a variable,

    ( <Param insert="1"/> ).
    

    Note:

    If you are customizing a message that contains a variable, then do not alter the variable. In the UNIX environment, be careful to preserve the case of the message name being customized.
  • The message identifier for the third message being customized is "kmsgWelcomeFrameCreateNewRequest". The default text for this message is located in the file searchsysmessages.xml in the ORACLE_HOME\bifoundation\web\msgdb\l_xx\messages directory. This message is in HTML format and uses an HTML tag ( <b> ) to display text in bold letters.

  • The message identifier for the fourth message being customized is "kmsgUIADMIN". The default text for this message is located in the file uimessages.xml in the ORACLE_HOME\bifoundation\web\msgdb\l_xx\messages directory. This message is in HTML format. This message identifier displays the Administration link at the top of each dashboard page or tab in the Analysis editor or agent editor. Deleting the Administration text between the <HTML> and </HTML> tags suppresses the display of the link.