Customizing the Oracle BI Web User Interface

The user interface in Oracle BI EE is generated by using scripts and is therefore highly customizable.

The look-and-feel is controlled by skins and styles. Skins define the user interface chrome (visible graphic features) outside the home and dashboard area.

Oracle BI EE is shipped with several styles, such as Skyros, blafp (browser look and feel), and FusionFX (fusion applications).

The following sections provide information about how to customize the web user interface:

What Are Skins and Styles?

Skins and styles change the way an interface looks.

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 styles only apply to dashboard content, whereas skins apply to every other part of the user interface. For example, within Oracle BI EE, skins apply to components that are used in analyses and scorecarding.

You specify the default style and skin in the instanceconfig.xml file. The content designer can then alter certain elements to control how dashboards 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. See Modifying the User Interface Styles for Presentation Services for additional information.

Styles and skins are organized into folders that contain Cascading Style Sheets (CSS) and images. 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 file. See About Style Customizations for additional information.

General Tips for Customizing the Web User Interface

Some points to keep in mind as you plan to customize the web user interface.

  • In Oracle BI Presentation Services, you customize the user interface elements and appearance by modifying styles and skins, not with JavaScript, and you do not modify JavaScript files because the objects and methods in 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. See Working with HTML Markup in User's Guide for Oracle Business Intelligence Enterprise Edition.

  • You can adapt the Oracle BI EE deployment to a particular language. See Localizing Oracle Business Intelligence

    .

About Style Customizations

Oracle BI EE ships with various styles, such as blaf (browser look and feel), FusionFX (fusion applications), and Skyros. If you are going to customize the look-and-feel of Oracle BI EE or Oracle BI Publisher, Oracle strongly recommends that you use the custom style provided in the bicustom-template.ear as your starting point.

This custom style is a copy of the Skyros style. See Modifying the User Interface Styles for Presentation Services for additional information.

Most of the common Skyros styles and image files, including the style sheet (master.css), are contained in a master directory. The topic Customizing Your Style describes this directory and its structure in detail.

Within the style sheet, each element (or class) that is available for update is documented by comments.

Other style sheets are also contained within the Skyros style and skin folders. You are not likely to need to update these files unless you are creating an advanced custom skin that provides styles for each detail of the user interface.

Modifying the User Interface Styles for Presentation Services

When creating your own styles and skins for Presentation Services, you must create CSS, graph.xml, and image files, and then make them available to Oracle BI EE. You can use two approaches to make these files available:

Approach 1: Deploying the "bicustom.ear" File for the First Time?

Enterprise Archive (EAR) files are archive (ZIP) files composed of a specific folder and file structure.

You can create an EAR file using any ZIP tool (for example, 7-zip) and then renaming the ZIP extension to EAR. Oracle provides the bicustom-template.ear file as a starting point.

The bicustom-template.ear file contains a bicustom.war file. Web Archive (WAR) files are also ZIP files composed of a specific folder and file structure. You must update the bicustom.war file within the bicustom-template.ear file to include your custom skin files. The bicustom.war file that is shipped with Oracle BI EE contains an example folder structure to help you get started.

Note:

This approach automatically deploys your custom skin to all nodes in your Oracle BI EE cluster.

  1. Copy ORACLE_HOME/bi/bifoundation/jee/bicustom-template.ear to BI_DOMAIN/bidata/components/OBIPS/bicustom.ear.

    Note:

    The patch or upgrade process may overwrite the bicustom-template.ear file, but it does not overwrite the bicustom.ear file.

  2. Update the bicustom.ear file.

    1. Extract the bicustom.war file from the bicustom.ear file.

    2. Extract the files from the bicustom.war file.

    3. Edit the files to create your custom style and save your changes. See Customizing Your Style

    4. Update the bicustom.war file with your changes.

    5. Update the bicustom.ear file with your new bicustom.war file.

  3. Deploy the bicustom.ear file.

    1. Log in to Oracle Weblogic Server Administration Console.

    2. Click Lock & Edit.

    3. Click Deployments in the Domain Structure region.

    4. Click Install in the Deployments table.

    5. Navigate to the folder containing the bicustom.ear file (by default, this file is located in BI_DOMAIN/bidata/components/OBIPS/).

    6. Select the bicustom.ear file.

    7. Click Next.

    8. Select Install this deployment as an application.

    9. Click Next.

    10. Select I will make the deployment accessible from the following location.

    11. Click Finish.

    12. Click Save.

    13. Click Activate Changes.

  4. Start the new application.

    1. Click Deployments in the Domain Structure region.

    2. Select the bicustom check box in the Deployments table.

    3. Click Start, and then select Servicing all requests.

  5. Update the instanceconfig.xml file to specify which style and skin to use as the default value of the Styles option in the Dashboard Properties dialog. For additional information about updating styles in a dashboard, see Changing the Properties of a Dashboard and its Pages in User's Guide for Oracle Business Intelligence Enterprise Edition.

    If these entries are not present in the instanceconfig.xml file, then fusionFX is the default style. Styles and skins are located in the ORACLE_HOME\bi\bifoundation\web\appv2\res directory.

    1. Open the instanceconfig.xml file for editing, located in:

      BI_DOMAIN/config/fmwconfig/biconfig/OBIPS

    2. Include the element and its ancestor elements as appropriate, as shown in the following example:

      <ServerInstance>
    <UI>
        <DefaultStyle>Skyros</DefaultStyle>
        <DefaultSkin>Skyros</DefaultSkin>
    </UI>
