1. Administering Oracle Analytics Server
  2. Advanced Configuration Settings
  3. Configure and Manage Analyses and Dashboards
  4. Customize the User Interface

Customize the User Interface

The user interface is generated by using scripts and custom interfaces, and is therefore highly customizable.

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

Oracle Analytics is shipped with several styles. Saved themes are also available in style selectors.

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

What Are Skins, Styles, and Themes?

Skins, styles, and themes change the way an interface looks.

You can control the way that the user interface is displayed to users by creating skins, styles, and themes. The primary difference between skins and styles is that styles apply to only dashboard content, whereas skins apply to every other part of the user interface. For example, skins apply to components that are used in analyses. Themes can apply to the entire interface, dashboard content, or both, depending on how they are applied.

You specify the default skin and style 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 Modify User Interface Styles. You design and apply themes using the Manage Themes page, which is enabled in the instanceconfig.xml file. You can then provide access on the Manage Privileges page.

Skins and styles 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. Themes are organized using the Manage Themes page.

General Tips to Customize the User Interface

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

  • In Presentation Services, you customize the user interface elements and appearance by modifying skins, and styles, not with JavaScript, and you don't 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.

    Users with appropriate permissions can customize the entire interface and analyses output using themes. See Creating Custom Themes in Visualizing Data in Oracle Analytics Server.

  • You can adapt the deployment to a particular language. See Localize Oracle Analytics Server.

About Style Customizations

Oracle Analytics Server has various styles. If you're going to customize the look-and-feel of Oracle Analytics Server or Oracle Analytics Server Publisher, Oracle strongly recommends that you use the custom style provided in the bicustom-template.ear as your starting point.

See Modify User Interface Styles for additional information.

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

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

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

Modify User Interface Styles

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

Approach 1: Deploy 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 contains an example folder structure to help you get started.

Note:

This approach automatically deploys your custom skin to all nodes in your 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 doesn't 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 Customize 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.

    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>StyleExample</DefaultStyle>
        <DefaultSkin>StyleExample</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 StyleExample above with the word Alta.

      Note:

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

    3. Save your changes and close the file.

  6. Restart Presentation Services. See About Managing Processes.

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

Approach 1: Redeploy 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're changing component values, such as an image or font color in your customized files, you don't 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: Deploy 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 as soon as possible.

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

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

Administering 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 Customize 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.

    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>StyleExample</DefaultStyle>
    <DefaultSkin>StyleExample</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 StyleExample above with the word Alta.

      Note:

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

      If you're 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>Alta</DefaultStyle>
    <DefaultSkin>Alta</DefaultSkin>
    <SkinMappings>
       
    <skinMapping>
       <biadfSkinFamily>SkinNewExample</biadfSkinFamily>
          <biSkin>SkinNewExample</biSkin>
     </skinMapping>
     <skinMapping>
          <biadfSkinFamily>SkinFamilyExample_1</biadfSkinFamily>
          <biSkin>SkinFamilyExample_1</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: View 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. 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.

  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.

Customize 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_ExampleStyle, which is defined in the filemap.xml file. This means that if a file can't 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_example">
      <Hierarchy>s_alta/s_Custom</Hierarchy>
   </Styles
   <Skins Default="sk_example">
      <Hierarchy>sk_alta/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. .

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 isn't 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 Publisher. Changing the styles defined in the classes contained in this file widely impacts the system.

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 updates.

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.

Note:

When you customize a style in the graph.xml file, you must copy the updated file to:

ORACLE_HOME/bi/bifoundation/javahost/config/styles/<stylename>/graph.xml

For example, for styleexample graph customizations you copy the updated graph.xml file to:

ORACLE_HOME/bi/bifoundation/javahost/config/styles/styleexample/graph.xml

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're extending is applicable only for Presentation Services.

Example to Modify Master Branding Class

You can modify the CSS for a style 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 Customize the User Interface for additional information.

Modify the User Interface With Themes

To create your own themes, you must edit the instanceconfig.xml file to make themes available to the system.

  1. On the Presentation Server, open the instanceconfig.xml file for editing, located in BI_DOMAIN/config/fmwconfig/biconfig/OBIPS.
  2. Locate the ServerInstance section.
  3. Add the elements shown:
    <ServerInstance>...
	<UI>
		<EnableDynamicThemes>true</EnableDynamicThemes>
	</UI>
  4. Save your changes and close the file.
  5. Restart Presentation Services.