|
4.12.2 portlet.xml
The portlet.xml elements are defined by the portlet_1.1.dtd which can be found in the WebSphere\PortalServer\app\wps.ear\wps.war\dtd directory. Figure 4-40 displays a simple portlet.xml.
Example 4-40 portlet.xml deployment descriptor
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE portlet-app-def PUBLIC "-//IBM//DTD Portlet Application 1.1//EN" "portlet_1.1.dtd">
<portlet-app-def>
<portlet-app uid="DCE:d798f9c6c:1" major-version="2" minor-version="1">
<portlet-app-name>HelloWorld application</portlet-app-name>
<portlet id="HWPortlet_1" href="WEB-INF/web.xml#Servlet_1"
major-version="3" minor-version="2">
<portlet-name>HelloWorld portlet</portlet-name>
<cache>
<expires>30</expires>
<shared>yes</shared>
</cache>
<allows>
<maximized/>
<minimized/>
</allows>
<supports>
<markup name="html">
<view output="fragment"/>
<configure/>
<edit/>
<help output="document"/>
</markup>
<markup name="wml">
<view/>
</markup>
</supports>
</portlet>
</portlet-app>
<concrete-portlet-app uid="DCE:d798f9c6c:1.1">
<portlet-app-name>HelloWorld application</portlet-app-name>
<context-param>
<param-name>context_param1</param-name>
<param-value>A context parameter</param-value>
</context-param>
<concrete-portlet href="#HWPortlet_1">
<portlet-name>HelloWorld portlet</portlet-name>
<default-locale>en</default-locale>
<language locale="en">
<title>HelloWorld</title>
<title-short>Hello</title-short>
<description>A simple hello world portlet.</description>
<keywords>Hello World simple</keywords>
</language>
<language locale="it">
<title>ciao mondo</title>
<title-short>ciao</title-short>
<description>Un portlet semplice del mondo di ciao.
</description>
<keywords>Ciao mondo semplice.</keywords>
</language>
<language locale="es">
<title>hola mundo</title>
</language>
<config-param>
<param-name>config_param1</param-name>
<param-value>A configuration parameter</param-value>
</config-param>
</concrete-portlet>
</concrete-portlet-app>
</portlet-app-def>
| DOCTYPE required
|
This will be the same for each and every portlet.xml deployed. This tag defines the DTD that is to be used when this document is parsed. Only one is allowed.
|
| portlet-app-def required
|
This is the top-level tag which encapsulates all abstract and concrete portlet application definitions. It is required and not more than one is allowed.
|
| portlet-app required
|
This tag is used to define the abstract portlet application. This abstract application will be used as a basis for the concrete portlet applications defined later in the descriptor. Only one portlet-app tag is allowed per portlet.xml and only one portlet.xml is allowed per war file. Therefore, each war file may only deploy a single abstract portlet application.
This ID uniquely identifies this abstract application in the portal server. This ID must unique throughout the entire portal environment. For guidelines on ensuring the ID is unique, refer to UID guidelines. This ID will be used if the portlet application is updated. Once the ID is determined, it should not be changed between iterations. Doing so will cause updates to fail. The ID may contain any combination of letters and characters to maximum length of 255.
An optional tag only used by administrators to track releases; it is not used in the portal. It must be a number and only one is allowed. If this attribute is not supplied, the major-version will always be 0. If this attribute is supplied, the minor-version must also be included or the default value of 0 will be assumed.
An optional tag only used by the administrators to track releases and not used in the portal. Must be a number and only one is allowed. If this attribute is not supplied, the minor version will be 0. If this attribute is supplied, the major-version must also be included or the default value of 0 will be assumed.
|
| portlet-app-name required
|
Only one is allowed. Since only concrete portlet applications are visible in the portal, this name is visible in the portal environment when the full information for the portal application is requested on the Manage Portlet Applications portlet. This name need not be unique.
|
| portlet required
|
One or more of these tags is required. This tag defines the abstract portlets contained in the abstract portlet application. Each portlet tag maps to a single servlet defined in the web.xml. There is a one-to-one relationship between the servlets defined in the web.xml and the abstract portlets defined in the portlet.xml. You may not map two abstract portlets to the same servlet. Therefore, if there are two servlets defined in the web.xml, there will be two abstract portlets defined in the portlet.xml
This ID must be unique within the abstract portlet application only. This ID will be used by the concrete portlets to create a link to the abstract definition. It may be any combination of letters and numbers to a maximum of 64 characters.
This tag creates the link between the abstract portlet and the servlet defined in the web.xml. The link is formatted as in Example 4-41 where Servlet_1 is the ID defined in the <servlet id> tag of the web.xml.
Example 4-41 href syntax
href="WEB-INF/web.xml#Servlet_1"
An optional tag only used by the administrators to track releases. Not used in the portal. Must be a number and only one is allowed. If this attribute is supplied, the minor-version must also be included or the default value of 0 will be assumed.
An optional tag only used by the administrators to track releases. Not used in the portal. Must be a number and only one is allowed. If this attribute is supplied, the major-version must also be included or the default value of 0 will be assumed.
|
| portlet-name required
|
Defines the name of the abstract portlet. This name will only be seen in the show info screen of the Manage Portlet Application portlet, not during normal portlet administration or execution. Must be unique within the abstract portlet application only.
|
| cache optional
|
This tag indicates the type and level of caching this portlet will perform. If this tag is included, it must contain the expires and shared elements. If the cache element is not included, the default values for expires and shared are 0 and no respectively.
|
| expires required
|
Indicates in seconds the when the cached content should be considered expired.
|
-
0 indicates the content immediately expires and should always be refreshed
|
|
-
-1 indicates the content does not expire.The content will not be refreshed once the portlet is initialized.
|
|
-
Any other value measures the cache in seconds.
|
|
| shared required
|
Indicates if the content is to shared among all users or if a cache must be maintained for each user. Use the NO option carefully as a large cache will result. Valid values are yes or no.
|
| allows required
|
This tag indicates the portlet states that are supported by this portlet. The normal state is assumed and may not be unsupported. The other valid values are:
When selected, the portlet will take ownership of the portal screen and other portlets will not be able to return content for inclusion in the portal page. Each portlet on the page will state have the opportunity to execute any listeners it implements, such as PortletPageListener. However, the service method, and by extension doView method of the other portlets will not be executed.
When selected, the portlet will be displayed as a title bar only. Any listeners implemented by the portlet will be executed but the portlet's service, and by extension doView method will not.
|
-
detached, moving, resizing, closed optional
|
Though these are valid values according to the DTD, they have no corresponding support in the portal server. As such, including or omitting them will have no effect at this point.
|
| supports required
|
This element indicate which markup languages this portlet can render its content. It is required and at least one markup may be supported.
|
| markup required
|
This tag provides a definition for a single markup that this portlet will support. Each markup that is to be supported is defined in a markup element.
This attribute identifies the name of the markup defined in this element. Valid strings are html, wml, chtml. If custom markups have been defined, they too would be valid.
|
| view required
|
Indicates that at a minimum, this portlet supports View mode. This is required for all markup types.
This attribute indicates the type of output the portal server should expect from this portlet. Valid values are document and fragment
Document: Not used in V4.1.2
|
|
Fragment: All HTML portlets should use this value.
|
|
| configure optional
|
Indicates this portlet supports the Configure mode. As with the View mode, it may specify as output fragment or document. This tag has no effect on non-html markup types. The developer is required to implement configure support by including a doConfigure method in the portlet. This tag simply instructs the portal server to include the appropriate link on the portlet title bar.
|
| edit optional
|
Indicates this portlet supports the Edit mode. As with the View mode, it may specify as output fragment or document. This tag has no effect on non-html markup types. The developer is required to implement edit support by including a doEdit method in the portlet. This tag simply instructs the portal server to include the appropriate link on the portlet title bar.
|
| help optional
|
Indicates this portlet supports the Help mode. As with the View mode, it may specify as output fragment or document. This tag has no effect on non-html markup types. The developer is required to implement help support by including a doHelp method in the portlet. This tag simply instructs the portal server to include the appropriate link on the portlet title bar.
|
| concrete-portlet-app required
|
This element defines the concrete portlet application to be deployed into the portal server. One or more of these elements are required. This concrete application is based upon the abstract portlet application defined earlier in the portlet.xml. A concrete portlet application is not required to contain all of the portlets defined in the abstract application. However, it may not define more portlets than the abstract application. Each concrete portlet contained in the concrete application maps to one and only one abstract portlet. An abstract portlet may not be mapped twice in the same concrete application.
This uid must be unique throughout the entire portal environment. Refer to 4.12.5, UID guidelines for more information about ensuring UIDs are unique. This UID will be used by the portal server when the portlet is updated or deleted. If the ID changes between iterations, the original concrete application will not be update. Instead, a new concrete application will be installed, resulting in multiple concrete applications. Generally, once the ID has been determined, it should not be changed. The ID may contain any combination of letters and characters to a maximum length of 255.
|
| portlet-app-name required
|
This is the application name that will be used in the portal server. When the war file is deployed, each of the concrete applications will be listed. This is the name that will appear in that list. This name need not be unique in the portlet.xml or the portal server. However, deploying more than one concrete portlet application with the same name may cause some administrative confusion. If two or more applications are deployed with the exact same name, only one will be initially active. The other application must be manually activated. In practice, when there is a one-to-one relationship between the abstract and concrete portlet applications, the application names are often the same. This name may contain any combination of letters and numbers to a maximum length of 255 and only one is allowed per concrete application.
|
| context-param optional
|
This element provides an opportunity to set parameters that will be shared by all concrete portlets defined in the concrete portlet application. These parameters are available in code through the PortletApplicationSettings object. There is no limit on the number of context parameters that may be set. Be aware that these parameters may be changed at runtime by the administrator via the Manage Portlet Applications portlet. For a summary on the various parameters set in the deployment descriptors, see 4.12.3, Parameter summary.
|
| param-name required
|
Indicates the name of the parameter. This name will be seen by the administrator if they decide to work with these parameters at runtime. This is also the name used in code to retrieve the parameter value. The name has a maximum length of 255.
|
| param-value required
|
The value intended to be held by the parameter. This value can be changed at runtime by the administrator. The maximum length of the parameter value is 1048576.
|
| concrete-portlet required
|
This element wraps the definition of the concrete portlet being deployed in this concrete application. Any number of concrete portlets may be deployed, up to the number of abstract portlets defined in the abstract portlet application.
This attribute creates a link between the concrete portlet and the abstract portlet. The syntax dictates that the portlet id defined in the abstract application be prefixed with a # symbol as illustrated in Example 4-42.
Example 4-42 Concrete portlet href
<concrete-portlet href="#HWPortlet_1">
|
| portlet-name required
|
This tag indicates the administrative name of the portlet. This name is not the title of the portlet and will not be seen by the average end user. This name need not be unique in the portlet.xml or the portal server. However, take care to properly name your portlets to prevent confusion. If two or more portlets are deployed in the same portlet.xml with the exact same name, only one will be initially active. The name may be any combination of characters to a maximum length of 255.
|
| default-locale required
|
This element indicates which language is the default language for this concrete portlet alone. This setting will not override the user's preferred locale or locale settings provided by the client browser. If the client's locale cannot be determined, this value is used. Also, if the portlet does not support the locale requested by the user, this default locale is used instead. The value must be a recognized country code including, if appropriate, any variants. This value cannot be changed at runtime by the administrator.
|
| language required
|
At least one language block must be included. Though not required, it is a best practice to ensure that at a minimum, the default locale is implemented in a language block. In practice, a language block should be provided for each language this portlet intends to support. ideally this includes all ten group 1 languages. Only the languages defined in the portlet.xml will be available. Though the strings can be changed, there is no mechanism to add new languages at runtime.
This attribute indicates the locale being defined by this language block. The value must a recognized country code, including any applicable variants.
|
| title required
|
This tag specifies the language specific title of this portlet. This title will be seen in the title bar of the portlet at runtime.This value may be changed at runtime by the administrator. The maximum length of the title is 255 characters.
|
| title-short optional
|
This tag specifies the language specific short title of the portlet. The maximum length of the short title is 128.
|
| description optional
|
This description is used in several places in the portal. For example, in the Edit Layout and Content portlet, the description will display in a hover box over the portlet. The maximum length for the description is 1024 characters.
|
| keywords optional
|
This tag specifies the language specific keywords of the portlet. The maximum length of the keywords is 1024 characters.
|
| config-param optional
|
This element allows parameters to be passed to the concrete portlet. Unlike context and servlet-config parameters, these parameters are not shared between portlets. Any number of portlet-config parameters may be supplied. The values can be changed at runtime by the administrator via the Manage Portlets portlet. These parameters are accessed in code via the PortletSettings object. For a summary on the various parameters set in the deployment descriptors, see Parameter summary.
|
| param-name required
|
Indicates the name of the parameter. This name will be seen by the administrator if they decide to work with these parameters. This is also the name used in code to retrieve the parameter value. The name has a maximum length of 255.
|
| param-value required
|
The value intended to be held by the parameter. This value can be changed at runtime by the administrator. The maximum length of the parameter value is 1048576.
|
