9 Customizing Portal Navigation

Customizing portal navigation allows you to change the look and feel of the entire portal browsing experience. Portal navigation includes links to available portal pages and resources, including My Pages, Communities, the Knowledge Directory and Administration. Navigation schemes can also include links to external resources.

A navigation scheme defines:

The location of the navigation pane on the portal page
The look and feel of the navigation pane, including layout, color scheme and the type of navigation links (i.e., pure HTML links, combobox menus or dropdown menus).

Portal administrators select the navigation scheme for each experience definition in the Experience Rules Manager. The scheme selected is implemented throughout the entire experience definition. For details on experience definitions, see Chapter 7, "Customizing Experience Definitions".

In Oracle WebCenter Interaction, there are three ways to customize portal navigation:

Built-in navigation options provide a wide range of possibilities. Many customizations can be implemented without writing any code. For information on the portal's built in navigation options, see Built-In Navigation Options .
Adaptive Tags allow you to build and customize navigation in portlets using only HTML and provided HTML tags representing navigation elements and data. You can even build your own HTML tags to create very advanced and highly customized navigations. For details on using adaptive tags, see Chapter 3, "Using Adaptive Page Layouts" and the Oracle WebCenter Interaction Web Service Development Guide.
Custom navigation schemes are an advanced customization that requires custom code. Custom navigation schemes are explained in Creating a Custom Navigation Scheme.

Built-In Navigation Options

Oracle WebCenter Interaction provides a wide range of possibilities for customizing navigation without writing code.

Navigation Pane Locations
Built-in Display Options

Navigation Pane Locations

There are seven possible locations for the navigation pane. For an introduction to the portal page, see Chapter 2, "Portal Page Layout".

Top Bar
Above Header
Below Header
Above Body
Below Body
Above Footer
Below Footer
Right
Left

The portal provides eight built-in Navigation Schemes:

Horizontal Dropdown Navigation (default) is implemented in the Above Header navigation pane using JavaScript-driven dynamic menus.
Horizontal Combobox Dropdown Navigation is implemented in the Above Header navigation pane using combobox menus.
Tabbed Section Left Vertical Navigation combines links in the Left navigation pane and tabs in the Above Header navigation pane.
Left Vertical Navigation displays HTML links in the Left navigation pane.
Low Bandwidth and Accessibility Navigation is similar to left vertical navigation but conforms to 508 accessibility standards.
Mandatory Links Only shows mandatory links if present (including Administration), but no Communities, MyPages, or directory links. This scheme is not intended for use in a deployed portal.
Portlet-Ready Navigationdisables all navigation panes and leaves the header and footer enabled. (The header should contain all navigation since there is no other way to navigate.) This option is intended for use with Adaptive Tags.
No Navigation shows no links at all except for Administration (users can log in and out). This scheme is not intended for use in a deployed portal.

The location of the navigation pane can be combined with a different look and feel to provide a completely unique portal experience.

Even if one of the standard navigation options does not meet your needs, always use one of the built-in schemes as a starting place for navigation design.

Built-in Display Options

Some portal page components can disabled or modified without creating a custom navigation scheme:

Header and Footer: The header and footer are configured in the experience definition editor. You can also choose to disable the header and footer.
Color Scheme: The color scheme for navigation schemes is configured in the experience definition editor. For details, see the portal online help. For details on creating custom color schemes, see Chapter 4, "Using Adaptive Styles (CSS Customization)". If you are not using Adaptive Page Layouts, see Chapter 5, "Customizing Portal Layout Using CSS - Legacy User Interface".
My Pages, Communities and Knowledge Directory: The links to portal areas displayed in a navigation scheme can be disabled for the associated experience definition, on the main page of the Experience Rules Manager. For details, see the portal online help.
Portlet Preference links: The icons displayed in each portlet that link to the associated User Preferences page can be removed using a setting in the portalconfig.xml file. For details, see Customizing Built-In Display Options (portalconfig.xml)below.
Navigation Pane layout: You can customize the spacing and width of the navigation panes by modifying the settings in the portalconfig.xml file. For details, see Customizing Built-In Display Options (portalconfig.xml)below.

