10 Building a Navigation Model for Your Portal

This chapter describes how to create the navigation model for your portal. Navigation models define the content, structure, and metadata of your portal navigation.

This chapter includes the following sections:

For information about how to expose the navigation model in your portal, see Chapter 13, "Visualizing Your Portal Navigation."

10.1 Introduction to Navigation Models

Typically, portals provide information from various different sources. Information may be provided by pages, portlets, task flows, content repositories, and external pages. Users need a way to easily move through this information and quickly access the specific information that they need. You provide this access to information through your portal navigation.

The navigation model defines the content, structure, and metadata of the navigation. When you create the navigation model, you specify the items to include and the hierarchy of those items. Navigation models can include the following resources:

  • Pages (individual pages and page hierarchies)

  • Content (individual content items or the results of a content query)

  • Other navigation models

  • Portlets

  • Task flows

  • External applications

  • External links

For more information, see Section 10.3, "Adding Resources to a Navigation Model."

You can also add resources that are dynamically generated. These are:

  • Custom Resources

  • Components

  • Custom Folders

  • Custom Content

For more information, see Section 10.3.7, "How to Extend Navigation Model Data."

When you create a new WebCenter Portal Application, a navigation model is created for you (default-navigation-model.xml). You can build on this seeded navigation model or create your own. You might even want to create different navigation models for different user types.

Note:

If you create your own navigation model, rather than extend the seeded navigation model, we recommend that you set your navigation model as the default navigation model. For more information, see Section 10.4, "Selecting the Default Navigation Model."

After you have created your navigation model, you can expose it on any page template in your portal either through the built in navigation task flows, or through your own navigation UI. For more information, see Chapter 13, "Visualizing Your Portal Navigation."

10.2 Creating a Navigation Model

If the default navigation model provided out of the box does not meet your requirements, you can create your own navigation model.

To create a navigation model:

  1. In the Application Navigator, right-click the node where you want to create the navigation model (for example /oracle/webcenter/portalapp/navigations) and choose New.

  2. In the New Gallery, expand Web Tier, select Portal and then Navigation, and click OK.

  3. In the Create Navigation dialog (Figure 10-1), in the File Name field, enter a name for the XML file that represents the navigation, for example myNavigation.xml.

    Figure 10-1 The Create Navigation Dialog

    Description of Figure 10-1 follows
    Description of "Figure 10-1 The Create Navigation Dialog"

  4. In the Directory field, enter the full directory path of the location under which to create the file.

    Note:

    In a WebCenter Portal application, to expose the new navigation model in the runtime Resource Manager, you must create the navigation model under the Application_Root/Portal/public_html/oracle/webcenter/portalapp directory. By default WebCenter includes a separate navigations directory.
  5. Select Create as a Portal Resource to add the navigation model to the resources registry, allowing it to be managed at runtime through the Resources Manager.

    Note:

    This option is available only if the directory you entered is the Application_Root/Portal/public_html/oracle/webcenter/portalapp directory or one of its subdirectories.

    Tip:

    If you do not select this option now, you can add the navigation model to the resources registry later by right clicking it and choosing Create Portal Resource.
  6. Click OK.

    The new navigation model opens in Design view (Figure 10-2).

    Figure 10-2 A Navigation Model in Design View

    Description of Figure 10-2 follows
    Description of "Figure 10-2 A Navigation Model in Design View"

  7. In the Design view for the navigation model, select the new navigation model in the Navigation column and define general properties as required:

    • In the Navigation Filter field, enter the name of a Java class to use to filter out selected resources in the navigation model based on specific criteria. The Java class should implement the oracle.adf.rc.spi.plugin.catalog.CatalogDefinitionFilter interface.

      Resources are automatically filtered based on security. If a user does not have access to a particular resource, it is not displayed when the navigation model is rendered on a page.

      Note:

      You can also conditionally hide individual resources in the model by specifying an EL expression in the Visible field for the resource.
    • In the Visible field, specify whether the navigation model is available for use in the application. This field takes an EL value. The default is #{true}, which means the navigation model can be used by other users and is available in dropdown lists of navigation models.

    • Use the Navigation Attributes section to set display options for the navigation model as desired. The options available are the same as those for individual resources. For more details about the different display options, see Section 10.3.9, "How to Set Display Options for a Resource.".

  8. Save the navigation model definition file.

    Now that you have created the navigation, you can add resources to it. For more information, see Section 10.3, "Adding Resources to a Navigation Model."

10.3 Adding Resources to a Navigation Model

To define the content of your navigation model you can add resources to the default navigation model, default-navigation-model.xml. The default navigation model is created automatically when you create an application using the WebCenter Portal Application template.

You can also create your own custom navigation model and add resources to that. For more information, see Section 10.2, "Creating a Navigation Model."

You can add resources to a navigation model in two ways:

In the Design view for the navigation model you can also modify and remove existing resources.

This section includes the following subsections:

10.3.1 How to Drag and Drop a Resource onto a Navigation Model

You can add the following resources to a navigation model by dragging and dropping them onto the desired location in the Design view for navigation model:

  • Content—You can drag a content item from an Oracle Content Server connection in the Application Resources pane or Resource Palette onto a navigation model.

  • Pages—When you drag a page from the Application Navigator onto a navigation model, you are prompted to choose whether to add just the page itself or to add a page query that includes the page its subpages.

  • Portlets—You can drag a portlet from the Application Resources pane or Resource Palette onto a navigation model.

  • Task flows—You can drag a task flow from the Application Resources pane or from the Resource Palette onto a navigation model.

  • External applications—You can drag an external application from the Application Resources pane or Resource Palette onto a navigation model.

  • URLs—You can drag a URL connection from the Application Resources pane or Resource Palette onto a navigation model.

  • Navigation models—You can drag a navigation model from the Application Navigator and embed it in another navigation model.

10.3.2 How to Add a Content Item to a Navigation Model

In your navigation model, you can include links to individual content items within an existing content repository connection, or you can include a folder to provide access to all its contents.

