13 Using View Replacement

The architecture of the portal UI is based on the Model, View and Control (MVC) design pattern. Well known among UI developers, MVC enables you to separate the code that handles business logic from the code that controls presentation and event handling. Each page in the portal is made up of a combination of at least one Model and View, and can include one or more Controls.

A Model class stores the data for a page or page section. A single page might use one or more Model classes, depending on how much of the page data can be shared by other types of pages. A Model defines how data is accessed and set for a given page. Models encapsulate calls to the portal server API and also store UI-specific data.
A View class contains HTMLElements and HTMLConstructs that describe how the data from the Model should be displayed to the user. In the Oracle WebCenter Interaction UI design, a DisplayPage object aggregates one or more View objects to encapsulate all the programmatic information needed to render a particular page. Some Views are common throughout the portal and some are specific to certain pages. For example, the banner that makes up the majority of the portal is a common View that defines the color scheme and the location of the search section. In contrast, the View used to create and modify data within a User Profile is specific to the User Profile function and is seen only on that page.
A Control is an action or set of actions that are executed when a specific event is triggered. Multiple Controls can be defined within a page, each with its own functional specification. For example, one Control might produce a popup window that allows the user to browse for a specific object and places the selection within the View, and another could save the new data to the Model.

You can customize the display of portal components by creating a custom version of the associated View class(es). The Oracle WebCenter Interaction UI Framework allows you to implement your customizations without modifying the portal code. This approach is safer, more efficient, and facilitates future upgrades.

Note: In most cases, you should modify only the View class of an Activity Space. Modifying Model and Control modules is supported, but consistency problems could occur if you do not test all related modules carefully.

This chapter provides instructions on how to create and deploy a custom View, and includes sample code that shows how to create a new view for the portal login page. The Hello World Login Page example illustrates how you can replace sections of portal code with your own customized code. As long as you maintain the contract dictated by Oracle WebCenter Interaction interfaces, your code will plug in seamlessly.

Identifying the Activity Space

In order to change the HTML displayed in the portal, you must locate where the HTML is generated in the portal code. Portal code is grouped into Activity Spaces, which contain multiple Views that generate the actual HTML. Therefore, you must first identify the Activity Space responsible for the page you want to modify; then you can find the View that creates the HTML you are interested in, and replace that View with your custom View.

There are several ways to find the code for the component you want to customize. It is usually easiest to find the name of an Activity Space by looking at the associated page URL or Logging Spy, and then browsing the source code to find that Activity Space.

There are two ways to find the name of an Activity Space:

Open a page in the portal that includes the component. The URL to the page should contain a query string argument that specifies the name of the Activity Space. Look in the query string for space= or in_hi_space=. The value after the equals sign should be the STR_MVC_CLASS_NAME of the Activity Space. (Note: This approach will not work if you navigated to the page via a form post, as the URL will not show the query string arguments.)
Turn on Logging Spy with Info and Action tracing enabled. Open a page in the portal that includes the component. You will see several messages in Logging Spy regarding the current Activity Space and Display Page (e.g., "current space is Login", "current control is DefaultLoginControl", and "Displaying page Login"). These messages can help you determine which Activity Space and/or Display Page is generating the HTML you want to customize. The first message ("current space") contains the name of the current Activity Space. The Display Page, noted in the "Displaying page" message, groups together different Views into a single HTML page.

Once you have found the name of the Activity Space, search for it in the portal UI packages (com.plumtree.uiinfrastructure, com.plumtree.portaluiinfrastructure, and com.plumtree.portalpages) and determine which View(s) you want to modify.

com.plumtree.portalpages: Most Views will be located in this package, which contains the UI code for the majority of the portal.
com.plumtree.uiinfrastructure: This package contains generic framework components that are used to build the UI.
com.plumtree.portaluiinfrastructure: This package contains portal-specific framework components.

The portalpages and portaluiinfrastructure packages are divided into admin, browsing, and common sections. The admin section is for the Administrative Site (Editors, etc...) and the browsing section contains end-user facing pages (MyPages, Directory, etc...). The common section contains code that is used for both admin and browsing.

Example: Hello World Login Page

For example, you might locate the View that creates the HTML for the portal login page by following the steps below.

Open the portal in your browser and click the "Login" link.
Look at the URL in your browser. Right after the question mark, it should say "space=Login" (the ordering of query string arguments is not guaranteed). This tells you that the Login HTML is generated by the Login Activity Space. In Internet Explorer, if the window you are viewing does not have the Address bar, you can often hit Ctrl-N and open the page in a new browser window that will have the Address bar.
Open up your IDE and view the portal source code.
The Login page is a page in the portal, so it should be in the portalpages package. The Login page is viewed by end-users, not just administrators, so it is most likely in the browsing package, although parts of it might be in the common package.
Browse to com.plumtree.portalpages.browsing.login and look for a file named LoginAS. "AS" stands for Activity Space. There is also a file named LoginView; that is the file you will modify.