You can also choose to disable the standard navigation panes and provide customized navigation in another component using portlets with adaptive tags. For details, see the Oracle WebCenter Interaction Web Service Development Guide.

Customizing Built-In Display Options (portalconfig.xml)

You can customize basic display options for any navigation scheme by modifying the settings in the portalconfig.xml file (PT_HOME\settings\portal) in the Navigation section. The settings in this file include toggling the Edit button in portlet banners and changing the spacing or width of the navigation panes. You can also add settings to this file for your custom navigation schemes.

Note: You must restart the portal after making changes to the portalconfig.xml file.

Some settings can be different for each navigation scheme. Navigation schemes are referenced by the NavID defined within the associated INavType class (for details on the INavType class, see the next section). Standard navigation schemes use negative numbers to avoid collisions with custom schemes. The NavIDs for the standard schemes are listed in the table below.

Navigation Scheme	NavID
Horizontal Dropdown (legacy)	-1
Horizontal Combobox Dropdown	-2
Tabbed Section Left Vertical	-3
Left Vertical	-4
Mandatory Links Only	-5
No Navigation	-6
Horizontal Dropdown JavaScript	-7
508 Navigation	-8
Portlet-Ready Navigation	-9

The Horizontal Dropdown JavaScript option (-7) is provided to support legacy 5.0 navigation and requires additional settings. For information, see Horizontal Dropdown Navigation Settings later in this section.

Edit Portlet Preferences Icon

By default, each portlet with an associated User Preferences page includes an icon that links to the preferences page for that portlet. To remove the Edit Portlets Preferences icon from all portlets on a portal page, use the intMyPortletPrefButtonInPortletHeader setting. If this value is set to 1, the icon is displayed; if it is 0, the icon is not shown.

Table Spacing

Table spacing refers to the space between the different navigation panes (not between portlets). The default table spacing provides a 10-pixel gap between panes. This setting can be different for each navigation scheme. To set the table spacing, use the intPlumtreeDPTableSpacing setting. You must append the NavID of the navigation scheme you are modifying. For example, the code below sets the cell spacing for the Tabbed Section Left Vertical scheme (-3) to 15 pixels.

<intPlumtreeDPTableSpacing-3 value="15" /> <!-- table spacing -->

Navigation Pane Width

The Left and Right navigation panes have a fixed width. If only one pane is specified, the width is 200 pixels. If both panes are specified, the width of each is 100 pixels. This layout works well for most applications. To override the default width settings, there are four separate settings that allow you to set different widths depending on whether or not both panes are specified: intPlumtreeDPLeftWidth and intPlumtreeDPRightWidth are used if both panes are specified; intPlumtreeDPLeftWidthAlone and intPlumtreeDPRightWidthAlone are used if only one pane is specified.

To change these values, uncomment the settings you want to change and enter the appropriate pixel values. As with table spacing, these settings are set separately for each navigation scheme. You must append the NavID of the navigation scheme you are modifying. The example below sets the column width for the Left Vertical scheme (-4).

<intPlumtreeDPLeftWidth-4 value="100" />
<!-- left view width when a right view is present -->
 <intPlumtreeDPRightWidth-4 value="100" /> 
<!\-- right view width when a left view is present -->
 <intPlumtreeDPLeftWidthAlone-4 value="200" /> 
<!-- left view width when there is no right view -->
 <intPlumtreeDPRightWidthAlone-4 value="200" /> 
<!-- right view width when there is no left view -->

Horizontal Dropdown Navigation Settings

The rest of the navigation settings in the portalconfig.xml file are specific to the Horizontal Dropdown Navigation Scheme. Standard navigation works dynamically and does not use these settings.

Note: These settings only apply to the Horizontal Dropdown Navigation Scheme (NavID -7).

The intISCDropDownMenuTruncationWidth setting limits the number of characters shown in a dropdown menu.