</ServerInstance>

      where DefaultStyle and DefaultSkin are the names of the custom style and skin properties, respectively.

      To use the Alta custom style and skin, replace the word Skyros above with the word Alta.

      Note:

      These names must match the names given to the folders containing the style and skin. Do not include underscores. For example: If your folder begins with the characters s_, such as s_Skyros, then omit s_.

    3. Save your changes and close the file.

  6. Restart Presentation Services. See About Managing Oracle Business Intelligence Processes.

To redeploy the bicustom.ear file, see Approach 1: Redeploying the "bicustom.ear" File.

Approach 1: Redeploying the "bicustom.ear" File

Enterprise Archive (EAR) files are archive (ZIP) files composed of a specific folder and file structure.

Use this task to update your custom skin

  1. Update the bicustom.ear file.

  2. Update the deployment.

    1. Log in to Oracle Weblogic Server Administration Console.

    2. Click Lock & Edit.

    3. Click Deployments in the Domain Structure region.

    4. Select the bicustom checkbox in the Deployments table.

    5. Click Update.

    6. Click Finish.

    7. Click Activate Changes.

    8. Click Release Configuration.

  3. Restart Presentation Services.

Note:

If you are changing component values, such as an image or font color in your customized files, you do not need to restart Presentation Services. Additionally, you do need to restart Presentation Services if you make a change to the default skin or style in the instanceconfig.xml file.

Approach 2: Deploying Using Shared Folders

Approach 2 is best suited to development or test environments where you want the changes that you make to the CSS and image files in your custom style and skin folders to be visible in Oracle BI EE as soon as possible.

This approach is also used when your customizations are outside the Presentation Services firewall.

In Oracle BI EE, static files are located in ORACLE_HOME\bi\bifoundation\web\appv2. Web servers have their own ways of exposing static directories that can be located anywhere within their file system, including a shared file system such as clustering. Refer to the documentation for your specific server on exposing static directories.

Note:

See the following documents for full information about how to configure Oracle WebLogic Server to work with web servers such as Apache HTTP Server, Microsoft Internet Information Server (Microsoft IIS), and Oracle HTTP Server:

Using Oracle WebLogic Server Proxy Plug-Ins 12.2.1

Administrator's Guide for Oracle HTTP Server

  1. Create your custom style.

    1. Extract the bicustom.war file from the bicustom-template.ear file.

    2. Extract the contents of the bicustom.war file to a location accessible to Oracle Weblogic Server (for example, c:\custom).

    3. Edit the files to create your custom style and save your changes. See Customizing Your Style for additional information.

  2. Deploy the custom folder.

    1. Log in to Oracle Weblogic Server Administration Console.

    2. Click Lock & Edit.

    3. Click Deployments in the Domain Structure region.

    4. Click Install in the Deployments table.

    5. Navigate to the folder containing your custom style (for example, c:\custom).

    6. Click Next.

    7. Select Install this deployment as an application.

    8. Click Next.

    9. Select bi_cluster as the deployment target.

    10. Click Next.

    11. Set the name to AnalyticsRes.

    12. Select I will make the deployment accessible from the following location.

    13. Click Next.

    14. Select Yes, take me to the deployment's configuration screen.

    15. Click Finish.

    16. Click the Configuration tab.

    17. Enter /analyticsRes in the Context Root box.

    18. Click Save.

    19. Click OK.

    20. Click Activate Changes.

    21. Click Release Configuration.

  3. Start the new application.

    1. Click Deployments in the Domain Structure region.

    2. Select the analyticsRes checkbox in the Deployments table.

    3. Click Start, and then select Servicing all requests.

  4. Update the instanceconfig.xml file to specify the path that points to your customization, which can then be accessed by Presentation Services.

    Presentation Services generates the user interface for the Analysis editor and dashboards, which visualize data from Oracle BI Server, the core server behind Oracle Business Intelligence.

    1. Open the instanceconfig.xml file for editing, located in:

      BI_DOMAIN/config/fmwconfig/biconfig/OBIPS

    2. Locate the ServerInstance section.

    3. Include the elements, as shown in the following example:

      <ServerInstance>
   <UI>
    <DefaultStyle>Skyros</DefaultStyle>
    <DefaultSkin>Skyros</DefaultSkin>
   </UI>
   <URL>
      <CustomerResourcePhysicalPath>c:\custom\res
         </CustomerResourcePhysicalPath>
      <CustomerResourceVirtualPath>/analyticsRes/res
      </CustomerResourceVirtualPath>
   </URL>