You can also include a set of documents that match particular query criteria to a navigation model. For more information, see Section 10.3.3, "How to Add Content Based on the Results of a Query to a Navigation Model."

To add a content item:

Tip:

To add a content item to a navigation model you can also drag and drop it into the Design view for the navigation model.
  1. In the Application Navigator, right-click the navigation model to which you want to add the resource, and choose Open.

  2. In the Design view for the navigation model, in the Navigation column on the left side, select the node in the navigation model under which you want to add the resource.

  3. Click the Add new node icon and choose Content Item.

  4. The Id field is automatically populated with a generated ID. You can keep this ID, but you will probably want to change it to something slightly more descriptive. The ID must be unique within the navigation model.

    If the resource is at the top level of the navigation model, the ID must not be wc_navtitle or wcnav_externalId; these IDs are reserved.

    Tip:

    If the ID is not unique, or you enter any invalid characters in the ID, the border of the field becomes red.

    Figure 10-4 Adding a Content Item to a Navigation Model

    Description of Figure 10-4 follows
    Description of "Figure 10-4 Adding a Content Item to a Navigation Model"

  5. In the URL field, enter or browse for the URL to access the resource. If you enter the URL manually, use the following format:

    content://Content_Connection_Id/Document_Id

    Note:

    If the following is true, you must make sure that an appropriate connection is added to the application (in the Application Resources pane) to ensure that the resource is available at runtime:
    • You manually entered the URL

    • The connection exists in the Resource Palette

  6. Select Render URL in Page Template, to render the resource in the current page, using the specified page template.

    Select Redirect to URL, to overwrite the current page with the resource when it is selected in the navigation.

  7. In the Visible field, specify whether the resource is displayed in the navigation. The default value is the EL expression #{true}, which means the resource is displayed to all users at all times. Enter false or #{false} to hide the resource from all users at all times, or enter an EL expression to specify the conditions under which the resource is displayed. If the field is empty, the value defaults to true.

    Note:

    Resources are automatically filtered based on security. If a user does not have access to a particular resource, it is not displayed when the navigation model is rendered on the page.
  8. In the URL Attributes section, specify any desired display options for the resource. For more information, see Section 10.3.9, "How to Set Display Options for a Resource."

  9. If you want to use a Content Presenter display template to display the content item, in the URL Parameters section, click the Add icon, and choose templateView.

  10. In the Value field for the templateView parameter, enter the display template view ID to use for rendering the content item, for example:

    oracle.webcenter.content.templates.default.detail
    

    Note:

    If you display a wiki page in a WebCenter Portal application using a Content Presenter display template, by default any links within that wiki page are displayed in the Document Viewer. If you want to display wiki page links using Content Presenter, you must edit the adf-config.xml file. For more information, see Section 31.3.5, "Displaying Wiki Page Links Within Content Presenter."
  11. Add further parameters, as required. For information about additional Content Presenter parameters, see Section 30.7.1, "Content Presenter Task Flow Parameters and Out-of-the-Box Display Templates."

  12. Save the navigation model definition file.

10.3.3 How to Add Content Based on the Results of a Query to a Navigation Model

You can add a content query to a navigation model to include all documents that match specific search criteria.

Note:

To add a single file, or all the files within a particular folder, to a navigation model, see Section 10.3.4, "How to Add a Page, Portlet, Task Flow, External Application, or Web Page to a Navigation Model."

To add a content query:

  1. In the Application Navigator, right-click the navigation model to which you want to add the resource, and choose Open.

  2. In the Design view for the navigation model, in the Navigation column on the left side, select the node in the navigation model under which you want to add the resource.

  3. Click the Add new node icon and choose Content Query.

  4. The Id field is automatically populated with a generated ID. You can keep this ID, but you will probably want to change it to something slightly more descriptive. The ID must be unique within the navigation model.

    If the resource is at the top level of the navigation model, the ID must not be wc_navtitle or wcnav_externalId; these IDs are reserved.

    Tip:

    If the ID is not unique, or you enter any invalid characters in the ID, the border of the field becomes red.

    Figure 10-5 Adding a Content Query to a Navigation Model

    Description of Figure 10-5 follows
    Description of "Figure 10-5 Adding a Content Query to a Navigation Model"

  5. In the Repository field, enter or browse for the content repository whose content you want to search.

    Note:

    If the following is true, you must make sure that the appropriate connection is added to the application (in the Application Resources pane) to ensure that the resource is available at runtime:
    • You manually entered the repository name

    • The connection exists in the Resource Palette

  6. In the Query field, enter the query criteria to identify the content to include in the navigation model, for example:

    select * from cmis:document WHERE cmis:name LIKE 'Foo%'
    

    For more information about how to format the query and for more examples, see Oracle Fusion Middleware Content Management REST Service Developer's Guide.

  7. In the Visible field, specify whether the resource is displayed in the navigation. The default value is the EL expression #{true}, which means the resource is displayed to all users at all times. Enter false or #{false} to hide the resource from all users at all times, or enter an EL expression to specify the conditions under which the resource is displayed. If the field is empty, the value defaults to true.

    Note:

    Resources are automatically filtered based on security. If a user does not have access to a particular resource, it is not displayed in the navigation when it is rendered on the page.
  8. Select Insert Folder Contents to display the results of the query directly in the navigation, rather than displaying them under a folder.

  9. In the Content Query Attributes section, specify any desired display options for the resource. For more information, see Section 10.3.9, "How to Set Display Options for a Resource."

  10. If you want to use a Content Presenter display template to display the results of the content query, in the URL Parameters section, click the Add icon, and choose templateView.

  11. In the Value field for the templateView parameter, enter the display template view ID to use for rendering the results of the content query, for example:

    oracle.webcenter.content.templates.default.list.simple
    

    Note:

    If you display a wiki page using a Content Presenter display template, by default any links within that wiki page are displayed in the Document Viewer. If you want to display wiki page links using Content Presenter, you must edit the adf-config.xml file. For more information, see Section 31.3.5, "Displaying Wiki Page Links Within Content Presenter."
  12. Add further parameters, as required. For information about additional Content Presenter parameters, see Section 30.7.1, "Content Presenter Task Flow Parameters and Out-of-the-Box Display Templates."

    Note:

    If you include links to the same portlet twice in a navigation model, the first link specifying parameter values and the second not, any parameters set for the first link are retained and also used for the second. To ensure that parameters are not used for the second link, you must explicitly set the parameter values to null.
  13. Save the navigation model definition file.

