WebCenter 11g PS3 Tutorial: Closer look at the navigation model

In the previous part you have seen how to create a WebCenter Portal application and how to create pages at runtime.
In this part I will go into the details of a navigation model. I will show you how you can create and manage a navigation model.

In this part I will also explain how to work with the page hierarchy and how you can modify the default page of your portal.

Before we will create a navigation model, we will first create a few pages so we can add them to the navigation model.
If you haven't done the previous part of the tutorial, you can download the application at the bottom of this page.

First of all, start JDeveloper and load the ViePortal application.

Create the About Us page

Right click on the pages folder from the Web Content/oracle/webcenter/portalapp folder and select New from the context menu.
Select JSF from the list on the left and JSF Page from the list on the right

Specify aboutUs.jspx as the file name.
Make sure that you have selected the Globe page template.

Press the OK button to create the page. We will not care about the content of the page. This will be done in another part (Content integration).

Now to the exact same and create a few more pages:

• courses.jspx
• registration.jspx
• prices.jspx
• teachers.jspx
• myCourses.jspx
• pastCourses.jspx
• futureCourses.jspx

When all the pages are created, the pages folder should look something like this:

Don't mind the content of those pages for now. We are just building the framework for later. Most of these pages will be used in other parts of the tutorial.

Assign security to pages

When we create a new page, it does not have any access assigned to it. This means that we can not access or use the page in our portal yet. 

When you are used to an ADF fusion application you modify the jazn-data.xml and add some security to it. In a WebCenter Portal application this is somewhat different. At the end, the rules are still added to the jazn-data but we don't really modify it by ourself. Instead we are using a page hierarchy. The page hierarchy of our portal is calld pages.xml in the pagehierarchy folder.  
Open that file and you will see a Root node with a Home node. When you select the Home node you will see the properties of the node in the hierarchy:

• ID: this is the unique identifier for the node in the page hierarchy
• Title: This value will be used in the navigation model when we add the page hierarchy to our navigation
• Path: path to the page
• Visible: if you uncheck this checkbox, the page will not be visible in the navigation model when you add the page hierarchy.
• Security: in this section you can specify the security:
• Inherit Parent Security: by selecting this, the page will use the same access settings as its parent node
• Delegate Security: select this by specifying your own security for the page.

As you can see, the Home page inherits security from its parent so select the Root node to investigate the access settings. You'll see that the anonymous user will have view rights and the administrator has all the rights.

Now we will specify the access settings for some pages that we just created.  

Drag & Drop the aboutUs.jspx page on the Root node of the page hierarchy.
Select the aboutUs node and set its Title to About Us. The security and visible settings are fine for now.

We will now add the My Courses section. In this section, the user can view the courses he already attended or the one he will do in the future.

First of all, drag & drop myCourses.jspx on the Root node. Modify the Title to My Courses.
We also need to modify the security for this page because we want only authenticated users to see this page.
Select Delegate Security and uncheck the View permission for the anonymous-role as shown in this image:

You will also notice that the My Courses node has a lock icon in the page hierarchy. This icon tells you that the page has delegate security and it does not inherit the security.

Now drag & drop the futureCourses.jspx on the My Courses node and change the title to Future Courses 
Drag & drop the pastCourses.jspx on the My Courses node and change the title to Past Courses.

When you have done this, the page hierarchy should look something like this:

Because the Future Courses and Past Course inherit the security from their parent (My Courses), they will also not be visible for anonymous users.

Let's take a look at our hard work. Run the Portal project and we'll see our changes take effect.
You'll notice that when the portal is launched we see the About Us link next to the Home:

The My Courses page is not available because we arent't logged in so let's login with any user. You'll see the My Courses page appearing and when you hover over the link you'll also see the subpages:

Modifying the navigation model 

As you can see, we have modified the navigation model without modifying the navigation model. How cool is that! Let me say you... Totally not cool but that isn't your fault. Let's take a closer look at the default navigation model. You can find it as the default-navigation-model.xml in the navigations folder.

As you can see, the navigation model has a single item being the Page Hierarchy. When you select it you can take a look at the properties. From the Path you can see that it is the page hierarchy that we have been modifying. That's why our pages are showing up when we run the portal.

