About NavigationBar

The navigationBar component is used to create a navigator that displays the user's current position among a set of steps or a block of records while allowing the user to navigate back and forth through the steps or records via generated links.

A navigationBar component that is used within the pageButtons component displays below the title on a page as well as at the bottom of the page.

You can create two types of navigators using the navigationBar component:

step-by-step navigator
record navigator

A step-by-step navigator shows the progress of a task through a sequence of known steps, such as those in a wizard. By default the generated text for the step-by-step navigator is in the format "Step 3 of 6". The generated links are Back and Next buttons that enable the user to navigate through the task one step at a time.

A record navigator is used with large sets of records. It shows a block of records at a time, and the generated text is based on the blockSize attribute that you set. For example, for a block size of 10, the generated text for the record navigator is in the format "10-19 of 100", and the generated links for browsing the range of records are in the formats "Previous 10" and Next 10".

The blockSize attribute defaults to the constant "-1", which causes a step-by-step NavigationBar to be rendered. Setting it to any other value causes the NavigationBar to render as a record navigator with the specified number of records as the currently viewed block size. Setting the blockSize to the special value of zero also causes a NavigationBar that has no range and disabled links to be rendered.

The generated links for a step-by-step navigator or record navigator are generated URLs based on the destination, value, and name attributes of the navigationBar component. The parameters of a generated URL are the "goto" event ID, the requested step or value to view, and the navigation bar component name as the source parameter. If a record navigator is rendered by a table, the table component name is used as the source parameter.

The navigationBar component can generate links that trigger form submission using Javascript. When the formSubmitted attribute of navigationBar is set to "true", form submission is enabled whereby the event, source, and value fields will be set to "goto", the navigation bar component name, and the requested step or value to view, respectively. In the case of a record navigator, the source field will be set to the table component name if the navigator is rendered by a table, and the size field will be set to the number of records to display.

Use the showAll attribute to specify whether a "Show All" option should be displayed in a record navigation bar.

Note: You must set a "goto" event handler for the links to function properly because the navigationBar sends a "goto" event when a user clicks a link.

Step-by-Step with Choice

To replace the read-only "Step X of Y" text with a choice list, insert link components as children of navigationBar. The navigationBar fires the same "goto" event, ignoring the destinations of the links.

When using a choice list, users will be able to jump back as many steps as they wish. They are not allowed, however, to advance past the current step unless the maxVisited attribute is set. You should set the maxVisited attribute only if a user has already visited a step but then moved backwards to an earlier step.