The intISCDropDownMenuWidth setting limits the pixel width of a dropdown menu.

The intHorizontalNavTabTruncationWidth setting limits the number of characters in the tabs used to access navigation menus.

The intHorizontalNavTabWidth setting limits the pixel width for the tabs used to access navigation menus.

Creating a Custom Navigation Scheme

If the built-in navigation schemes and display options listed in the previous section do not meet your needs, you can create a custom navigation scheme. The easiest way to customize navigation is to use Adaptive Layouts; for details, see Chapter 3, "Using Adaptive Page Layouts". For more advanced customizations, the Adaptive Navigation Framework allows you to create a new look and feel, disable portal components, and add functionality.

Top Bar, Header and Footer: The top bar (including the login and search functionality), the header, and/or the footer can be disabled using the IsFeatureEnabled method in the INavTypes interface.
JavaScript: You can use custom JavaScript in your Navigation Schemes through the JavaScriptIncludes method of theINavTypes interface.
Look and Feel: You can change the display of navigation components through the IView interface.

The Adaptive Navigation Framework is designed for interface-based development. To create a custom navigation scheme, you must implement two interfaces: HelloWorldNavType (INavTypes) and HelloWorldNavView (IView) (com.plumtree.portaluiinfrastructure.navtypes). The methods in these classes are detailed in the example that follows. (For more information, see the Pluggable Navigation API documentation. For links to all portal API documentation, see Appendix B, "Portal API Documentation".) This section also provides instructions on Generating Navigation Links.

Note: Never change existing source code. The best way to modify an existing navigation scheme is to extend it and override the methods that you want to change. This way you can reuse the original code for the parts of the scheme that will stay the same. To facilitate upgrades, write a new class that corresponds to the navigation scheme you want to modify, and make it available through Dynamic Discovery (explained in the next section). Dynamic Discovery handles multiple versions of the same navigation scheme by giving precedence to the last version loaded.

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.

Example: Hello World Navigation Scheme

The example customization below removes the My Pages and Communities tabs in the left navigation pane and replaces them with a "Hello World" string.

If you were creating a new navigation scheme, you would create your own custom project and custom navigation class with a unique ID (for example, a CustomNav project and a CustomNav class in com.yourcompany.navigation), and compile the new class into a new JAR/DLL file with an intuitive name (for example, CustomNav).

HelloWorldNavType (INavTypes)

The HelloWorldNavType class implements INavTypes and defines a new navigation scheme to be used by the portal by giving it a name, assigning an ID, and defining the View modules for the sections of the UI that display navigation. (All customizable classes follow the naming convention of ending with the name of the interface that they implement.)

The GetID() method provides a unique ID for the navigation scheme. This ID is used to order the list of navigation schemes available for experience definitions. The standard navigation schemes in the portal use negative numbers for NavIDs (-1 through -7) to avoid collisions with custom schemes. Be sure to pick a unique ID so that you do not cause conflicts with existing custom navigation schemes. The Hello World example uses 200. You can also use the base ID available from the NavTypeConstants class. Set the ID for your custom schemes equal to NavTypeConstants.NAV_TYPE_ID_BASE + N, where N is an integer greater than or equal to zero, as shown in the code below.

Java:
```
public int GetID() 
{ 
   return NavTypeConstants.NAV_TYPE_ID_BASE + 1; 
} 
```
C#:
```
public virtual int GetID() 
{ 
   return NavTypeConstants.NAV_TYPE_ID_BASE + 1; 
} 
```
The GetName() method returns the name for the navigation scheme. This name is displayed in the Experience Rules Manager on the Choose Navigation Scheme page. The _strLangID argument contains the two letter language code of the current language (i.e., en for English, jp for Japanese).

Java:
```
public String GetName(String _strLangID) 
{ 
   return "Hello World" ; 
} 
```
C#:
```
public virtual String GetName(String _strLangID) 
{ 
   return "Hello World"; 
} 
```
The GetScope() method returns the description for the navigation scheme. This description can be any kind of text, but it must be stored in a String variable. The _strLangID argument contains the two letter language code of the current language (i.e. en for English, jp for Japanese).