You can also search the UI source code using your IDE or Windows Explorer to find the correct files. You can search for either the Activity Space name or a unique string in the HTML source. To find a unique string in the HTML source, open a page in the portal that includes the component. View the HTML source for the page and find a unique (non-generated) tag in the section of the HTML that includes the UI component you want to customize. Search for the tag in the portal UI packages.

Creating a Custom View

When you modify a piece of the UI, never change existing source code. It is a best practice to start with the original source, making modifications as necessary. The UI source code is shipped with the product. (For links to all portal API documentation, see Appendix B, "Portal API Documentation".)

The best way to modify an existing View is to extend it and override the methods that you want to change. This way you can avoid class cast exceptions if any code references the original class name.

To create a custom View, follow the steps below. For a simplified example, see the Example: Hello World Login Page sample code that follows.

Create your own custom project and custom View class (e.g., a CustomLogin project and a CustomLoginView class in com.yourcompany.login).
Edit the new class in your custom project. Make sure to follow the Requirements and Best Practices below:
- When replacing a pre-existing View with a custom View (as opposed to creating a brand new View), the STR_MVC_CLASS_NAME returned by the GetName() method must not be modified; this ensures that the portal will replace the original View with your custom View. To find the STR_MVC_CLASS_NAME, look in the View class' GetName() method (the constant also appears at the top of the file).
- If you are modifying only one component of the Activity Space, make sure to import the original Activity Space package to guarantee that the other modules will be available.
- The Create() method must return a new instance of the custom class. Otherwise, when the portal attempts to instantiate a new instance of the custom View using the Create() method, it will not work. A common problem is cutting and pasting code from an existing View and then forgetting to update this method. Your customization will be loaded by the portal, but the original View will still be displayed.
Compile the new class into a new JAR/DLL file with an intuitive name.

IMPORTANT: In most cases, you should modify only the View class of an Activity Space. Modifying Model and Control components is supported, but consistency problems could occur if you do not test all related modules carefully. When you upgrade to a new release of the portal, it is very important to check all customized files to see if the original versions have been modified in the upgrade. This way you can migrate any new features and bug fixes into your modified version. (For information on modifying the functionality of the login page, see Chapter 12, "Using PEIs".)

Example: Hello World Login Page

For example, the sample customization below starts with existing code and adds a line ("Hello World") to be displayed on the login page.

The name of the file is important; it ends with "View." All presentation layer classes that implement the IView interface follow this naming convention. The IView interface defines a few simple methods: Init, Display, and DisplayJavaScript. Use your IDE to navigate to the interface definition or view the API documentation for the IView class.

Make a copy of the LoginView file at com.plumtree.portalpages.browsing.login and make the modifications detailed below.
The Create() method gets a new instance of the View when it is needed. It is very important to update this method when copying a file; otherwise your custom class will return an instance of the original class, and your customization will not appear in the portal.

Java:
```
public Object Create() 
{ 
   return new HelloWorldView(); 
} 
```
C#:
```
public virtual Object Create() 
{ 
     return new HelloWorldView(); 
} 
```
The GetName() method returns the name of the View, which is used to store and retrieve the View class in the portal and in the ActivitySpace. When overriding an existing View, this method must return the same value as the View that will be overridden.

Java:
```
public String GetName()
{ 
   return STR_MVC_CLASS_NAME; 
} 
```
C#:
```
public virtual String GetName() 
{ 
   return STR_MVC_CLASS_NAME; 
} 
```

The Init() method provides the View with access to the model and parent Activity Space. Copy this code directly from the LoginView class.

Java:

public void Init(IModelRO model, AActivitySpace parent) 
{ 
   m_asmLoginModelRO = (ILoginModelRO) model; 
   m_asOwner    = parent; 
}

C#:

public virtual void Init(IModelRO model, AActivitySpace parent) 
{ 
  m_asmLoginModelRO = (ILoginModelRO) model; 
  m_asOwner = parent; 
}

The DisplayJavascript() method is used to add javascript to the page. This example does not use javascript for this example, so it returns null.

Java:
```
public HTMLScript DisplayJavascript() 
{ 
   return null; 
} 
```
C#:
```
public virtual HTMLScript DisplayJavascript() 
{ 
   return null; 
} 
```

The Display() method creates the HTML for display to the user. Copy the code for this method from the LoginView class (com.plumtree.portalpages.browsing.login). This code outputs a table containing the HTML for the login form.

This example adds a row to the table that prints the string "HELLO WORLD." (It adds a cell to the row and prints the string in the cell.) As shown in the code snippet below, the code is added after calling the MakeLoginForm() helper method. This helper method creates the HTML form that contains the username and password text boxes. (This code is in a separate class so it can be reused in the Login Portlet.)

Java:

LoginHTML.MakeLoginForm(myForm, sFormName, m_asOwner.GetName(), 
   m_asOwner.GetSpaceID(), LoginControl.STR_MVC_CLASS_NAME, 
   m_asOwner, b508, "" , myCreateLink, bShowAuthsourceDropdown, bAllowAuthSourceDropdownDisplay);  
