Portlet Factory, Version 6.1.2
Breadcrumbs builder
The Breadcrumbs builder places a list of links to visited pages on a page in your model. Each link is called a breadcrumb.
In the context of this builder, a page that is associated with a breadcrumb can be a page in the model or a page of data. The links, called breadcrumbs, provide a mechanism for users to return to pages that they displayed in the application. Use this builder to put a breadcrumbs element on a page. A breadcrumbs element is a list of links that represents where the user has visited, with the ability to go the previously visited links. The pages that are saved as breadcrumbs can be either of the following:
- Actual pages in the model
- Data in the form of a key
When dealing with navigating a tree of data, you can use different model pages to display different items. For example, consider a catalog that has multiple groups, including groups within groups that lead to individual items. You might have one model page that is used for displaying a group (with its subgroups and items that it contains) and a different model page for displaying items. This approach is easily supported.
Breadcrumbs are usually placed across the top of a page and indicate the navigation path that the user followed to the current page. Using breadcrumbs, the user can easily backtrack to a previous page by clicking a breadcrumb.
The currently selected level in the breadcrumbs is text, that is, the current page does not have a link to itself. Because clicking the current level does not change the navigation, only the previous levels are links. Specify a separator between levels of the breadcrumbs to clearly illustrate the link intervals. You can specify some text to display before the breadcrumb.
This builder requires only one tag per page location on all pages that will contain the display of the breadcrumbs. You can have the display on all pages that participate in the breadcrumbs. In this case, a user who visits one of the pages creates a breadcrumb in the list. Or you can have this display only on a single page that wraps other pages, for example, by using an Inserted Page builder. The following sections describe the use of the builder:
- Requirements to use the builder
- About navigating through model pages
- About navigating through data
- Advanced navigation through data
- A data provider class
Requirements to use the builder
The following are the requirements for using this builder:
- Provide a unique selector or key for every page used as a breadcrumbs element.
The element can be either a page in your model or a page of data. The unique selector might be a URL or a page name if you are maintaining breadcrumbs of model pages. Or the unique selector might be the key to a database record if you keep breadcrumbs of a user moving through data.
The selector is typically a string. However, you can use advanced inputs to the builder and maintain a key with any sort of object if it can be represented as a string. In this advanced mode, you provide a class with methods to translate from one format to another.
- Write a method to prepare the page to be displayed.
This preparePage method accepts the unique selector as an argument and processes the page to be displayed. The processing can involve no processing if the model tracks visits to pages in the model. Alternatively, the method can make database calls if the model keeps breadcrumbs of a user moving through data.
The method must return a string that is used as the name of the action to invoke in the model to display the page.
- Use one of the following techniques for creating the breadcrumbs and fulfill the requirements of that technique:
- Navigating through pages of the model (see About navigating through model pages)
- Navigating through data (see About navigating through data and Advanced navigation through data)
- Assign a common named element to a location on all the pages on which breadcrumbs appear and include those pages in the model.
You can have a single page that contains the breadcrumbs, and use the Inserted Page builder to show the page. Or you can have the breadcrumbs control be on each page in the model.
Note: The pages that contain the breadcrumbs control do not have to be in the list of pages that participate in the breadcrumbs.
About navigating through model pages
In this technique, you use breadcrumbs so that the users can see how they arrived at the current page and can easily return to a previously visited page. For this technique, the selector is simply the name of the page. The preparePage method is not required to perform any other action to prepare the page. The key is the name of the model page.
If you leave the entry for the Prepare Page Method input blank, a default method is created that takes the name of the page as the name of the action to run and no preparations are done. This default method works very well if your application consists of multiple model pages that users visit.
For the Get Text Method input, specify the text that is displayed for the breadcrumbs element in the list. If you leave this input blank, the name of the method that returns the key is displayed to describe the link to that page. This input lets you supply more readable names for the pages. You can use a Localized Resource builder that includes page names as the keys and readable names as the values. The Localized Resource builder has an advanced input that creates a method that you can specify in the Get Text Method input of this builder. Alternatively, you can write a method that uses conditional statements to return the correct readable name for each possible page name.
About navigating through data
Another common use for breadcrumbs helps users save their places as they navigate through data, for example, the categories and groups within an online catalog. In the technique for implementing this use, perhaps only a single page in a model is ever displayed. However, each breadcrumb has different data (probably from a database query or a service) with which it is currently associated. For example, one breadcrumb can be associated with sporting goods, and another with basketball equipment; but the same page in the model actually displays either of these breadcrumbs.
The following are the considerations in using this technique:
- Use a unique selector or key.
Each selector value is associated with a new breadcrumb. Typically, the value is a database key or an identification that is passed to a data service which fetches the data associated with that breadcrumb element. The model perhaps has only a single page that is used to display the current breadcrumb element. The page simply has different data to display each time. The different breadcrumbs represent the user navigating through data by means of links or buttons.
- Write a preparePage method that accepts an object (the unique key) and returns a string.
This method performs whatever database calls are necessary to load the data that is associated with that value of the unique key. The method should return a string that is the action in the model to call to display the data. In its simplest form, the returned string is always the same value, that is, the name of the page in the model that displays a batch of data.
To use different model pages, use advanced techniques (see Advanced navigation through data).
- Optionally write a getText method to specify the text that is displayed for the breadcrumbs element in the list. Specify this method in the Get Text Method input of this builder.
The method accepts as input an object (the selector or key) and returns a string that is to be displayed for the selected element in the breadcrumbs control. The linked Java object (LJO) that is created by the builder (called the breadcrumbs assistant) keeps this data in a cache and requests one from the database only if there is no cached value.
If you create your model to support multiple languages, use the Localized Resource builder to load the resource bundle information. If you select the advanced input in the Localized Resource builder, construct a method to specify for the Breadcrumbs builder input.
Note: The text that is returned can contain HTML coding. For example, to return an image rather than text links, the method can return coding similar to the following:
<img url="/images/category12.jpg"> </img>- Add the Breadcrumbs builder to your model after you write your methods.
Use the indicated builder inputs to specify your methods.
- Indicate at which location the breadcrumbs are to be displayed for the users.
In the Tag On Pages input, indicate the location on which all pages in the model display the breadcrumbs. You can confine the display to a single wrapper page or have many different pages on which the breadcrumbs are displayed. It is best practice to display the breadcrumbs in the same location in every page.
If only selected pages are to display the breadcrumbs, ensure that you omit the tag from the other pages.
Advanced navigation through data
If the model navigates through data (see About navigating through data), you can have different model pages display different types of data, for example, one for major categories, another for groups of items, and another for individual items. This technique is supported by having the preparePage method return different actions depending on the type of breadcrumb element being displayed. For example, all major categories can be displayed using MyCategoryPage, all groups of items with MyGroupPage, and all individual items with MyItemPage.
To implement this technique, modify the preparePage method to do the following processing:
- From the unique key, identify which type of element is involved.
- Fetch the data that is associated with the unique key.
- Return one of several different strings depending on the type of data selected by the unique key. For example, MyCategoryPage, MyGroupPage, or MyItemPage.
A data provider class
Sometimes a simple string is not adequate as a key to identify data. For the model to be efficient, it might need to cache more information, possibly the entire set of data. However, when the breadcrumbs links are created, a string is still required to represent the breadcrumb element that the user clicks. This string might be temporary, and last as long as a breadcrumb is active. But it must be a string to be able to be encoded in the URL in the link. This mode of operation requires that you create a DataProvider class.
The following requirements must be met:
- The Java class must implement the following interface:
com.bowstreet.builders.webapp.methods.BreadcrumbsDataProvider- The class must implement the following methods defined by the interface:
- preparePage and getText
These methods are described in About navigating through data and Advanced navigation through data.
- Two methods that convert a selector to a key and a key to a selector.
The selector is always a string. This value is put into the link to be submitted when the users clicks the breadcrumb element and must select a specific page in the model.
The key can be anything, for example, a block of XML code, a RowSet, an instance of a class that you devise. However, the keys must implement the equals and hashcode methods because they are used in a hashmap.
There has to be a clear one-to-one mapping of selectors to keys.
The Breadcrumbs builder creates the method that instantiates your DataProvider instance. The constructor that the builder invokes can be one of the following forms:
- Takes zero arguments
Use this if you left the preparePage and getText inputs blank.
- Takes two arguments
The arguments are the two strings that you specify in the preparePage and getText inputs.
Specify this class in the Data Provider Class Name input of the builder.
Set the Use Empty Constructor input to specify which constructor is invoked.
Parent topic: Builder help
- About using the builder call editor
The builder call editor allows you to specify all the input values to a builder call.
- Breadcrumbs builder inputs
This topic describes the inputs for the Breadcrumbs builder.
- Objects that the Breadcrumbs builder creates
The Breadcrumbs builder creates a variety of objects within the WebApp.
- Inserted Page builder
Use the Inserted Page builder to insert the contents of an imported page into a named location in the specified pages.
- Localized Resource builder
The Localized Resource builder imports the contents of a resource bundle into a variable in the model.
- Repeated Region builder
Use the Repeated Region builder to repeat part of an HTML page.
Library | Support |