Java:
```
public String GetScope(String _strLangID) 
{ 
   return "Hello World Navigation" ; 
} 
```
C#:
```
public virtual String GetScope(String _strLangID) 
{ 
   return "Hello World Navigation"; 
} 
```
The GetNavAreaView() method defines the View for each section of the page, and returns the name of the View class that builds the navigation scheme (i.e., the name returned by View.GetName). In this example, the HelloWorldNavView (IView) is displayed to the left of the body, and nothing is displayed in the other sections.

Java:
```
public String GetNavAreaView(NavAreaEnum area)
{ 
   if (area.equals(NavAreaEnum.LEFTOFBODY)) 
   { 
     return HelloWorldNavView.STR_MVC_CLASS_NAME; 
   }
 
   return null; 
} 
```
C#:
```
public virtual String GetNavAreaView(NavAreaEnum area) 
{ 
   if (area.Equals(NavAreaEnum.LEFTOFBODY)) 
  { 
     return HelloWorldNavView.STR_MVC_CLASS_NAME; 
  } 
   return null; 
} 
```
You can also reuse Views from other navigation schemes in your custom scheme. For example, the code below reuses the Community Section navigation (below the header) from the Horizontal Dropdown navigation scheme.
```
... 
else if (area.equals(NavAreaEnum.BELOWBANNER)) 
{ 
return NavigationCommSectionDropDownView.STR_MVC_CLASS_NAME; 
} 
...
```
The IsFeatureEnabled() method returns a boolean to tell the portal whether or not a specific navigation feature is enabled. Using this method you can disable the Top Bar (search field and login buttons), header, or footer. In this example, all three features are enabled. This method is the only way to disable these components. If you try to turn off a header or footer in a navigation scheme by not assigning a portlet, the portal will show the default header or footer. Using the IsFeatureEnabled method, you can ensure that no header or footer is shown, even if one is assigned.

This method is called repeatedly for each component: TOPBAR, HEADER, and FOOTER. You must return True or False for each item.

Java:
```
public boolean IsFeatureEnabled(NavFeatureEnum feature)
{ 
   return true; 
} 
```
C#:
```
public virtual bool IsFeatureEnabled(NavFeatureEnum feature) 
{ 
   return true; 
} 
```
The JavaScriptIncludes() method allows you to include any custom JavaScript needed for menus or dropdowns. The method returns a collection of HTMLScript elements that either contain JavaScript or include .js files. To use JavaScript in menus or dropdowns, simply wrap the JavaScript in an HTMLScript element and return an HTMLScriptCollection that contains all the required HTMLScript elements for the navigation scheme. This example returns null because it does not use custom JavaScript.

Note: JavaScript that is specific to only one View can be included in the DisplayJavascript method of your View instead of in JavaScriptIncludes. Do not call DisplayJavascript methods within JavaScriptIncludes; these methods are called within PlumtreeDP.

Java:
```
public HTMLScriptCollection JavaScriptIncludes(AActivitySpace owner) 
{ 
   return null; 
} 
```
C#:
```
public virtual HTMLScriptCollection JavaScriptIncludes(AActivitySpace owner)
{ 
   return null; 
} 
```

HelloWorldNavView (IView)

To create a working navigation scheme, you must build a valid View module class that displays all the necessary portal sections (MyPages, Communities, Directories, and Mandatory Communities) and components (drop-downs or submenus). Because a navigation scheme View is used throughout an entire Experience Definition, it extends from the top level View class within the UI Architecture, the IView interface. The GetNavAreaView method in INavTypes tells the portal which View class to use for each section of the portal page. For more information on Views, see Chapter 13, "Using View Replacement".

As noted above, the HelloWorldNavView class example implements the IView interface and displays the HTML output for the navigation scheme.