10.3.4 How to Add a Page, Portlet, Task Flow, External Application, or Web Page to a Navigation Model

You can add links to the following types of resources to a navigation model:

  • External Link: Hypertext link to any external web page.

    Note:

    If you use the External Link option to include a mailto: link in your navigation, your navigation UI must explicitly handle this type of link. For information, see Section 11.2.3, "What You Should Know About Creating Page Templates for WebCenter Portal Applications."
  • External Application: Link to any registered external application.

  • Page: Link to any JSPX page in the application.

    This option enables you to add a link to a single page to the navigation model. For information about how to include an entire page hierarchy, see Section 10.3.5, "How to Add a Page Hierarchy to a Navigation Model."

  • Task Flow: Link to any task flow in the application, or to a WebCenter task flow (available in the Resource Palette).

    Note:

    If you provide navigation directly to a task flow in this way, users cannot customize the task flow. If you want users to be able to customize the task flow, add it to a page and add that page to the navigation model.
  • Portlet: Link to a portlet in any registered portlet producer.

    Note:

    If you provide navigation directly to a portlet in this way, users cannot customize the portlet. If you want users to be able to customize the portlet, add it to a page and add that page to the navigation model.
  • Other: Link to a custom resource. For more information, see Section 10.3.7.1, "How to Add a Link to a Custom Resource."

To add a link to a page, portlet, task flow, external application, or web page:

Tip:

To add a portlet, task flow, external application, or web page to a navigation model you can also drag and drop it into the Design view for the navigation model.

To add a link to a single page, drag the page into the Design view for the navigation model and choose Page Link from the popup menu.

  1. In the Application Navigator, right-click the navigation model to which you want to add the resource, and choose Open.

  2. In the Design view for the navigation model, in the Navigation column on the left side, select the node in the navigation model under which you want to add the resource.

  3. Click the Add new node icon and choose Link.

  4. The Id field is automatically populated with a generated ID. You can keep this ID, but you will probably want to change it to something slightly more descriptive. The ID must be unique within the navigation model.

    If the resource is at the top level of the navigation model, the ID must not be wc_navtitle or wcnav_externalId; these IDs are reserved.

    Tip:

    If the ID is not unique, or you enter any invalid characters in the ID, the border of the field becomes red.

    Figure 10-6 Adding a Link to a Navigation Model

    Description of Figure 10-6 follows
    Description of "Figure 10-6 Adding a Link to a Navigation Model"

  5. From the Type dropdown list, select the type of resource that you want to add to the navigation model: External Link, External Application, Page, Taskflow, Portlet.

  6. The Factory Class field is automatically populated with the appropriate factory class for the resource type and cannot be edited.

    Note:

    If you are adding a resource of type Other, the Factory Class field is editable and you must enter the factory class of the resource. For more information, see Section 10.3.7.1, "How to Add a Link to a Custom Resource."
  7. In the URL field, enter or browse for the URL to access the resource. Table 10-1 provides the URL format to use for the different resource types.

    Table 10-1 Format for URL Different Resource Types

    Resource Type Location in Application URL Format

    External Link

    None

    Absolute or relative path to web page

    Note: If you use the External Link option to include a mailto: link in your navigation, your navigation UI must explicitly handle this type of link. For information, see Section 11.2.3, "What You Should Know About Creating Page Templates for WebCenter Portal Applications."

    External Application

    External application connection in the Application Resources pane

    extapp://External_Application_Id
    

    Page

    Application Navigator

    page://Path_to_Page/Page_Name
    

    For example:

    page://oracle/webcenter/portalapp/pages/myPage.jspx
    

    Task Flow from an ADF Library

    Resource Palette

    taskflow://Path_to_TaskFlow/TaskFlow_Definition_File_Name#TaskFlow_Id
    

    Task Flow Within the Application

    Application Navigator

    taskflow://Path_to_TaskFlow/TaskFlow_Definition_File_Name#TaskFlow_Id
    

    Portlet

    Portlet producer connection in the Application Resources pane or in the Resource Palette

    portlet://Producer_Id/Portlet_Id
    

    Note:

    If the following is true, you must make sure that an appropriate connection is added to the application (in the Application Resources pane) to ensure that the resource is available at runtime:
    • You manually entered the URL (without using drag and drop or the Choose a Resource dialog)

    • The link Type is External Application, or Portlet

    • The connection exists in the Resource Palette

  8. Select Render URL in Page Template, to render the resource in the current page, using the specified page template.

    Select Redirect to URL, to overwrite the current page with the resource when it is selected in the navigation.

  9. In the Visible field, specify whether the resource is displayed in the navigation. The default value is the EL expression #{true}, which means the resource is displayed to all users at all times. Enter false or #{false} to hide the resource from all users at all times, or enter an EL expression to specify the conditions under which the resource is displayed. If the field is empty, the value defaults to true.

    Note:

    Resources are automatically filtered based on security. If a user does not have access to a particular resource, it is not displayed when the navigation model is rendered on the page.
  10. In the URL Attributes section, specify any desired display options for the resource. For more information, see Section 10.3.9, "How to Set Display Options for a Resource."

  11. In the URL Parameters section, enter values, as desired, for any parameters supported by the selected resource.

  12. Save the navigation model definition file.

10.3.5 How to Add a Page Hierarchy to a Navigation Model

You can add a hierarchy of pages to the navigation model. All pages below the selected page in the hierarchy are included in the navigation model.

Although there is only a single page hierarchy within an application, in a navigation model you can use any node within the application page hierarchy as the starting point.