So why did i say it isn't cool to use the page hierarchy in your navigation model? I'll explain this by an example that we will be using in another part of the tutorial. Suppose that we want to add content from the content server to our navigation model. This is easy to do but when you put this after the Page Hierarchy in the navigation model than the content will show up after the About Us page which is not what we want. The About Us page should be the last one of our navigation model and the model the first one. If you want to put resource between the Home page and the Abous Us page than the page hierarchy is just not right for us. That's why it's a good practice to never use the page hierarchy in the navigation model and add each page seperatly.

I can hear you thinking... Why should we use the page hierarchy anyway? Well, you should think of the page hierarchy as the security hierarchy instead of the page hierarchy. You definitly need to use the page hierarchy for assigning access to your pages and specify a hierarchy among those security settings. If you add a page to the navigation model, the security settings from the page hierarchy are applied, no mather what. So let's find out how it works.

First of all, open the default-navigation-model.xml from the navigations folder. Select the Page Hierarchy node and press the delete button so we have an empty navigation model.
Now let us add the Home page. Drag & Drop home.jspx on the default-navigation-model node and select Page Link from the context menu.

When you select the Home node you will see following attributes:

• Id: this is the unique identifier for the node in the navigation model
• Type: this properties defines the type to with the URL attribute is refering to. In our case, this should be Page
• Factory Class: the class that is responsible for the resource. In most cases this field is read-only
• URL: the URL of the resource that we want to add to the navigation model
• Visible: Expression Language specifying whether or not we want to display the node. This value will always be used so no mather what you have specified in the page hierarchy for this page, the visible attribute from the navigation model will be used instead!
• Title: the text for the link that will be used on our pages.

If you want to learn more about the navigation model and types of resources you can add, you can take a look at my book. Chapter 3 contains a complete chapter dedicated to the navigation model. You will also learn more about the navigation model in future sections of the tutorial.

Now add the mycourse.jsxp and aboutUs.jspx to the navigation model and change the title to My Courses and About Us.

In order to show the difference between the page hierarchy and the navigation model,  we will add the futureCourses.jspx after the aboutUs page as shown in image:

We don't modify any other attributes so all the pages should be visible, right? What do you think.... When we run the portal, will we see four pages or only two?
Let's test it by running the portal project:

Did we just brake the application? As a mather of fact, we did!

Setting the default home page

When JDeveloper creates the application, he also creates a default index.html file which can be found in the Web Content root of our application. Let's take a look at the source of that file:

Portal Home

As you can see from the meta-tags, it redirects to ./faces/pages_home. In WebCenter we can use a special syntax in the URL for accessing pages. This uses the ID's of our resources in the navigation model. In this case, the URL redirects to a page called home from the resource with the pages ID.
Because we also want to redirect to the home page we need to modify this redirect to ./faces/home. Why is that? Because home is the ID of home.jspx in the navigation model.  
Make sure you have done the modifications in the index.html and rerun the portal application.

You should now be able to see the portal:

As you can see, we only have two links in the navigation. The My Courses and Future Courses page are not listed although their visible attribute is set to true! This is because the security from the page hierarchy is applied here. The Future Courses page inherits the security from the My Courses page so wherever we put the futureCourses page, the same security as the My Courses page is applied here. Once you login you will see both links appear.

This example shows how the navigation model and the page hierarchy are two seperate things. The navigation model is used to build the navigation while the page hierarchy is used to create a hierarchy of pages based upon security.

This concludes the second part of the tutorial.
You now should be able to build basic navigation models and set security to your pages. You should also know the difference between the page hierarchy and the navigation model!

You can add more types of resources to the navigation model than just pages. I will discuss them into detail in other parts of this tutorial.

Exercises

As promised in the introduction, I will also add some exercises so you could practice the things that we have learned in this part. This way you should think for yourself and not just click and do what the tutor tells you!

1. In this exercise I want you to add the teachers page to the navigation model as a subpage of the Home page. Also make sure that the teachers page is only accessible by the administrators.
2. Move the Future Courses page from the navigation model and add it as a child of the My Courses.
3. Add the prices page between the My Courses and the About Us page.
4. Add the registration page after the About Us page and add security in a way that only anonymous users will see the page.
5. Instead of starting the portal on the Home page, we want it to start at the About Us page. Make the needed changes for this.

If you should have problems doing these exercies, please leave a comment and we can figure it out together.

Download ViePortal_part2

Below you can find the second part of the ViePortal application as it should be after this tutorial. The application does not include the solutions for the exercies. It is in a state as it should be before the exercies. I will add the solutions as a download in the next part of the tutorial.