Open the HelloWorldNavView file (.java or .cs) in the sampleplugnav project in the src/com/plumtree/sampleui/navigation directory. As with all MVC modules, this example creates a public variable at the top of the View class that sets the name of the class.
```
public static final String STR_MVC_CLASS_NAME = "HelloWorldNavView";
```
The Create() method is used to get a new instance of the View when it is needed. It is very important to update this method if you are copying a file; otherwise your custom class will return an instance of the original class, and your custom View will not appear in the portal.

Java:
```
public Object Create()
{ 
   return new HelloWorldNavView();
} 
```
C#:
```
public virtual Object Create()
{ 
   return new HelloWorldNavView(); 
} 
```
The GetName() method returns the name of the View, which is used to store and retrieve it in the portal and in the ActivitySpace. When overriding an existing View, this method must return the same value as the View to 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.

Java:

public void Init(IModelRO model, AActivitySpace parent) 
{ 
   m_model = (NavigationModel) model; 
   m_asOwner = parent; 
}

C#:

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

The DisplayJavascript() method is used to add JavaScript to the page. Since this example does not use JavaScript, the code below returns null.

Note: The DisplayJavaScript method is called for each View in your navigation scheme by PlumtreeDP and its JavaScript is displayed in the Head of page. If you use JavaScript that is common to more than one View in a navigation scheme, it should be included in the JavaScriptIncludes method of your NavType class instead of in DisplayJavaScript. You could get JavaScript errors if the same code is included more than once. (This example does not use JavaScript.) For details on JavaScript navigation, see . Using Advanced JavaScript Navigation Elements (JSPortalmenus)

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

The Display() method is the primary method in the View class and creates the HTML for display to the user. This example outputs a table containing the string HELLO WORLD by creating an HTMLElementCollection, adding a table to it, adding a row to it, adding a cell to the row, and printing the string in the cell.)

Java:

public HTMLElement Display() 
{ 
   HTMLElementCollection result = new HTMLElementCollection();
 
   HTMLTable myTable = new HTMLTable(); 
   result.AddInnerHTMLElement(myTable); 
   HTMLTableRow myRow = new HTMLTableRow(); 
   myTable.AddInnerHTMLElement(myRow); 
   HTMLTableCell myCell = new HTMLTableCell(); 
   myRow.AddInnerHTMLElement(myCell);
   myCell.AddInnerHTMLString( "HELLO WORLD" );
   return result; 
}

C#:

public virtual HTMLElement Display() 
{ 
  HTMLElementCollection result = new HTMLElementCollection();
 
  HTMLTable myTable = new HTMLTable(); 
  result.AddInnerHTMLElement(myTable);
  HTMLTableRow myRow = new HTMLTableRow(); 
  myTable.AddInnerHTMLElement(myRow);
  HTMLTableCell myCell = new HTMLTableCell(); 
  myRow.AddInnerHTMLElement(myCell); 
  myCell.AddInnerHTMLString("HELLO WORLD");
   return result; 
}

In working navigation schemes, the Display method only defines the overall layout and structure of the navigation scheme. Internal methods are used to build each section and process the data required to create each menu item. These Write*Section methods control how each menu and submenu item is built for the corresponding section of the navigation pane. This includes the text, ASURL, and icon required for each item. All Write*Section functions defined within the scope of a View class should use IPluggableNavModelRO to gather the correct enumerators for a given menu item, then use ICPLIstEntryIterator and CListURLMediator to process each individual item and create an HTMLElement to be displayed within the portal. For details, see the next section.

Generating Navigation Links

Navigation schemes or Views within the same scheme can display links in different ways. One View might use HTML anchors, while another could use a JavaScript array to populate DHTML menus. The Navigation Framework uses a set of classes called mediators to store and format navigation links. Mediator classes ensure consistency in both appearance and functionality. You can also include links to resources on remote servers; for details, see Creating Gatewayed URLs at the end of this section. (If you are adding navigation links to a portlet, use adaptive tags; for details, see the Oracle WebCenter Interaction Web Service Development Guide.)

URL Mediators

