Navigating among web pages with navigation rules

A JSF Handler can control the navigation on a website, forwarding the user from one page to another and passing data between pages. EGL works closely with JavaServer Faces (JSF) navigation functionality to control page navigation in this way.

EGL provides two ways to navigate to another page: forward to URL and forward to label, the default. When using forward to URL, you specify an absolute or relative URL to the target page; when using forward to label, you specify a navigation rule that in turn points to the target page. When navigating among pages in an EGL applications, use forward to label; when navigating to a web page in a different application, use forward to URL.

The JSF servlet responds to a forward statement by issuing either a forward or a redirect. A JSF redirect prompts the user's web browser to load a different target page; the effect is the same as if the user had typed the new URL into the browser's address bar, including the loss of any request information that was passed to the first page. A JSF forward, not to be confused with an EGL forward statement, loads the new page in the browser without indicating to the browser that the location has changed. In the case of the JSF forward, the browser believes that it is still at the original page location, though it is displaying the new target page. In this case, the request information is available to the new target page. However, the browser and servlet are out of sync, because the browser is not viewing the same page that it requested from the servlet. This mismatch can cause problems; for example, relative links to files such as images and stylesheets must be relative to the original page, rather than the forwarded target page, because the browser will interpret the links relative to the original page.

In the functions defined in the onConstructionFunction, onPreRenderFunction, or onPostRenderFunction properties of a JSF Handler, you can use forward to URL but not forward to label.

Forwarding to a label

When navigating from page to page within an EGL application, use forward to label. To forward the user from one page to another, you must know the name of the JSF navigation rule that points to the target page. By default, the name of the navigation rule that points to a page is the same as the name of the JSF Handler that manages that page.

For example, a page named myPage.jsp might have a JSF Handler named myPage in a file named myPage.egl. By default, the navigation rule for this page is myPage. When you know the navigation rule of the target page, you can use the EGL forward statement to send the user's web browser to that target page. In this case, to forward to the page myPage.jsp, use the following code:
forward to label "myPage";
To find the navigation rule that points to a page, look in the faces-config.xml file, which is in the WebContent/WEB-INF folder of your EGL web project. This file lists the rules and the pages to which those rules lead. The previous example used a navigation rule that looks like this:
<navigation-case>
    <from-outcome>myPage</from-outcome>
    <to-view-id>/myPage.jsp</to-view-id>
</navigation-case>
The navigation rule contains two strings: a label for the rule and a relative link to the target page. In this case, the label is myPage and the link refers to a page named myPage.jsp in the same directory as the page that used the navigation rule. Note the beginning slash before the file name of the page, which is a requirement for the navigation rule. This navigation rule will result in a JSF forward as described above.
To navigate to a page in a different EGL web project, use a relative URL reference. For example, to link from the page myProject01/myPage01.jsp to a file named myPage02.jsp in a project named myProject02, use the following navigation rule:
<navigation-case>
    <from-outcome>myPage02</from-outcome>
    <to-view-id>/../myProject02/myPage02.jsp</to-view-id>
    <redirect/>
</navigation-case>
The <redirect/> tag is required for a navigation rule pointing to a target page in a different project. JSF uses a redirect rather than a forward when navigating from a page in one project to a page in another project.

Forwarding to a URL

You can also use forward to send the user to another web page by specifying the complete URL of the page:
forward to URL "http://www.ibm.com";
You can also specify a relative URL:
forward to URL "../myPage02.jsp";
Finally, you can specify a URL relative to the context root, or the directory that contains all of the projects on the server:
forward to URL "/myProject02/myPage02.jsp";

When forwarding to another page controlled by an EGL JSF Handler, be sure to use the correct extension of .faces or .jsp, as explained in Running a web page on a server.


Feedback