Note:

If you just want to include a single page in the navigation model, use the Link navigation type. For more information, see Section 10.3.4, "How to Add a Page, Portlet, Task Flow, External Application, or Web Page to a Navigation Model."

To add a page hierarchy:

Tip:

To add a section of the page hierarchy to a navigation model, you can drag and drop a page (which has been added to the page hierarchy) from the Application Navigator into the Design view for the navigation model. Choose Page Query from the popup menu that appears.
  1. In the Application Navigator, right-click the navigation model to which you want to add the resource, and choose Open.

  2. In the Design view for the navigation model, in the Navigation column on the left side, select the node in the navigation model under which you want to add the resource.

  3. Click the Add new node icon and choose Page Query.

  4. The Id field is automatically populated with a generated ID. You can keep this ID, but you will probably want to change it to something slightly more descriptive. The ID must be unique within the navigation model.

    If the resource is at the top level of the navigation model, the ID must not be wc_navtitle or wcnav_externalId; these IDs are reserved.

    Tip:

    If the ID is not unique, or you enter any invalid characters in the ID, the border of the field becomes red.

    Figure 10-7 Adding a Page Query to a Navigation Model

    Description of Figure 10-7 follows
    Description of "Figure 10-7 Adding a Page Query to a Navigation Model"

  5. The Scope field is not applicable to WebCenter Portal applications (the scope is always the current application), so you can leave this field empty.

    Scope is used in WebCenter Spaces to determine whether to display all the pages in the Home Space or a specific Space if a particular page is not specified as the root of the page query.

  6. In the Path field, enter the path and file name of the XML file that corresponds to the page within the page hierarchy that you want to use as the starting point of the page query. For example:

    /oracle/webcenter/portalapp/pagehierarchy/pages/pages.xml
    /oracle/webcenter/portalapp/pagehierarchy/pages/productsPages.xml
    
  7. From the Page Template dropdown list, select the page template to use to display the resource when it is selected in the navigation.

  8. From the Page Style dropdown list, select the style of page to include in the navigation model. For example, if you select Wiki, only pages that use the Wiki page style are included in the navigation..

  9. From the Page Visibility dropdown list, select whether to include pages even if they have been flagged as hidden in the hierarchy.

  10. In the Visible field, specify whether the resource is displayed in the navigation. The default value is the EL expression #{true}, which means the resource is displayed to all users at all times. Enter false or #{false} to hide the resource from all users at all times, or enter an EL expression to specify the conditions under which the resource is displayed. If the field is empty, the value defaults to true.

    Note:

    Resources are automatically filtered based on security. If a user does not have access to a particular resource, it is not displayed in the navigation when it is rendered on the page.
  11. Select Insert Folder Contents to display the subpages in the hierarchy directly in the navigation rather than displaying them under a folder for the parent page.

  12. In the Page Query Attributes section, specify any desired display options for the resource. For more information, see Section 10.3.9, "How to Set Display Options for a Resource."

  13. In the Page Query Parameters section, enter values, as desired, for any parameters supported by the page template.

  14. Save the navigation model definition file.

10.3.6 How to Embed Another Navigation Model Within a Navigation Model

You can nest navigation models within each other. For example, if you have a complex navigation model, it might be easier to break it down into several separate models and then nest them all within a single overarching navigation model. You can also use nested navigation models to delegate the development of navigation models to different users or to control access to different parts of the navigation.

To embed another navigation model within a navigation model:

Tip:

To embed another navigation model within a navigation model you can also drag and drop the navigation model that you want to embed from the Application Navigator into the Design view for the navigation model.
  1. In the Application Navigator, right-click the navigation model to which you want to add the resource, and choose Open.

  2. In the Design view for the navigation model, in the Navigation column on the left side, select the node in the navigation model under which you want to add the resource.

  3. Click the Add new node icon and choose Navigation.

  4. The Id field is automatically populated with a generated ID. You can keep this ID, but you will probably want to change it to something slightly more descriptive. The ID must be unique within the navigation model.

    If the resource is at the top level of the navigation model, the ID must not be wc_navtitle or wcnav_externalId; these IDs are reserved.

    Tip:

    If the ID is not unique, or you enter any invalid characters in the ID, the border of the field becomes red.

    Figure 10-8 Embedding Another Navigation Model Within a Navigation Model

    Description of Figure 10-8 follows
    Description of "Figure 10-8 Embedding Another Navigation Model Within a Navigation Model"

  5. In the Path field, enter or browse for the location and file name of the navigation model definition file for the navigation model that you want to embed, for example:

    /oracle/webcenter/portalapp/navigations/myNavigation2.xml
    
  6. In the Visible field, specify whether the resource is displayed in the navigation. The default value is the EL expression #{true}, which means the resource is displayed to all users at all times. Enter false or #{false} to hide the resource from all users at all times, or enter an EL expression to specify the conditions under which the resource is displayed. If the field is empty, the value defaults to true.

    Note:

    Resources are automatically filtered based on security. If a user does not have access to a particular resource, it is not displayed in the navigation when it is rendered on the page.
  7. In the Navigation Attributes section, specify any desired display options for the resource. For more information, see Section 10.3.9, "How to Set Display Options for a Resource."

  8. Save the navigation model definition file.

10.3.7 How to Extend Navigation Model Data

As well as adding known resources to your navigation model, you can also add resources to the model that are dynamically generated at runtime.

This section includes the following subsections:

10.3.7.1 How to Add a Link to a Custom Resource

You can add links to various WebCenter-supported resources, such as pages, portlets, and task flows, by adding a link of the appropriate Type and identifying the URL of the resource. For more information, see Section 10.3.4, "How to Add a Page, Portlet, Task Flow, External Application, or Web Page to a Navigation Model."

If you want to link to a third party resource, you can do so by adding a link of type Other, and specifying the third-party URLResourceFactory implementation class.