</ServerInstance>

      where DefaultStyle and DefaultSkin are the names of the custom style and skin properties, respectively.

      To use the Alta custom style and skin, replace the word Skyros above with the word Alta.

      Note:

      The CustomerResourceVirtualPath points to the location entered in the Context Root box.

      If you are embedding a Presentation Services' dashboard or report in an ADF application, you must include the SkinMappings element following the DefaultStyle and DefaultSkin elements, as shown in the following example:

      <ServerInstance>
   <UI>
    <DefaultStyle>Skyros</DefaultStyle>
    <DefaultSkin>Skyros</DefaultSkin>
    <SkinMappings>
       <skinMapping>
       <biadfSkinFamily>fusion</biadfSkinFamily>
          <biSkin>FusionFx</biSkin>
       </skinMapping>
    <skinMapping>
       <biadfSkinFamily>blafplus-rich</biadfSkinFamily>
          <biSkin>blafp</biSkin>
     </skinMapping>
     <skinMapping>
          <biadfSkinFamily>skyros</biadfSkinFamily>
          <biSkin>Skyros</biSkin>
      </skinMapping>
    </SkinMappings>
   </UI>
   <URL>
      <CustomerResourcePhysicalPath>c:\custom\res
         </CustomerResourcePhysicalPath>
      <CustomerResourceVirtualPath>/analyticsRes/res
         </CustomerResourceVirtualPath>
   </URL>
</ServerInstance>

    4. Save your changes and close the file.

    5. Restart Presentation Services.

Approach 2: Viewing Your Modifications to a Shared Folder

Once you have configured your shared folder, you can view the changes to the CSS files and images.

  1. Reload the metadata.

    1. In Oracle BI EE, click the Administration link in the global header.

    2. On the Administration tab, click the Reload Files and Metadata link.

  2. Clear the browser's cache. Note that this process is dependent on the browser being used.

  3. Click any link on the global header (for example, Home or Catalog) to see your changes.

Note:

If you add files, such as an image file, to your custom style folder, you must restart Presentation Services.

Customizing Your Style

To create your custom style, you must edit one or more files.

