3 Configuring the User Interface

This chapter describes the steps to modify the application user interface of Oracle Role Manager in a managed fashion.

This chapter includes the following sections:

Best Practices
Extracting Files from the Web Application Archive
Modifying Appearance and Style
Modifying the Search Component
Deploying UI Customizations

3.1 Best Practices

Changes to the Oracle Role Manager user interface are made by modifying files contained in the Web application archive file that is deployed on the application server. To support future upgrades and to simplify reverting to the original state of the application, the recommendation is as follows:

Archive a copy of the original Web application archive file (webui.ear or webui.war, depending on the application server) provided with the release.

Keeping a copy allows the opportunity to make comparisons and redeploy the application as its original state at any time.
Extract the entire contents of the Web application archive file, retaining all directory path information, and store them in a version control repository system.

Using a version control system enables you to carefully manage updates and additions to those files, but more importantly, helps you retain your customizations when upgrading to later versions of Oracle Role Manager.

Note:

All user interface customizations require modifying the content of the Web application archive file, rebundling it, and redeploying it on the application server. For most deployments, the application server must then be restarted for changes to be in effect.

For the purpose of clarity in this document, the location where you extracted the contents of the Web application archive file is referred to as ORMUI_HOME.

3.2 Extracting Files from the Web Application Archive

To extract files from Web application archive:

On the Oracle Role Manager host, navigate to the ORM_HOME/webui directory.
Go to the subdirectory named for the application server where Oracle Role Manager intended to be deployed (for example, weblogic/10.3).
In the source control location that you will store your customization, create a directory named webui.
Using a utility like WinZip or jar, extract the entire contents of the webui.war file (or for WebSphere, the webui.ear file) into the newly created webui directory.

Note:
This location is the one referred to in this document as ORMUI_HOME.

Once expanded, the subdirectories and files you should see in that location are:
```
images/
META-INF/
nlstree/
pages/
scripts/
styles/
WEB-INF/
signin.jsf
signin.xhtml
signout.xhtml
```
Navigate to WEB-INF/lib and create a directory named webui.
Using a utility like WinZip or jar, extract the entire contents of the webui.jar file into the newly created webui directory within WEB-INF/lib.

These files include the Resource.properties file that is used for setting properties and labels in the user interface.
Using the source control system, check in all these files so you can store the baseline of the application before any changes are made

3.3 Modifying Appearance and Style

The appearance and style of the Oracle Role Manager user interface is governed by style sheets and image files. The style sheet for the general areas of the application is the style.css file. This is where you can modify the "look and feel" of the application.

Before you decide on your modifications you might want to see the settings in this style sheet.

To view the style sheet:

Navigate to the ORMUI_HOME/styles directory.

You should see the style.css file, which is where customizations can be made.

Once you decide on your modifications, you can edit this file and then deploy your changes as described in Section 3.5.

The following sections include examples of some of the style modifications you can do.

3.3.1 Changing the Header Logo

If desired, y ou can replace the Oracle Role Manager logo with one of your own.

Note:

The logo you use should be within the range of 234 pixels in width and 40 pixels in height.

Example 3-1 Changing the Logo

This example replaces the standard logo with a custom logo.

Navigate to ORMUI_HOME/images.
Rename logo.gif to RoleManagerLogo.gif.
Copy the logo you want to use as the banner logo into ORMUI_HOME/images.
Rename your logo to logo.gif.

Depending on your logo, you may want to modify the header background and link colors as described in the subsequent section.

3.3.2 Changing the Header Background and Link Colors

If desired, you can modify the header background and link colors in the header to match your logo.

Example 3-2 Changing the Background and Link Colors

This example changes the background of the header area to white. It also changes the color of the link text so they display over the white background.

Navigate to ORMUI_HOME/styles.
Open the style.css file for editing.
Change the globalheader element to remove the header background graphic and change the background color as follows:
```
.globalheader {
   background-color: #ffffff;
   padding-top: 10px;
   padding-bottom: 10px;
   width: 100%;}
```

Change the globalhelp element to change the help links in the header to blue so they are visible on the white background as follows:

.globalhelp {
   font-size: 11px;
   font-family: Tahoma, Arial, sans-serif;
   color: #0033cc;
   vertical-align: top;
   text-align: right;   padding-top:5px;   padding-right:12px;}

Change the following elements to change the color to black to make the Sign Out link visible:

..globalhelp a{
   color: #000000;
   text-decoration: none;
   text-align: right;
   padding-left: 5px;
}

.globalhelp a:visited{
   color: #000000;
   text-decoration: none;
   text-align: right;
}

.globalhelp a:hover {
   color: #000000;
   text-decoration: underline;
   text-align: right;
}

Save and close the style.css file.

3.4 Modifying the Search Component

The number of search results per page in can be configured by modifying the value for the page.table.rowcount property.

Example 3-3 Changing the Number of Rows in the Search Results

This example changes the number of rows in the search results area from the default of 15 rows to 20 rows.

Navigate to ORMUI_HOME/WEB-INF/lib/webui.
Open the Resource.properties file for editing.
Search for the property named page.table.rowcount and replace the value with 20 for twenty rows in the search results.
Save and close the Resource.properties file.
Using a utility such as WinZip or jar, rebundle the entire contents of WEB-INF/lib/webui and name the file webui.jar to replace the previous webui.jar file in WEB-INF/lib.
Remove the webui directory created in ORMUI_HOME/WEB-INF/lib.
Deploy your changes as described in Section 3.5.

3.5 Deploying UI Customizations

This procedures assumes that Oracle Role Manager has been deployed previously following the i nstructions in the Oracle Role Manager Installation Guide.

To deploy UI customizations:

Navigate to the ORMUI_HOME directory chosen in Section 3.2.
Using a utility such as WinZip or jar, archive the entire content of the ORMUI_HOME and save it with the following name:
- For WebLogic: webui.war
- For JBoss: webui.war
- For WebSphere: webui.ear
For WebLogic, deploy and test the modified Web application as follows:
1. In a Web browser, log in to the WebLogic Server Console. For example:
```
http://appserverhost:7001/console
```
2. In the left pane, click Deployments, then click Install.
3. Navigate to the location of the new Web application archive file, select webui.war, then click Next.
4. Select Install this deployment as an application, then click Next.
5. In the Target field, select the Oracle Role Manager server, then click Next.
6. In the Name field, enter Oracle Role Manager Application.
7. In the Security list, select Custom Roles and Policies: Use only roles and policies that are defined in the Administration Console, then click Next.
8. Click Finish.
9. In a Web browser, navigate to the Oracle Role Manager Web application address. For example:
```
http://appserverhost:7001/webui
```
10. Log in as the Oracle Role Manager Administrator.
  
  You should be able to see your customizations to the UI.
For JBoss, deploy and test the modified Web application as follows:
1. Copy the new webui.war file to the JBoss server where Oracle Role Manager server is deployed. For example:
```
JBOSS_HOME/server/default/deploy
```
2. Start the JBoss server.
3. In a Web browser, navigate to the Oracle Role Manager Web UI. For example:
```
http://appserverhost:8080/webui
```
4. Log in as the Oracle Role Manager Administrator.
  
  You should be able to see your customizations to the UI.
For WebSphere, deploy and test the modified Web application as follows:
1. In a Web browser, log in to the WebSphere administrative console. For example:
```
http://appserverhost:9060/ibm/console
```
2. From Applications > Install New Application, choose Remote file system, then click Browse to navigate to the location of the new Web application archive file, then select webui.ear.
3. Click Next on the next two pages to accept the defaults.
4. Click Finish, then save your changes.
5. From Applications > Enterprise Applications > ORM Web UI, click Manage Modules.
6. Select webui.
7. In the Class loader order list, choose Classes loaded with application class loader first.
8. Click OK, then save your changes.
9. From Applications > Enterprise Applications, select ORM Web UI, then click Start.
  
  (This assumes you are administering WebSphere on the same server as the ORM Web UI is installed.)
10. In a Web browser, navigate to the Oracle Role Manager Web application address. For example:
```
http://appserverhost:9080/webui
```
11. Log in as the Oracle Role Manager Administrator.
  
  You should be able to see your customizations to the UI.