Work with friendly URLs for web content
With friendly URLs for web content, you can construct URLs to content items that are clear and concise, making the URLs easier for users to remember and share. Friendly URLs for web content are a convenient way for users to create bookmarks to content items or for external applications to provide links directly to content items in the portal. To ensure that you create friendly URLs for web content effectively, it is important to understand how friendly URLs for portal pages are constructed and how friendly URLs for web content extend the portal friendly URLs.
How friendly URLs for pages work
For a page to be referenced as part of a friendly URL, assign a friendly URL name for the page. You can do this when you create the page, or you can use Manage Pages to edit the page properties after the page is created.Friendly URLs take the following general form:
http://host_name:port_number/context_root/portal/page_id/ [!ut/p/encoded_suffix]
The page_id portion of the friendly URL is made up of the friendly URL names of each page in the page structure from the content root to the currently selected page.
For example, you might have a portal page called Products with a friendly URL name of products, and underneath the Products page is another page called Appliances with a friendly URL name of appliances. When referenced as a complete friendly URL, you would enter the following URL to access the Appliances page:
http://www.example.com:10039/wps/portal/products/appliances
For friendly URLs to work for a specific page, define a friendly URL name for each page or label in the page hierarchy from the specific page back up to the content root. To suppress a friendly URL name from appearing in the friendly URL, you can specify a friendly URL name of com.ibm.portal.friendly.wildcard for the page. For example, if the Products page has a friendly URL name of com.ibm.portal.friendly.wildcard, the friendly URL above for the Appliances page is abbreviated:
http://www.example.com:10039/wps/portal/appliances
When the portal displays a page using a friendly URL, the URL might also include an encoded suffix at the end of the URL that takes this form: !ut/p/base_codec/rich_state. This suffix contains information about the portal's state that the portal might use when displaying the page. However, when bookmarking or sharing friendly URLs, it is not necessary to include the suffix.
How friendly URLs for web content work
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 left to right, matching each path segment of the URL to the friendly URL names of portal pages until it can no longer find a match. The remainder of the URL is then considered to be path information to a content item and 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 that are concatenated using a forward slash (/) as a path separator.Friendly URLs for web content take the following general form:
http://host_name:port_number/context_root/portal/page_id/path_to_content/ [!ut/p/encoded_suffix]
When you add a JSR 286 web content viewer to a portal page, the web content viewer reads the path-info parameter and assembles the path to the content to be rendered by appending the path information to the content mapping defined for the current page. For example, you might have the following friendly URL for web content:
http://www.example.com:10039/wps/portal/products/appliances/welcome
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 contains a content mapping to the Web Content/Appliances site area.
When a JSR 286 web content viewer is added to the Appliances page, the web content viewer interprets the path-info information from the friendly URL and identifies welcome as path information that represents content in a web content library. By examining the content mapping on the page, the web content viewer locates the Web Content/Appliances site area and then displays the site area's default content, which is the welcome content item.
When setting up the portal page hierarchy and web content hierarchy, ensure that naming schemes for each do not overlap in such a way that the path_to_content information starts with segments that could be part of the page_id portion of the friendly URL. Because the page_id portion of the friendly URL is always evaluated first, the friendly URL could inadvertently point to the wrong page, 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.
Considerations for the path-info parameter:
- For a web content viewer to process the path-info parameter, the web content viewer must be configured to receive links. If configured to receive links, the JSR 286 web content viewer gives precedence to the path-info parameter over the context public render parameter, which can also be used to set a web content item to be displayed by the web content viewer. 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, but 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. Similarly, if there is a mismatch between the path-info contents and the path information encoded in the rich_state section, the portal replaces the path_to_content portion of the friendly URL with the rich_state information and directs the user to that page.
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 browser's 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, and 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 browser's 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, and the user is directed to the page where content_item_2 is displayed.
Troubleshooting friendly URLs for web content
If you are seeing unexpected behavior when using friendly URLs for web content, review these issues to help identify why the friendly URL is not working:
- Support for friendly URLs for web content requires that the values for the configuration properties friendly.enabled and friendly.pathinfo.enabled be set to true in the portal Configuration Service.
- If the friendly URL for web content references a content item that cannot be located or if the user does not have sufficient access rights to view the content item, the JSR 286 web content viewer displays a warning.
- If the portal page specified in the friendly URL for web content is not mapped to an existing web content folder or site area, any JSR 286 web content viewers on that page display a warning message about the missing page context.
- If the target portal page does not contain a JSR 286 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 JSR 286 web content viewer is not configured to broadcast links, web content 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 the user begins to browse the web content using links displayed by the JSR 286 web content viewer.
- Friendly URLs for web content are URL-encoded. When using friendly URLs for web content, special characters that appear 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, so 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 will be constructed of these English terms, even if the portal language is set to a language other than English.
Parent
Friendly URLs and web content viewersRelated
Coordination with other JSR 286 portlets
December 14, 2011
Apr 1, 2011 1:26:17 PM
});