URL generation in HCL Portal | HCL Digital Experience
Generating Portal URLs correctly is one of the most important tasks in programming an HCL Portal based application. There are several programming tools and techniques available for generating HCL Portal URLs in custom code. The following section introduces the programming tools available and discusses when it is most appropriate to use each of the tools.
Types of Portal Urls
- Render URLs
- This type of URL is used for retrieving a general view of a Portal page. It specifically does not include any portlet actions or cause any server-side state changes. A Render URL corresponds to an HTTP GET operation and is idempotent, that is, it can be run more than once without any harm. Normal HCL Portal page navigation is made up of render URLs.
- Action URLs
- Action URLs are used for activities within portlets. The URLs correspond to HTTP POST or PUT and are often non-idempotent, meaning they must be run at most once. An Action URL typically targets a specific portlet, and might cause server-side state changes. The portlet action and the portlet at which the action is targeted are carried as parameters within the Navigation State document.
- Friendly URLs
- Friendly URLs have human-readable strings in the URL that describe
the path to a Portal page. These human-readable strings correspond
to the Friendly URL Names that are associated with the pages or labels.
In addition, there might also be Friendly Content Path tokens in the
URL. The Friendly Content Path tokens are human-readable strings that
describe the site area path to Web Content Management library associated
with the page. Note: A friendly URL might also include an encoded Navigational State document. If it does not, it is a Stateless Friendly URL. There is a programming API specifically for working with Friendly URLs.
- Vanity URLs
- Vanity URLs are similar to Stateless Friendly URLs, in that they are human-readable and do not have an encoded Navigational State document. However, Vanity URLs are not tied to the Friendly URL Names associated with the Portal pages. Instead, Vanity URLs are intended to be aliases that are simple, easily remembered, and easily entered by hand if necessary. Vanity URLs are similar to Mapped URLs that were introduced in prior releases of HCL Portal. They are intended only as an initial entry point, and are not persistent in the browser address bar after interaction with the Portal site begins. There is a programming API specifically for working with Vanity URLs.
- Piece-of-Content URLs
- Piece-of-content URLs or PoC URLs are late binding mechanism that targets content instead of Portal artifacts such as pages. They use a different URL entry point into HCL Portal (typically mypoc or mycontenthandler instead of myportal). A programming API is available for working with Piece-of-Content URLs.
Methods for generating portal URLs
The complexity of a HCL Portal URL makes them difficult to hand-code, therefore do not try to build Portal URLs by string concatenation. The design intention is that most self-referential URLs in Portal are generated in code at run time to avoid broken links and to avoid manually maintaining links within a Portal-based site.
- Portal JSP tags method is used in Theme and Skin JSPs.
- JSR 286 Portlet API and corresponding JSP tags. This method of URL generation addresses almost
all URL generation requirements within a standard portlet.
- Or if necessary when you modify an existing portlet, and upgrading is not a possibility, the older JSR 168 Portlet API is used.
- The HCL Portlet API is no longer supported. Older portlets that are written to this API must be migrated to the current standard.
- HCL Portal defined public render parameters. This method can support many use cases that previously required the use of the Navigational State API.
- Friendly URL API method is specifically for use cases that involve Friendly URLs, including URLs that must be stateless (have no encoded Navigational State document).
- PoC URL API method is specifically for creating Piece-of-Content URLs.
- Vanity URL API method is specifically for working with Vanity URLs.
- Navigational State API method is the most full-featured and general programming tool for URL generation, but requires the most in-depth understanding and programming skill.
When you create cooperating portlets that require inter-portlet communication, the inter-portlet messaging might be carried in the URLs that are generated. Render parameters as supported by JSR 286 are one way of accomplishing this, but additional programming tools are also provided. JSR 286 techniques for cooperative portlets, and the additional tools are described in more detail in the Portlet communication section. One example of such a tool is the Cooperative Portlet API for interoperability between JSR 286 and JSR 168 portlets.
Task (Simplest to most Complex) | URL Generation Method |
---|---|
Creating page navigation links between Portal pages at the theme level. For example, standard tabbed pages navigation. |
These URLs are typically simple render URLs. In JSPs, use the <portal-navigation/> JSP tags. For more information about programming a Portal theme, see Developing Themes and Skins section. |
A JSR 286 portlet, self-contained (no inter-portlet communication required), generating action URLs to itself and setting its own render parameters. |
|
A JSR 286 portlet, which requires inter-portlet communication with another JSR 286 portlet, but no page navigation (Portal view remains on the current page). |
It might be sufficient to use the JSR 286 render parameter support. However, other techniques also exist. For more information, see the Portlet communication section. |
A JSR 286 portlet, which needs to interoperate with a JSR 168 portlet. |
A JSR168 portlet that worked with other portlets through inter-portlet communication is written to use the Cooperative Portlet API, also known as the Property broker. The Property broker was an HCL extension to the JSR 168 specification. JSR286 introduced the portlet event model, which superseded the Property Broker. JSR286 portlets and JSR 168 portlets can interoperate if certain conditions are met. For more information, see the Interoperability between JSR 286 portlet events and JSR 168 cooperative portlets section. |
A JSR 286 portlet, which needs to
|
Starting with Portal
8.5 CF05 use the HCL Portal-defined public render parameters
for all of these use cases, and more. These render parameters make
various aspects of the current request context available as normal
public render parameters in a HCL Portal specified namespace.
Notes:
The namespace of the HCL Portal specified public render
parameter is http://www.ibm.com/xmlns/prod/websphere/portal/publicparams
(available as NAMESPACE_URI). The following items are the special public render parameters that HCL Portal supports:
There also exists a Portal URL Generation Convenience
API. This convenience API supports render URLs only. No state changes
(action URLs) can be generated by using this API. The following items
are the key classes in this API:
An equivalent set of JSP tags for the URL Generation
Convenience API exists. For
more information, see JSP tags for standard portlets.
An example of creating a render URL by using the Convenience API tag
is<portlet-ext:portalRenderURL> . |
Friendly URL |
A Friendly URL also known as a Friendly URL Name is a human-readable
name for a Portal page. It is set as an attribute of the page, and
each page can have at most one Friendly URL. Notes:
To use the Friendly URL API, you need to get
a FriendlyURLFactory instance. Depending
on the type of code you are writing, you can get a FriendlyURLFactory instance
in one of two ways:
After you have a |
Vanity URL |
A Vanity URL is a simple, easy to remember URL that a user can enter by hand. Vanity URLs are managed by the webmaster with the HCL Portal administrative tools, such as the toolbar, administrative portlets, or XMLAccess scripting. However, sometimes when you render a response, it is necessary to produce a Vanity URL link. The following section describes how to use the Vanity URL API to obtain a VanityURLNode , which can be used to render a Vanity URL link. Depending on the type of
code package you are developing, use one of the 3 different ways to access and use the Vanity URL
API. Note: Be careful to select the correct SPI package for the code that is being developed.
The necessary interface documentation is in the HCL Portal SPI javadoc.
VanityURLNode instance through any of the
appropriate ways, you can call the various methods of that interface to build a rendered
representation of the VanityURL:
|
Create, update, or delete Vanity URLs. |
If you are writing code, which is intended to create, update,
or delete Vanity URLs, rather than read and render them, use the following
APIs:
|
A JSR 286 portlet, which needs to generate an action URL to a second specific portlet, or any other use case that is not listed here. |
Navigational State API |
Piece-of-Content URL |
A Piece-of-Content or POC URL is a URL that targets a DataSource or a ResolutionService within the Resolver framework. Given such a DataSource or ResolutionService, the PoC URL API assists the programmer to create a URL that results in the Resolver framework to start the correct DataSource or ResolutionService. To work with Piece-of-Content
URLs, obtain an instance of a com.ibm.portal.resolver.acessors.url.PocURLFactory.
Much like other URL APIs, the code for obtaining an instance of a
URLFactory depends on whether you are writing a portlet, theme code,
or if you are already running a code within the resolver framework.
After you obtain a PocURLFactory :
|