Controlling Navigation Using Branches

A branch is an instruction to link to a specific page, procedure, or URL after a given page is submitted. For example, you can branch from page 1 to page 2 after page 1 is submitted.

You create a branch by running the Create Branch Wizard and specifying the branch point and branch type.

To create a branch:

1. Navigate to the appropriate Page Definition. See "Accessing a Page Definition".

2. Under Branches in the Page Processing column, click the Create icon.

3. For Point and Type, select a branch point:

   • On Submit: Before Computation - Occurs before computations, validations, or processing. Use this option for a Cancel button.

   • On Submit: Before Validation - Occurs after computations, but before validations or processing. Typically not used. If a validation fails, page processing stops, a rollback is issued, and the page displays the error. Because of this default behavior, you do not need to create branches to accommodate validations. However, you might want to branch based on the result of a computation (for example, to the previous branch point).

   • On Submit: Before Processing - Occurs after computations and validations, but before processing. Use this option to branch based on a validated session state, but before performing any page processing.

   • On Submit: After Processing - Occurs after computations, validations, and processing. This option branches to a URL or page after performing computations, validations, and processing. When using this option, remember to sequence your branches if you have multiple branches for a given branch point.

   • On Load: Before Header - Occurs before a page is rendered. This option displays another page, instead of the current page, or redirects the user to another URL or procedure.

4. Select a branch type and click Next.

5. For Target, specify the target location. The information that appears on the page depends on the branch type you selected:

   1. If the target location is a URL, specify the following:

      • Target is a - Select URL.

      • URL Target - Enter a URL. For example:

        http://www.yahoo.com
        

   2. If the target location is a page, specify the following:

      • Target is a - Select Page in this Application.

      • Page - Specify the target page number.

        You can also select reset pagination for this page. Selecting this option causes the page to return to the first set of data meeting a user's query.

        You can also select include process success message. Selecting this option displays a message when a user submits a page and a branch is taken to another page. If you do not select this option, the message does not display because it is part of submitting the page, not displaying the next one.

      • Request - Specify the request to be used.

      • Clear Cache - Specify the page numbers on which to clear cache. Separate multiple entries with a comma.

   3. To set session state (that is, give a listed item a value):

      • Set these items - Enter a comma-delimited list of item names for which you would like to set session state.

      • With these values - Enter a comma-delimited list of values for the items your specified.

        You can specify static values or substitution syntax (for example, &APP_ITEM_NAME.). Note that item values passed to f?p= in the URL cannot contain a colon. Additionally, item values cannot contain commas unless you enclose the entire value in backslashes (for example, \1234,56\).

   4. Select save state before branching to clear cache and save session state before performing the redirect. See "About Saving State Before Branching".

   5. Click Next.

6. Follow the on-screen instructions.

Creating a Branch on a Page with a Component that Submits

If you have a page with a component that submits, such as a Go button or select list with submit, note that you must create a branch that links back to that page. For example, suppose you have a page with a select list and a submit button. For processing to occur properly, you need to create a branch on the page that links back to the page.

About Saving State Before Branching

Consider selecting save state before branching if your branch is redirecting to a URL or returning a URL and passes clear cache directives or item names and item values in the resulting f?p URL. By default, this information is passed after the branch is taken, displaying any passed information in the URL.

Selecting save state before branching sets potentially sensitive information in session state before the branch redirect. This option improves application security by making URLs less susceptible to tampering and by exposing fewer item names, values, and indications of program logic.

Note that when you select save state before branching, the redirected URL no longer include clear cache or item name and item values. You can still view this information, by running your application in Debug mode. See "Accessing Debug Mode".