The NavigationModel is the source of data for all navigation Views. The ASCompoundList class is a linked list that provides links to the appropriate Views. Individual links are stored as ListEntry objects, a container with member variables for all possible elements of a link, including page ID, community ID, ActivitySpace, page name and other control parameters. The ASCompoundList is returned as an ICPListEntryIterator, an interface that allows you to iterate over list entries. Mediator classes are wrappers for ICPListEntryIterators that convert each link into the appropriate form. In addition, mediators allow you to set a maximum display string width before truncation, and control link images.

There are two types of mediators:

TemplateMediators use a template to represent a link. A template is a comma-separated String with the type of URL and its parameters. For example, "C,200,-201" where C stands for a Community link template, 200 for the community ID., and 201 for the page ID. The purpose of using a template is to reduce the size of the data sent to the client. The common use for this mediator is for ListView menus, in which the onclick event calls a function that constructs the full URL and then redirects the browser. Note: These classes require that the user's browser support JavaScript.
FullMediators generate a full href URL link instead of just a URL template. The resulting link is 508 and low-bandwidth compatible.

There are five URLMediator classes included in the Navigation Framework library:

CListURLFullMediator creates ASURLs with target URLs in href, display string and image (if assigned).
CListURLFullLinkMediator is an extension of CListURLFullMediator that generates HTMLAnchors using target URLs as the onclick action.
CListURLTemplateMediator takes values from ASCompoundList and returns URL templates. This mediator is used by Horizontal Dropdown Navigation.
CListURLTemplateLinkMediator is an extension of CListURLTemplateMediator that generates HTMLAnchors using URL templates as the onclick action.
CListURLMediator is not truly a mediator class, but delegates link generation requests to the appropriate link medator. If the user is accessing the 508 or low-bandwidth portal, the class delegates to CListURLFullMediator. Otherwise, it delegates to CListURLTemplateLinkMediator.

As noted above, all mediators implement the ICPListEntryIterator interface. To get the data from a mediator, simply iterate over the items in the list. The code snippet below retrieves the links available on a MyPage and uses CListURLMediator to create HTMLElements.

// ICPListEntryIterator contains a listing of all actions and links
// for the referenced navigation section for the current user.
// IPluggableNavModelRO Model provides access to all information about
// users navigation. (The m_model variable is defined higher in the
// inheritance structure to avoid allocating another object.)
// GetCategoryLinks retrieves the list of available actions and links
// The boolean parameter determines which links are returned 
ICPListEntryIterator iterActions = m_model.GetCategoryLinks(NavCategoryType.MYPAGE,true); 
if (SectionVisible(NavVisibility.VISIBILITY_MYPAGESACTIONS_SECTION)) 
// Before HTMLElements can be created, the ICPListEntryIterator must
// be transformed into a CListURLMediator
{ 
  //create a mediator based on the ICPListEntryIterator of URLs
  CListURLMediator mediator = new CListURLMediator(m_asOwner, iterActions);
  mediator.SetImageSize(25, 25);
  mediator.SetLabelMaxLength(30); 
  int i = 0; 
  // Take each entry from the Mediator, cast it to an
  // HTMLAnchor, and pass it to AddActionListRow
  while (mediator.Next()) 
  { 
    AddActionListRow(table,(HTMLAnchor)mediator.GetEntry(),((i == 0) ?
    GetActionCollapseURL(NavVisibility.VISIBILITY_MYPAGESACTIONS_SECTION): null));
    i++; 
    } 
}

You can add links to the set provided by IPluggableNavModelRO by casting the ICPListEntryIterator to an ASCompoundList, which provides methods to add links to the list. Refer to the API documentation for ASCompoundList for more detailed instructions. You can also add links to content hosted on a remote server to your navigation panes, as detailed in the next section.

Creating Gatewayed URLs

In some cases, you might want to include content hosted on a remote server in your navigation scheme. To include links to remote content, the content must be part of a remote portlet. For example, a bug-tracking portlet might include a link to a page that shows the total number of open bugs, and you want to include the same link in a custom navigation scheme. You cannot point to the page directly, since the remote server might not be available to the outside users; you must gateway the link to make it available to all users.