/* 
* Add this custom code to print HELLO WORLD after the Login Form directions. 
*/ 
HTMLTableRow myRow = new HTMLTableRow(); 
myTable.AddInnerHTMLElement(myRow);
HTMLTableCell myCell = new HTMLTableCell();
myRow.AddInnerHTMLElement(myCell);
myCell.AddInnerHTMLEncodedString( "HELLO WORLD" );
/*
* End of HELLO WORLD code
*/

C#:

LoginHTML.MakeLoginForm(myForm, sFormName, m_asOwner.GetName(), m_asOwner.GetSpaceID(), 
  LoginControl.STR_MVC_CLASS_NAME, m_asOwner, b508, "", myCreateLink, bShowAuthsourceDropdown, bAllowAuthSourceDropdownDisplay);
/* 
* Add this custom code to print HELLO WORLD after the Login Form directions. 
*/ 
HTMLTableRow myRow = new HTMLTableRow();
myTable.AddInnerHTMLElement(myRow);
HTMLTableCell myCell = new HTMLTableCell(); 
myRow.AddInnerHTMLElement(myCell);
myCell.AddInnerHTMLEncodedString("HELLO WORLD");
/* 
* End of HELLO WORLD code 
*/

Once you have written the code for your new View, you must deploy it for use by the portal, described in the next section

Deploying a Custom View

After you create a custom View as explained in the previous section, you must deploy it to the portal using Dynamic Discovery. For detailed information and instructions, see Chapter 18, "Deploying Custom Code Using Dynamic Discovery". To deploy a View replacement, use Jar or DLL-Based Dynamic Discovery.

The example below deploys the Hello World Login Page sample code from the previous section. Once you have deployed you code, confirm that your code was deployed correctly as explained in Viewing Your Customization in the Portal at the bottom of this section.

Example: Hello World Login Page

These instructions use Visual Studio in .NET and Ant scripts in Java to deploy your custom code.

First, add the library containing the new HelloWorldView class to the CustomActivitySpaces.xml file so it can be deployed by Dynamic Discovery.

Navigate to PT_HOME\settings\portal and open CustomActivitySpaces.xml in a text editor (you might have to make the file writable). Note: Do not modify the ActivitySpaces.xml file. The CustomActivitySpaces.xml file is functionally identical to the ActivitySpaces.xml file and allows you to enumerate custom components without modifying the code used by standard portal components.
Find the <AppLibFiles> tag and add an entry for your project:

<AppLibFiles> <libfile name="sampleview"/> </AppLibFiles>

You must also run a clean build in order to deploy the custom code.

Java:

Open a command prompt and change the directory to the \ptwebui directory where you installed the portal source code
Run a clean build using the following Ant script: ant build
Generate a new WAR file for the application server using the following Ant script: ant install

Note: This target deletes and rebuilds all jar files associated with all the UI source projects (as well as the custom projects in the ptwebui folder).

C#:

Build the project in Visual Studio.
Visual Studio should copy the sampleview.dll file from SOURCE_HOME\sampleview\dotnet\prod\bin to PORTAL_HOME\webapp\portal\bin for you. If there are problems with Dynamic Discovery on startup, you might need to do this step manually. This is necessary to allow Dynamic Discovery to find the new library.

Viewing Your Customization in the Portal

Once you have deployed your code, view the changes in the portal to confirm that they were loaded correctly. Use Logging Spy to catch any obvious errors.

Open Logging Spy. For details, see the Administrator Guide for Oracle WebCenter Interaction.
Start the portal.
Open a new browser window and navigate to the portal. You should see your customization on the login page (the "HELLO WORLD" string appears after the login instructions).

The next step is to debug your code, covered in the next section.

Debugging and Troubleshooting

This section provides technical tips for common problems and instructions on how to debug your new class.

Technical Tips

If your custom View is not displayed correctly, first check the following items:

The GetName() method in your custom class must return the same STR_MVC_CLASS_NAME used by the class that will be overridden; this ensures that the portal will replace the original View with your custom View. To find the STR_MVC_CLASS_NAME, look in the View class' GetName() method (the constant also appears at the top of the file).
The Create() method must return a new instance of the custom class. Otherwise, your customization will be loaded by the portal, but the original View will still be displayed.
If you modified only one component of the Activity Space, make sure you imported the original Activity Space package to provide access to the other modules.

If none of these tips solve the problem, debug your code using the instructions below.

Debugging

These instructions use the Hello World Login Page class created in the previous section as an example.

Java

In Eclipse, stop the Tomcat debugging session and open SampleView.java.
Add a breakpoint as shown below:

Description of the illustration javadebug_view.gif
In the Eclipse menu, click Run | Debug… and select the Tomcat application.
Choose the Classpath tab, select Add Projects, and add the sampleview project.
Hit Debug (and Save to retain your changes).
Open a browser and navigate to your portal. You should hit the breakpoint, since you are debugging the login page.

Stop the Visual Studio debugger (and close your browser if it is still open) and open HelloWorldView.cs in Visual Studio.
Add a breakpoint as shown below:
Description of the illustration dotnetdebug_view.gif
Start the Visual Studio debugger (F5 or Start | Debug).
Navigate to your portal and log in again. You should hit this breakpoint, since you are debugging the login page.