To add a link to a custom resource:

  1. In the Application Navigator, right-click the navigation model to which you want to add the resource, and choose Open.

  2. In the Design view for the navigation model, in the Navigation column on the left side, select the node in the navigation model under which you want to add the resource.

  3. Click the Add new node icon and choose Link.

  4. The Id field is automatically populated with a generated ID. You can keep this ID, but you will probably want to change it to something slightly more descriptive. The ID must be unique within the navigation model.

    If the resource is at the top level of the navigation model, the ID must not be wc_navtitle or wcnav_externalId; these IDs are reserved.

    Tip:

    If the ID is not unique, or you enter any invalid characters in the ID, the border of the field becomes red.
  5. From the Type dropdown list, select Other.

    Figure 10-9 Adding a Custom Resource to a Navigation Model

    Description of Figure 10-9 follows
    Description of "Figure 10-9 Adding a Custom Resource to a Navigation Model"

  6. In the Factory Class field, enter or browse for the URLResourceFactory implementation class that can resolve the URL for the custom resource.

  7. In the URL field, enter the URL to access the resource.

  8. Select Render URL in Page Template, to render the resource in the current page, using the specified page template.

    Select Redirect to URL, to overwrite the current page with the resource when it is selected in the navigation.

  9. In the Visible field, specify whether the resource is displayed in the navigation. The default value is the EL expression #{true}, which means the resource is displayed to all users at all times. Enter false or #{false} to hide the resource from all users at all times, or enter an EL expression to specify the conditions under which the resource is displayed. If the field is empty, the value defaults to true.

    Note:

    Resources are automatically filtered based on security. If a user does not have access to a particular resource, it is not displayed in the navigation when it is rendered on the page.
  10. In the URL Attributes section, specify any desired display options for the resource. For more information, see Section 10.3.9, "How to Set Display Options for a Resource."

  11. In the URL Parameters section, enter values, as desired, for any parameters supported by the selected resource.

  12. Save the navigation model definition file.

10.3.7.2 How to Add a Component to a Navigation Model

You can add a custom component to a navigation model. You can add a variety of components, such as simple ADF Faces components, compound objects containing two or more components, and JSF Verbatim tags that let you add arbitrary HTML content inside them. An example for arbitrary HTML that you can add to your catalog is a YouTube video.

To add a custom component:

  1. In the Application Navigator, right-click the navigation model to which you want to add the resource, and choose Open.

  2. In the Design view for the navigation model, in the Navigation column on the left side, select the node in the navigation model under which you want to add the resource.

  3. Click the Add new node icon and choose Component.

  4. The Id field is automatically populated with a generated ID. You can keep this ID, but you will probably want to change it to something slightly more descriptive. The ID must be unique within the navigation model.

    If the resource is at the top level of the navigation model, the ID must not be wc_navtitle or wcnav_externalId; these IDs are reserved.

    Tip:

    If the ID is not unique, or you enter any invalid characters in the ID, the border of the field becomes red.

    Figure 10-10 Adding a Custom Component to a Navigation Model

    Description of Figure 10-10 follows
    Description of "Figure 10-10 Adding a Custom Component to a Navigation Model"

  5. In the Component Factory field, enter or browse for the Java class that implements the oracle.adf.rc.component.ComponentFactory interface and creates an instance of the component based on a set of parameters, for example, oracle.adf.rc.component.XmlComponentFactory.

    As you type the name, the field autocompletes with valid factory classes from the classpath.

    For more information, see Section C.4, "Factory Classes Available for Adding Dynamic Resources to the Catalog."

  6. In the Visible field, specify whether the resource is displayed in the navigation. The default value is the EL expression #{true}, which means the resource is displayed to all users at all times. Enter false or #{false} to hide the resource from all users at all times, or enter an EL expression to specify the conditions under which the resource is displayed. If the field is empty, the value defaults to true.

    Note:

    Resources are automatically filtered based on security. If a user does not have access to a particular resource, it is not displayed in the navigation when it is rendered on the page.
  7. In the Component Attributes section, specify any desired display options for the resource. For more information, see Section 10.3.9, "How to Set Display Options for a Resource."

  8. In the Component Parameters section, add the parameters that define the component.

    For example, if you are adding an XML component, click the Add icon in the Parameters section and select xml. In the new row that is displayed, specify the XML code for the component in the Value field.

    Note:

    The xml parameter is displayed only if you selected oracle.adf.rc.component.XmlComponentFactory as the component factory.

    To ensure that the component works properly, you must specify the custom component ID to be #, and provide the namespace, as shown in the following example:

    <cust:panelCustomizable id="#" xmlns:cust="http://xmlns.oracle.com/adf/faces/customizable"/>
    

    The # value ensures that a unique ID is generated dynamically for the component.

  9. Save the navigation model definition file.

10.3.7.3 How to Add a Custom Folder to a Navigation Model

You can add a custom folder to a navigation model that is configured to display its content dynamically at runtime. A custom folder is not added as a folder with resources; it contains only a reference to the factory class, which displays the resources dynamically.

To add a custom folder:

  1. In the Application Navigator, right-click the navigation model to which you want to add the resource, and choose Open.

  2. In the Design view for the navigation model, in the Navigation column on the left side, select the node in the navigation model under which you want to add the resource.

  3. Click the Add new node icon and choose Custom Folder.

  4. The Id field is automatically populated with a generated ID. You can keep this ID, but you will probably want to change it to something slightly more descriptive. The ID must be unique within the navigation model.

    If the resource is at the top level of the navigation model, the ID must not be wc_navtitle or wcnav_externalId; these IDs are reserved.

    Tip:

    If the ID is not unique, or you enter any invalid characters in the ID, the border of the field becomes red.

    Figure 10-11 Adding a Custom Folder to a Navigation Model

    Description of Figure 10-11 follows
    Description of "Figure 10-11 Adding a Custom Folder to a Navigation Model"

  5. In the Path field, enter the MDS path for the custom folder.

  6. In the Initial Context Factory field, enter or browse for the Java class that implements the javax.naming.spi.InitialContextFactory interface and generates the folder based on a set of parameters.

    For more information, see Section C.4, "Factory Classes Available for Adding Dynamic Resources to the Catalog."

  7. In the Visible field, specify whether the resource is displayed in the navigation. The default value is the EL expression #{true}, which means the resource is displayed to all users at all times. Enter false or #{false} to hide the resource from all users at all times, or enter an EL expression to specify the conditions under which the resource is displayed. If the field is empty, the value defaults to true.

    Note:

    Resources are automatically filtered based on security. If a user does not have access to a particular resource, it is not displayed in the navigation when it is rendered on the page.
  8. Select Insert Folder Contents to display the contents of the custom folder directly in the navigation rather than displaying them under the folder.

  9. In the Custom Folder Attributes section, specify any desired display options for the resource. For more information, see Section 10.3.9, "How to Set Display Options for a Resource."

  10. In the Custom Folder Parameters section, add the parameters that were defined while implementing the factory class. You can bind these parameters to other artifacts in the application.

  11. Save the navigation model definition file.