To generate the correct gateway URL, call the following method (and pass PT_CLASSIDS.PT_GADGET_ID as the iClassID argument).

portaluiinfrastructure.statichelpers.GatewayHelpers.ConstructPrefPageLink(AActivitySpace asOwner, int iPortletID, int iCommunityID, int iPageID, int iPrefType, int iClassID)

The iPrefType argument determines whether the page is displayed in a popup window or in the main browser window. To display the page in a popup, pass GatewayHelpers.POPUPFLAG. To display the page in the main browser window, pass GatewayHelpers.NOFLAGS. You must create a window for the popup. The result of this call is a string that you can use as a prefix to generate the gateway URL. For example, to generate a link to the "http://myserver/portlet134/page.asp" that is part of a portlet with ID 134, the call would look something like the following:

String strGWURL = GatewayHelpers.ConstructPrefPageLink(m_asOwner, 134, iCurrentCommunityID, iCurrentPageID, GatewayHelpers.NOFLAGS, PT_CLASSIDS.PT_GADGET_ID) + GatewayHelpers.CreateGatewayFriendlyURL(http://myserver/gadget134/page.asp);

In addition to the settings in the methods above, you can configure gateway pages to be hosted or non-hosted.

Non-hosted pages just show the content that the remote server sent back.
Hosted pages include the portal banner, footer and navigation links, so that the remote page looks like it came from the portal.

This configuration is defined by the portlet code that contains the link.

Once you have written the code for your navigation scheme, you must deploy it for use by the portal, as described in the next section

Using Advanced JavaScript Navigation Elements (JSPortalmenus)

To implement advanced JavaScript functionality in your navigation elements, you can use the JSPortalmenus framework. This framework provides native JavaScript objects to create menu tabs and dropdown menus. The framework uses common jscomponent functionality in jsutil, reducing the size of JavaScript files downloaded by the browser. The total download size of the JSPortalmenus JavaScript and CSS files is approximately 85 KB.

The major feature of the JSPortalmenus framework is that form elements do not burn through the dropdown menus in Internet Explorer browsers, a typical problem with most other dropdown menu frameworks. This behavior is not an issue in Netscape 7.x and Firefox browsers. The JSPortalmenus framework also supports older Netscape browsers, (4.x and 6.x) but burn-through of form elements does happen in these browsers.

The portal usesJSPortalmenusin main portal navigation and in portlet title bars.

To create a single tab with a dropdown menu, follow the steps below:

Include JavaScript files on the page. JSPortalmenus files must be included through the jsincluder component.
- On the server side, as in a navigation scheme, use ConfigHelper.GetJSIncluderJSComponentInclude with ConfigHelper.JSCOMPONENT_JSPORTALMENU as the component name.
- In a portlet, use the jsincluder adaptive tag: <pt:ui.include pt:name="jsportalmenus"/>

Both methods will generate JavaScript to include the JSPortalmenus. Manually adding the generated JavaScript is not supported since it might change in future releases.

Define an HTML Container element with an ID where the menu should be displayed. For example: <table><tr><td ID="menuCell1"></td></tr></table>
Create a menu object, add entries to the menu, add the menu to a menu tab object, and associate the HTML block ID with the menu tab object.
1. Create a menu object: var menu = new PTPMMenuContainer();
2. Add entries to the menu (container menuItems is an array):
```
for (var j = 0; j < somearray.length; j++)
{
var strTitle = ...;
var strImgSrc = ...;
var strImgWidth = ...;
var strURL = ...;
menu.menuItems[j] = new PTPMSimpleMenuItem();
menu.menuItems[j].text = strTitle;
menu.menuItems[j].image = new PTPMImage();
menu.menuItems[j].image.imgSrc = strImgSrc;
menu.menuItems[j].image.imgWidth = strImgWidth;
menu.menuItems[j].action = new PTPMJavaScriptAction();
menu.menuItems[j].action.js = 'window.location = "'+strURL+'"'; 
}
```
3. Set tab content (HTML is allowed): var buttonText = "My Menu";
4. Add the menu to a menu tab object (static call). Assign tab content and provide the ID of the HTML element where the tab HTML should be inserted.
  
  PTPMSelectMenu.init(menu, strDivID, buttonText);
  
  Note: This function should only be called after the HTML container has been rendered on the page.

Deploying a Custom Navigation Scheme

After you create a custom project, you must deploy it to the portal using Dynamic Discovery. For detailed information and instructions, see Chapter 18, "Deploying Custom Code Using Dynamic Discovery". For navigation schemes, only the Jar or DLL-Based Dynamic Discovery section is necessary. Always confirm that your code was deployed correctly, explained in Viewing Your Customizations in the Portal at the end of this section.

Example: Hello World Navigation Scheme

The example below deploys the Hello World sample code from the previous section. These instructions use Visual Studio in .NET and Ant scripts in Java to deploy your custom code.

First, add the library containing the new 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. For more detailed information, see Chapter 18, "Deploying Custom Code Using Dynamic Discovery".
Find the <AppLibFiles> tag and add an entry for your project. In the example below, the project is called "sampleplugnav".
```
<AppLibFiles>
  <libfile name="sampleplugnav"/>
</AppLibFiles>
```

You must also run a clean build in order to deploy the custom code. The process is different based on your portal platform; see the appropriate set of instructions below.

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 sampleplugnav.dll file from SOURCE_HOME\sampleplugnav\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 Customizations 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. In Logging Spy, you should see your sample navigation load up with ID 200.
This example navigation scheme cannot be applied to the administrator's portal view because administrators will not be able to successfully navigate the portal. Instead, you must create an experience definition that uses the new navigation scheme. Log in as the administrator and navigate to portal Administration.
Create a new Administrative folder (Create Object | Administrative Folder) and name it Navigation.
Open the Experience Rules Manager (Select Utility | Experience Rules Manager).
Create a new Experience Definition (Create Object | Experience Definition).
On the first page of the Experience Definition Editor, click Add Folder.
Select the Navigation folder created in step 4 and click OK.
In the left menu of the Experience Definition Editor, click Edit Navigation Options.
Select the Hello World navigation scheme and click Finish. When prompted for a name for the new Experience Definition, enter Hello World Pluggable Nav.
Return to portal Administration and open the Navigation folder created in step 4.
Create a new user (Create Object | User) in the Navigation folder and name the new user Navigator. Click Finish to save the user.
Log out of the portal and log in as the new Navigator user. You should see the new Hello World navigation scheme.

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 navigation scheme.

Technical Tips

If your custom navigation scheme does not function correctly, first check the following:

The GetID() method in INavTypes must return a unique ID for the navigation scheme. If you use the same ID as another navigation scheme, only one of the schemes will be available. The standard portal navigation schemes use negative numbers for NavIDs (-1 through -7) to avoid collisions with custom schemes.
The JavaScriptIncludes () method in INavTypes must return the JavaScript for all Views included in the navigation scheme. If it does not, the Views will not work correctly and might produce JavaScript errors.
The Create() method in a View must return a new instance of the custom class. If this is not done, 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.

If this does not solve the problem, debug your code using the instructions below.

Debugging

These instructions use the Hello World navigation scheme created on the previous pages as an example.

Java

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

Description of the illustration javadebug_nav.gif
In the Eclipse menu, click Run | Debug… and select the Tomcat application.
Choose the Classpath tab, select Add Projects, and add the sampleplugnav project.
Hit Debug (and Save to retain your changes).

In Logging Spy you should see the system load up.
Open a browser and navigate to your Java portal. Log in and you should hit the breakpoint.

Stop the Visual Studio debugger (and close your browser if it is still open) and open HelloWorldNavView.cs in Visual Studio.
Add a breakpoint as shown below:

Description of the illustration dotnetdebug_nav.gif
Start the Visual Studio debugger (F5 or Start | Debug).
Navigate back to your portal and log in; you should hit the breakpoint.