About friendly URLs for web content
With friendly URLs for web content, you can construct URLs to content items that are clear and concise. Although you can construct friendly URLs that reference web content items, IBM® Web Content Manager itself does not generate friendly URLs by default. However, to cause the web content viewer to generate friendly URLs, you can create a plug-in that implements a content URL generation filter.
These URLs are easier for users to remember and share and are a convenient way for users to create bookmarks to content items. External applications can also use friendly URLs to provide links directly to content items in the portal. To create effective friendly URLs for web content, you must understand how friendly URLs for portal pages are constructed and how friendly URLs for web content extend those URLs.
How friendly URLs for pages are constructed
For a page to be referenced as part of a friendly URL, you must assign a friendly URL name for the page. You can assign a friendly URL when you create the page, or you can edit the page properties after the page is created.
The page_id portion of the friendly URL is made up of the friendly URL names of each page in the page structure. The page structure begins at the content root and ends with the currently selected page.
How friendly URLs for web content are constructed
Friendly URLs for web content are constructed just as friendly URLs for pages but include additional information that identifies the path to a content item. When the portal decodes a friendly URL, it decodes the URL from beginning to end. Each path segment of the URL is matched with the friendly URL names of portal pages until no more matches can be located. The remainder of the URL is then considered to be path information to a content item.
This path information is mapped to a shared public render parameter that is scoped to the portal page identified by the URL. The fully qualified name of this path-info parameter is http://www.ibm.com/xmlns/prod/websphere/portal/publicparams:path-info. The path-info parameter can contain multiple values, with the individual values representing segments of a content path. The segments are concatenated using a forward slash (/) as a path separator.
Several conditions contribute to this URL:
- The portal page Products has a friendly URL name of products, and underneath the Products page is another page called Appliances with a friendly URL name of appliances.
- A web content library contains a site area called Appliances, which contains a content item called welcome. For this example, the web content library is called Web Content.
- The portal page Appliances has a default content mapping to the Web Content/Appliances site area.
The page_id portion of the friendly URL is always evaluated first. Because of this priority, ensure that your naming schemes do not overlap when setting up your portal page hierarchy and your web content hierarchy. In particular, the path_to_content information cannot begin with segments that could be part of the page_id portion of the friendly URL. If the first segment of the path_to_content information matches the friendly URL name of a portal page at that point in the page hierarchy, the friendly URL could reference the wrong page.
- For a web content viewer to process the path-info parameter, the web content viewer must be configured to receive links. If it is configured to receive links, the web content viewer gives precedence to the path-info parameter over the context public render parameter. When you click links displayed by the web content viewer, the link automatically incorporates the path information for the linked item.
- Clicking Clear page context when editing the settings of a web content viewer also clears the path-info parameter.
- If a friendly URL includes an encoded suffix, it takes this form: !ut/p/base_codec/rich_state.
Because this information is encoded, it is not intended to be read
by people. However, the portal itself might act on the information,
which can sometimes cause the wrong page to be displayed.
If the path-info public shared render parameter is encoded in the rich_state portion of the suffix, the path-info contents overwrites the path_to_content portion of the friendly URL. It is also possible that there could be a mismatch between the path-info contents and the path information encoded in the rich_state section. If such a mismatch occurs, the portal replaces the path_to_content portion of the friendly URL with the rich_state information and directs the user to that page.The following tables demonstrate how the presence of rich_state information affects the page that is shown:
Table 1. Example of rich_state information affecting displayed page Description URL The user navigates to URL in the portal. http://www.example.com:10039/wps/portal/home/content_item_1/!ut/p/b1/dY07Do... The user modifies the URL in the browsers address bar to go to content_item_2. http://www.example.com:10039/wps/portal/home/content_item_2/!ut/p/b1/dY07Do... Resulting URL. http://www.example.com:10039/wps/portal/home/content_item_1/!ut/p/b1/dY07Do...
Because the rich_state portion of the URL still contains path information pointing to content_item_1, the portal overwrites the path_to_content portion of the URL. The user remains on the same page instead of being directed to the page where content_item_2 is displayed.
Table 2. Example of friendly URL for web content without rich_state information Description URL The user navigates to URL in the portal. http://www.example.com:10039/wps/portal/home/content_item_1/!ut/p/b1/dY07Do... The user modifies the URL in the browsers address bar to go to content_item_2. http://www.example.com:10039/wps/portal/home/content_item_2 Resulting URL. http://www.example.com:10039/wps/portal/home/content_item_2
Because the user removed the rich_state portion of the URL when modifying the URL, the path_to_content portion of the URL is evaluated. The user is directed to the page where content_item_2 is displayed.
Content URL generation filters and friendly URLs
A content URL generation filter is used to customize the URLs that are generated by a web content viewer. The web content viewer generates a content URL whenever there is a URL to web content within content that the viewer is displaying. By creating a plug-in that implements a content URL generation filter, you can tailor the URLs to content items. For details, see Creating a content URL generation filter class.
Troubleshooting friendly URLs for web content
- Support for friendly URLs for web content is only enabled when the configuration properties friendly.enabled and friendly.pathinfo.enabled both have a value of true in the portal Configuration Service.
- The web content viewer displays a warning message in the following
- The friendly URL for web content references a content item that cannot be located.
- The user does not have sufficient access rights to view the referenced content item.
- The portal page specified in the friendly URL for web content must have a default content mapping to an existing web content site area. If there is no default content mapping on the page, any web content viewers on the page display a warning message about the missing page context.
- If the target page does not contain a web content viewer that is configured to receive links, the content item specified in the friendly URL for web content is not displayed.
- If a web content viewer is not configured to broadcast links, links rendered by the viewer do not affect the friendly URL for web content.
- The default portal page selection does not show the path of the default content item in the friendly URL. The path_to_content portion of the URL includes the content path information only after users browse web content using links displayed by the viewer.
- Friendly URLs for web content are URL-encoded. When using friendly URLs for web content, special characters that show in any segment of the URL must be URL-encoded. For example, a space character in the URL would be replaced by its URL-encoded equivalent: %20. Some web browsers perform automatic decoding of the URL. In this case, you might see unencoded characters in the URL, but the portal always works with an encoded version of the URL.
- The segments of a friendly URL for web content are not localized for multiple languages. The path_to_content portion of a friendly URL for web content is composed of the unlocalized names of web content folders, site areas, and content items. For example, if you name these items with English terms, the friendly URL for web content is constructed of these English terms, even if the portal language is not English.