10.3.7.4 How to Add a Custom Content Provider to a Navigation Model

A custom content provider dynamically generates zero or more navigation items at runtime. It is very similar to a custom folder, except that, for custom folders, the folder is always displayed when the navigation model is rendered at runtime, even if it is empty. With custom content providers however, the folder is displayed at runtime only if it has content inside it.

To add custom content provider:

  1. In the Application Navigator, right-click the navigation model to which you want to add the resource, and choose Open.

  2. In the Design view for the navigation model, in the Navigation column on the left side, select the node in the navigation model under which you want to add the resource.

  3. Click the Add new node icon and choose Custom Content.

  4. The Id field is automatically populated with a generated ID. You can keep this ID, but you will probably want to change it to something slightly more descriptive. The ID must be unique within the navigation model.

    If the resource is at the top level of the navigation model, the ID must not be wc_navtitle or wcnav_externalId; these IDs are reserved.

    Tip:

    If the ID is not unique, or you enter any invalid characters in the ID, the border of the field becomes red.

    Figure 10-12 Adding a Custom Content Provider to a Navigation Model

    Description of Figure 10-12 follows
    Description of "Figure 10-12 Adding a Custom Content Provider to a Navigation Model"

  5. In the Content Provider field, enter or browse for the Java class that implements the oracle.adf.rc.spi.plugin.catalog.CustomContentProviderV2 interface.

    For more information, see Section C.4, "Factory Classes Available for Adding Dynamic Resources to the Catalog."

  6. In the Visible field, specify whether the resource is displayed in the navigation. The default value is the EL expression #{true}, which means the resource is displayed to all users at all times. Enter false or #{false} to hide the resource from all users at all times, or enter an EL expression to specify the conditions under which the resource is displayed. If the field is empty, the value defaults to true.

    Note:

    Resources are automatically filtered based on security. If a user does not have access to a particular resource, it is not displayed in the navigation when it is rendered on the page.
  7. In the Custom Content Attributes section, specify any desired display options for the resource. For more information, see Section 10.3.9, "How to Set Display Options for a Resource."

    Note:

    Typically for custom content, you will not need to specify any attributes, because the attributes for the resources generated by the content provider will be specified by the content provider.
  8. In the Custom Content Parameters section, define the parameters on the folder. The parameters you define here are passed to and interpreted by the CustomContentProviderV2 implementation.

  9. Save the navigation model definition file.

10.3.8 How to Organize Resources in a Navigation Model

You can add folders to your navigation model to create subsets of resources or to group similar resources. You can also add separators to divide the navigation model into distinct groupings of resources. Folders and separators enable you to break up the items in the navigation model when it is rendered on in a page, making it easier to locate items.

You can also rearrange items within the navigation model by dragging them up and down in relation to each other and dragging them inside other items to indicate hierarchy.

To organize resources:

  1. In the Application Navigator, right-click the navigation model whose resources you want to organize, and choose Open.

  2. To add a folder or separator:

    1. In the Design view for the navigation model, in the Navigation column on the left side, select the node in the navigation model under which you want to add the folder or separator.

    2. Click the Add new node icon and choose Folder or Separator.

    3. The Id field is automatically populated with a generated ID. You can keep this ID, but you will probably want to change it to something slightly more descriptive. The ID must be unique within the navigation model.

      If the resource is at the top level of the navigation model, the ID must not be wc_navtitle or wcnav_externalId; these IDs are reserved.

      Tip:

      If the ID is not unique, or you enter any invalid characters in the ID, the border of the field becomes red.
    4. In the Visible field, specify whether the resource is displayed in the navigation. The default value is the EL expression #{true}, which means the resource is displayed to all users at all times. Enter false or #{false} to hide the resource from all users at all times, or enter an EL expression to specify the conditions under which the resource is displayed. If the field is empty, the value defaults to true.

  3. To move a resource within the navigation model, select the item and drag it to the desired position.

  4. To indent one resource (child item) under another (parent item), select the child item and drag it over the top of the parent item.

  5. To re-parent a resource, right click it and choose Change Parent.

  6. Save the navigation model definition file.

10.3.9 How to Set Display Options for a Resource

You can specify various display options for resources to determine their appearance and behavior when the navigation is rendered on a page. The display options available depend on the type of the resource.