The bicustom.war folder structure from which the style directory is extracted, contains the following in the application resources (res) directory (./res/), which houses the relevant files:

  • ./res/filemap.xml

  • ./res/s_Custom/

  • ./res/s_Custom/master/

  • ./res/s_Custom/master/master.css

  • ./res/s_Custom/master/graph.xml

  • ./res/s_Custom/master/custom.css

  • ./res/s_Custom/master/styleproperties.res

  • ./res/s_Custom/master/*.png

  • ./res/s_Custom/master/*.gif

The style directory, prefixed by s_, contains the style sheet, image files, and a graph xml file.

All classes are located within the CSS or the graph.xml file.

The table below describes the content of the "res" folder structure.

Folder or File Name Description

filemap.xml2

The filemap.xml file enables you to specify that your style or skin extends another style or skin. By default, s_Custom1 extends s_Skyros, which is defined in the filemap.xml file. This means that if a file cannot be found as part of your custom style or skin, then Presentation Services knows where to look next for that file. The content within the filemap.xml file looks similar to the following:

<FileMap>
   <Styles Default="s_blafp">
      <Hierarchy>s_Skyros/s_Custom</Hierarchy>
   </Styles
   <Skins Default="sk_blafp">
      <Hierarchy>sk_Skyros/sk_Custom</Hierarchy
   </Skins>
</FileMap>

s_Custom

s_Custom is a folder containing the files that define a style named Custom. The prefix, s_, indicates that the folder contains a style. This name displays in the Dashboard Properties dialog, Styles option. For additional information about updating styles in a dashboard, see Changing the Properties of a Dashboard and its Pages in User's Guide for Oracle Business Intelligence Enterprise Edition.

If you want to change the default style manually by using the instanceconfig.xml file, the style name that you specify in the instanceconfig.xml file must match the style name specified as part of this folder name. You can name your style whatever you choose, but it must begin with s_. If you do change the name of the custom style, you must also update the filemap.xml file with the new style's name.

If the files and folders that you add to the new style folder share the same names as files and folders in the base style (as defined in the filemap.xml file), then these new files and folders are used instead of the files in the base style. Use the files and folders in the base style as a guide for creating your custom style folders.

You can define as many different styles as you like. Make a copy of the s_Custom folder in the same folder and name it by prefixing it with s_ (for example, s_Corporate). If you create additional custom styles, you must also add them to a style hierarchy in the filemap.xml file.

sk_Custom

sk_Custom1 is a folder that you create to customize the full skin and not just the style. You create sk_Custom as a sibling of the s_Custom folder. sk_Custom is not provided as part of the bicustom-template.ear file. The prefix, sk_, indicates that the folder contains a skin.

If you want to change the default skin manually by using the instanceconfig.xml file, the skin name that you specify in the instanceconfig.xml file must match the skin name specified as part of this folder name. You can name your skin whatever you choose, but it must begin with sk_. If you do change the name of the custom skin, you must also update the filemap.xml file with the skin's new name.

If the files and folders that you add to the new skin folder share the same names as files and folders in the base skin (as defined in the filemap.xml file), then these new files and folders are used instead of the files in the base skin. Use the files and folders in the base skin as a guide for creating your custom style folders.

You can define as many different skins as you like. Make a copy of the sk_Custom folder in the same folder and name it by prefixing it with sk_ (for example, sk_Corporate). If you create additional custom skins, you must also add them to a skin hierarchy in the filemap.xml file.

master

The master folder contains all of the files that you likely need to create a custom style.

master.css

The master.css file contains all the CSS classes that are used by the style and defines the majority of the CSS classes and styles that are used throughout Presentation Services and Oracle BI Publisher. Changing the styles defined in the classes contained in this file widely impacts Oracle BI EE.

Oracle does not recommend changing the CSS class selectors (CSS class names) in this file. Change the styles defined within each CSS class. The master.css file also contains comments to help you understand what classes apply and to which parts of the user interface they apply.

custom.css

The custom.css file is an empty (or blank) file that is imported by the master.css file. You can use the custom.css file to add your own CSS classes (for example, to apply styles to analyses) and override classes in the master.css file without changing the master.css file. Keeping your changes in the custom.css file, a separate file, enables you to take advantage of future improvements to the master.css file that are applied by patches and upgrades.

graph.xml

The graph.xml file enables you to define all the default styles that are applied to various graphs within analyses. The graph.xml file is documented with comments. These comments describe the valid values for each setting and provide a description of the elements for that style.

styleproperties.res

The styleproperties.res file provides advanced control over some of the elements of the user interface. For example, you can specify which version of the data loading animation to use when your dashboard is rendered. Data loading animations are used in the "status indicator" area of a web page when a page is loading data from the server. There are two different versions of the data loading animation: one animation uses dark foreground colors for use on light backgrounds and the other animation uses the reverse.

The styleproperties.res file is documented with comments. These comments provide a description of the elements.

.png and .gif (image files)

All required images and the most common images are located in the master directory. These images are primarily .png and .gif formats. You can replace these images with your own files, preferably with images of the same size.

  1. File names, such as s_Custom, are case-sensitive and in lowercase on Linux.

  2. Using the filemap.xml file to specify the style or skin that you are extending is applicable only for Presentation Services.

Example of Modifying the Skyros Master Branding Class

You can modify the CSS for Skyros to effect changes to any element contained within the CSS.

For example, if you want to change the background color of the master branding area from black to bright blue, perform the following steps:

  1. Open the master.css file.
  2. Scroll down and locate the class that you want to customize. In the sample code, modify the .masterBrandingArea class. Also note that the code contains inline comments to identify that code section. 
    .
.
.
.masterHeader
{
      font-weight: bold;
      color: #003d5b;
      text-align: left;
}
/* BRANDING AREA ========================================================= */
/* This class applies to the branding area shown at the top of most pages. */
{
.masterBrandingArea
{
      background-color: #000000;
      color: #ffffff;
      padding: 5px;
}
/* This class applies to the brand name text shown at the top of most pages. */
.masterBrandingAreaBrandName
{
      font-size: 17px;
      font-weight: bold;
.
.
.

    Note:

    To ensure that a custom.css setting is used in Dashboards, add the text !important just before the colon (;) in the custom.css file. This stops other css-files opened after custom.css from overwriting the value.

    For example, if you change the background-color on the masterBrandingArea class from black to a light grey and the text color from white to black. The branding area appears light grey for login, Home, Catalog, Analysis and logoff, but for Dashboards, the branding area is still black with white text. To retain the custom settings for Dashboards you add the word!important before the semi colon (;) as follows:

    .masterBrandingArea
{
  background-color: #ffffff !important; /* white background */
  color: #333333 !important; /* almost black text color */
}
  3. Change the HTML background-color code value from #000000 to #3300ff.
  4. Save the file.
  5. Reload the metadata and clear the browser's cache. See Customizing the Oracle BI Web User Interface for additional information.