You can request a portlet directly through a Uniform Resource
Locator (URL) to display its content without portal aggregation. The
PortletServingServlet servlet registers each web application that
contains portlets. It is similar to the FileServingServlet servlet
of the web container that serves resources. The PortletServingServlet
servlet supports direct rendering of portlets into a full browser
page by a URL request.
You can invoke each portlet by its context root and name with the
URL mapping
/<portlet-name> that is created
for each portlet. For example:
http://<host>:<port>/<context-root>/<portlet-name> For example,
http://localhost:9080/portlets/TestPortlet1
The context
root identifies the web application archive (WAR) file that contains
the portlet. The portlet name uniquely identifies the portlet with
a portlet application of a WAR file. The DefaultDocumentFilter servlet
only supports HTML, UTF8 encoding and an extended URL form based on
the basic URL form as shown above.
You can only display one portlet at a time using the PortletServingServlet
servlet. If you want to aggregate multiple portlets on the page, you
need to use the aggregation tag library. Refer to the Portlet aggregation
using JavaServer Pages article for additional information.
Because a portlet only delivers fragment output whereas a servlet
usually delivers document output, a mechanism is introduced to convert
the fragment into a document, called the PortletDocumentFilter filter.
By default, the PortletDocumentFilter filter only supports converting
HTML. The conversion is implemented using a servlet filter before
the PortletServingServlet servlet is initiated to return the portlet‘s
content inside of a document. This default document servlet filter
only applies to URL requests, not for includes or forwards using the
RequestDispatcher method. You can create servlet filters to support
other markups additional document servlet filters. Refer to the Converting
portlet fragments to an HTML document article, for additional information.
The PortletServingServlet servlet does not persist portlet preferences
in a XML file or database. It places the portlet preferences directly
into a cookie to store the preferences persistently. Refer to the
Portlet preferences article, for additional information on how to
change this behavior.
Portlet URL syntax
You can add additional
portal context such as portlet mode or window state. You can access
the PortletServingServlet servlet by using a URL mapping that has
the following structure:
http://host:port/context/portlet-name [/portletwindow[/ver [/action |
/resource[/id=custom-id][/cacheability]] [/mode] [/state] [rparam][/?name]]]
Any
differing URL structure results in a com.ibm.wsspi.portletcontainer.InvalidURLException
exception. Empty strings are not permitted as parameter values and
creates an InvalidURLException exception. The following is a list
of valid parameters:
- http:// host:port/context/portlet-name
- This is the minimum URL required to access a portlet. A default
portlet window called "default" is created. The portlet-name variable
is case-sensitive.
- /portletwindow
- This parameter identifies the portlet window. You must set this
parameter if you choose to add more portal context information to
the URL.
- /ver=major.minor
- This optional parameter is used to define the version of the portlet
API that is used. You must set this parameter if you choose to add
more portal context information to the URL. Only versions "1.0" and "2.0" are
supported. Any other version creates an InvalidURLException exception.
- /action
- This is a required parameter if you call the action method of
the portlet. The action parameter causes the action process of the
portlet to be called. After the action has been completed, a redirect
is automatically issued to call the render process. To control the
subsequent render process, a document servlet filter can set a request
attribute with name "com.ibm.websphere.portlet.action" and value "redirect" to
specify that the portlet serving servlet directly returns after action
without calling the render process.
- /mode=view | edit | help | custom-mode
- This optional parameter defines the portlet mode that is used
to render the portlet. The default mode is "view". The value
is not case-sensitive. For example, "Vew", "view" or "VIEW" results
in the same mode.
- /state=normal | maximized | minimized | custom-state
- This optional parameter defines the window state that is used
to render the portlet. The default state is "normal". The value
is not case-sensitive, for example, "Normal", "normal",
or "NORMAL" results in the same state.
- * [ /rparam=name *[=value]
]
- This optional parameter specifies render parameters for the portlet.
Repeat this parameter chain to provide more than one render parameter.
For example, /rparam=invitation/rparam=days=Monday=Tuesday.
- ?name=value&name2=value2 …
- Query parameters may follow optionally. They are not explicitly
supported by the portlet container, but they do not invalidate the
URL format.
- /action | /resource
- This parameter defines the methods of the portlet that is called.
Valid values are no, action or resource parameter. No specific method
defined calls the render method. The resource parameter is only supported
for JSR 286 portlets.
- /resource [/id=custom-id] [/cacheability=cacheLevelFull | cacheLevelPortlet
| cacheLevelPage]
- Set this parameter to define the method of the portlet to be called.
No redirection occurs. No other method of the portlet is called. To
control the resource parameter, you can add an additional ID parameter
to provide a resource serving identifier that is passed through to
the portlet. The cacheability parameter defines the cache level of
this resource URL. This parameter is only supported with JSR 286 portlets
.
![[IBM i]](../images/iseries.gif)
The following list includes examples
of valid JSR 168 and JSR 286 URLs:
- http:// your.server.name:9080/sample/WorldClock
- http:// your.server.name:9080/sample/WorldClock/myPortlet/ver=1.0/mode=edit/rparam=timezone=UTC
- http:// your.server.name:9080/sample/WorldClock/myPortlet/ver=1.0/action/state=maximized?timezone=UTC
- http://your.server.name:9080/sample/WorldClock/myPortlet/ver=2.0/resource/id=somePicture.jpg