To set display options for a resource:

  1. In the Application Navigator, right-click the navigation model that contains the resource for which you want to set display options, and choose Open.

  2. In the Design view for the navigation model, in the Navigation column on the left side, select the resource.

  3. In the URL Attributes panel, click the Add icon and choose the attribute that you want to set. Table 10-0 lists the available attributes.

    Table 10-2 Resource Attributes

    Attribute Description

    Title

    The title displayed for the resource when the navigation model is rendered on a page.

    AccessKey

    A key mnemonic (single character) that users can enter to access the resource without using the mouse.

    Description

    A description of the resource.

    IconURI

    An icon to visually represent the resource. This is displayed next to the Title when the navigation model is rendered on a page.

    Subject

    Keywords to facilitate searching of the resource.

    Target

    The location on the container page where the resource is displayed when it is selected, either in the same browser window (_self), a new window (_blank), or a popup (_popup), or any other location supported by the navigation UI.

    ToolTip

    Text that displays to provide additional information about the resource when users hover the mouse over the Title.

    Modified

    The date of the last modification of the resource. This attribute is used for site map creation.

    ChangeFrequency

    How frequently the resource is likely to change: always, hourly, daily, weekly, monthly, yearly, never. This attribute is used for site map creation.

    Significance

    The priority of this resource relative to other resources in the navigation model, within the range 0.0 to 1.0. This attribute is used for site map creation.

    ExternalId

    An ID to enable a direct reference to a node in the navigation model from a static link in the page.

    Nodes in the default navigation model with this attribute defined can be accessed using /faces/wcnav_externalId/externalId from an af:goLink component in a page or using /wcnav_externalId/externalId from an External Link navigation item in the navigation model. The alternative is to access the node by its hierarchy, which is faster, but may change as the application develops.

    To directly access a node in a non-default navigation model, you must specify the path of the navigation model by setting the wcnav.modelPath URL parameter, for example:

    /faces/wcnav_externalId/myNavigationItem?wcnav .modelPath=/oracle/webcenter/siteresources/scopedMD/
    s7f446cab_f622_4b68_a83e_b7eaf28b52ec/navigation/gsr0271c712_721a_4565_9f0e_755784a7093b/
    myProjectNavigationModel.xml
    

  4. From the Value Type dropdown list, choose:

    • Literal String—to specify a string as the value for the attribute

    • Resource Bundle—to use a resource bundle to provide localized values for the attribute.

  5. In the Display Value field, enter the value for the attribute. If you are using a resource bundle, click the Browse icon to select the resource bundle to search for the localized value.

  6. Save the navigation model definition file.

10.4 Selecting the Default Navigation Model

The default navigation model provides a convenient way to select a navigation model that should be used by default by an application. Page template designers can then reference this default navigation model without having to know its actual name. For example, in navigation EL expressions, the default navigation model is often referenced, such as in #{navigationContext.defaultNavigationModel}.

When you first create a WebCenter Portal application, the seeded navigation model, default-navigation-model.xml, is set as the default navigation model. If you subsequently create your own navigation model, rather than having to explicitly reference this navigation model whenever you want to use it, you can set it as the default.

You can set the default navigation model for an application by editing the oracle.webcenter.portalapp.navigation.model preference in the adf-config.xml file.

To select the default navigation model:

  1. In the Application Resources pane of the Application Navigator, right-click the adf-config.xml file, and choose Open.

    Tip:

    To locate the adf-config.xml file, expand the Descriptors node, and then the ADF META-INF node.
  2. Click the Source tab.

  3. Locate the ADF preference with the following id:

    oracle.webcenter.portalapp.navigation.model
    
  4. Set the value attribute to the path of the navigation model that you want to use as the default for the portal, for example:

    value="oracle/webcenter/portalapp/navigations/myNavigationModel.xml"
    

    Example 10-1 shows an example of the complete preference element.

    Example 10-1 The Default Navigation Model ADF Preference

    <portal:adf-portal-config>
      <preferences>
        ...
        <preference id="oracle.webcenter.portalapp.navigation.model"
            desc="Default Navigation Model"
            value="oracle/webcenter/portalapp/navigations/myNavigationModel.xml"
            resourceType="navigation" display="true"/>
        ...
      </preferences>
    </portal:adf-portal-config>
    
  5. Save the adf-config.xml file.

10.5 Editing the Navigation Renderer

The navigation renderer is a JSPX page renders non-page navigation resources, including:

  • Portlets

  • Content

  • External links

  • External applications

  • Task flows

To change how these resources are rendered, you can edit the navigation renderer page. For example, you may also want to add an image before or after the navigation renderer task flow or change from a flow to a stretch layout.

The navigation renderer page is hidden by default, so you must first show it in your application before you can edit it.

Note:

In the vast majority of cases, you should be able to edit the existing navigation renderer to meet your requirements. However, if required, you can create your own navigation renderer page. For example, the navigation renderer expects a content facet. If you want to use a different facet, you can create your own page and place the navigation renderer task flow in the appropriate location for your template.

If you choose to create your own navigation renderer page, it must include a navigation renderer region that contains the navigation renderer task flow.

To set your page as the navigation renderer for the application, edit the navigation renderer ADF preference (oracle.webcenter.portalapp.navigation.renderer) to point to the appropriate file. For detailed instructions for how to edit an ADF preference, see Section 10.4, "Selecting the Default Navigation Model."

To edit the navigation renderer:

  1. In the Application Navigator, right-click the application project and choose Project Properties.

  2. Expand the Project Source Paths node and select Web Application.

  3. Select the Excluded tab.

  4. Select the navigation renderer file (navigation-renderer.jspx) and click Remove to remove it from the list of excluded files.

  5. Click OK.

    The navigation renderer JSPX file is now listed in the Application Navigator under the following node:

    /oracle/webcenter/portalapp/pages/
    
  6. Right click navigation-renderer.jspx and choose Open.

  7. Click the Source tab and edit the file as required.

  8. When you are finished, save the navigation-renderer.jspx file.

10.6 Setting the REDIRECT_OPTIONS Context Parameter

If your application does not use partial page refresh (PPR), the URL in the browser changes whenever a user navigates to a resource in the navigation model. However, the URL shown by the browser does not reflect the current page; it shows the URL of the last page shown.

To enable the browser to display the URL of the current page, you can set the oracle.webcenter.navigationframework.REDIRECT_OPTIONS context parameter in the web.xml file.

Note:

Setting the oracle.webcenter.navigationframework.REDIRECT_OPTIONS context parameter affects performance by adding an extra request/response for every navigation.

To set the REDIRECT_OPTIONS context parameter:

  1. In the Application Navigator, right-click the web.xml file and choose Open.

  2. In the Overview Editor, expand the Context Initialization Parameters section.

  3. Click the Create Context Initialization Parameter icon.

  4. In the Name field, enter oracle.webcenter.navigationframework.REDIRECT_OPTIONS.

  5. In the Value field, enter toPrettyURL.

    This adds the following to the web.xml file:

    <context-param>
     <param-name>oracle.webcenter.navigationframework.REDIRECT_OPTIONS</param-name>
     <param-value>toPrettyURL</param-value>
    </context-param>
     
    
  6. Save the web.xml file.

10.7 Enabling Runtime Administration of Navigation Models

The Resource Manager in a WebCenter Portal application enables users with administrative privileges to create and modify portal resources, including navigation models, at runtime. By exposing navigations in the Resource Manager, you allow administrators to manage these navigations at runtime. If you want to create and expose more navigations after deploying the application, you can export them from JDeveloper to the runtime application.

To expose a navigation in the Resource Manager, see Section 16.2.1, "How to Add a Resource to the Resource Manager."

You can also control exactly which resources users can add to navigation models at runtime by editing the navigation registry file, navigation-registry.xml.

For more information about the runtime features of navigation models, see the chapter "Working with Navigations" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Spaces.

This section includes the following subsections:

10.7.1 How to Edit the Navigation Registry File

The navigation registry is a Resource Catalog specifically for registering which resources users can add to navigation models at runtime. Each WebCenter Portal application contains one navigation registry file, navigation-registry.xml, which is created when you create the application. You can edit this file to change which resources to include. For example, if you do not want users to be able to embed other navigation models at runtime, you can remove the Navigation Reference resource from the navigation registry.

To edit the navigation registry:

  1. In the Application Navigator, right-click the navigation-registry.xml file.

    Tip:

    You can find this file under Application_Root/oracle/webcenter/portalapp/navigations.
  2. Edit the file the same way as any other Resource Catalog. For more information, see Section 15.2.3, "How to Manage Content in the Resource Catalog."

    You can add the following resources to the navigation registry:

    • Folder

    • Link

      • Task Flow

      • Portlet

      • Content

      • Other

    • Resource Catalog

    • Component

    • Custom Folder

    • Custom Content

    You can also modify and remove existing resources in the navigation registry, and rearrange resources in the registry.

  3. When you are finished, save the navigation-registry.xml file.

10.7.2 How to Enable Further Development of Deployed Navigation Models

Seeded navigation models cannot be modified or deleted in the Resource Manager. Users with administrative privileges can make a copy of a seeded navigation model and edit or delete it, or they can create their own navigation models.

If users create or edit navigation models at runtime, you may find that you need to bring them back into JDeveloper for further enhancement. You can do this by downloading the navigation model from the deployed application, editing it in JDeveloper, and uploading it back to the application. At design time, this type of round-trip development includes importing the downloaded navigation model, editing it in JDeveloper, and exporting it so that it can be uploaded back to the deployed application.

In addition, if you create a new navigation model after you have deployed your application, you can export the navigation model from JDeveloper and upload it into the deployed application.

This section describes how to import and export navigation models in JDeveloper. It includes the following subsections:

For more information about round-trip development, see Section 16.4, "Enabling Round-Trip Development of Resources."

10.7.2.1 Importing a Navigation Model

When you download a navigation model from the Resource Manager, an EAR file is created. On importing the EAR file in JDeveloper, the files from the EAR file are extracted to the folder Application_Root/Portal/public_html/oracle/webcenter/siteresources/scopedMD/scope_GUID. You can open the navigation model and edit it as you would any other navigation model at design time. The updated navigation model must then be exported to the deployed application.

For detailed steps to import a resource, see Section 16.4.3, "How to Import a Portal Resource into JDeveloper."

10.7.2.2 Exporting a Navigation Model

You would need to perform an export for the following reasons:

  • To expose a new navigation model in an already deployed application.

  • To copy back a navigation model that you imported from a deployed application and modified.

When you export a navigation model from JDeveloper, an EAR file is created. Users with administrator privileges can then upload this EAR file to a deployed application using the Resource Manager.

For detailed steps to export a resource, see Section 16.4.4, "How to Export a Portal Resource from JDeveloper."

10.8 Working with WebCenter Spaces Navigation Models

Out of the box, WebCenter Spaces provides seeded navigation models that you can use in your Spaces. If these default navigation models do not suit your requirements, you can build your own navigation models within WebCenter Spaces. For more information, see the section "Working with Navigation" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Spaces.

However, WebCenter Spaces may not provide all the controls to create a navigation model that provides all the functionality that you require. In such cases, in JDeveloper you can edit navigation models originally created in WebCenter Spaces, and then upload them back into WebCenter Spaces.

WebCenter provides a special JDeveloper workspace (DesignWebCenterSpaces.jws) to help you develop and upload resources, such as navigation models, to WebCenter Spaces. Chapter 49, "Extending WebCenter Spaces Using JDeveloper" tells you where to find the sample workspace and explains how to use the WebCenterSpacesResources project to build custom navigation models and other types of resources for WebCenter Spaces.

When working with WebCenter Spaces navigation models in JDeveloper, you should consider the following:

  • All the resources required for a WebCenter Spaces navigation model exist within WebCenter Spaces. Therefore, you should really only use JDeveloper to restructure WebCenter Spaces navigation models and perform minor edits. First, you should create as much of the navigation model in WebCenter Spaces as possible and add the required resources. You can then use JDeveloper to refine the order of the resources and set all required attributes and parameters.

  • If you do want to use JDeveloper to add resources to a WebCenter Spaces navigation model, you should obtain the resource ID from WebCenter Spaces by accessing the About dialog for the resource. For more information, see the section "Viewing Information About a Resource" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Spaces.

  • When adding resources to a WebCenter Spaces navigation model, you must manually enter the path to the resource. You cannot use the Browse icon. For example, to enter a link to a page, you must identify the ID of the page in WebCenter Spaces and then enter that value manually as page://pathToXmlFile.