This section covers information needed during implementation of portlets. The portlets themselfes are described in the section Chapter 5, Portlets.
Further information about portlets, portlet applications and the portlet descriptor can be found in the JSR 168 Portlet Specification.
A portlet application bundles several portlets together with other resources, such as templates, view definition files, images, dictionaries, etc.
Portlet applications can be developed in the Gentics Portal.Node SDK and then deployed onto a production system using the AdministrationPortlet. For details on the deployment, see Section 7, “AdministrationPortlet”.
Every portlet application provides a portlet application template loader with
the
loaderid
gentics.portletapp
. This loader loads the templates from the directory
/WEB-INF/templates
within the portlet application's context path. When templates are bundled with a
portlet application, it is strongly recommended to locate them in files under
the directory
/WEB-INF/templates
and to use this portlet application loader.
The portlet application's dictionaries must be located at
/WEB-INF/dictionaries/portal.[languageid].property
. See
“Dictionaries” (Section 8.5.3)
for details.
The Portletdescriptor is used to define the portlets, that are part of a portlet application. It follows strictly the standard defined in the JSR 168 Portlet Specification.
The Gentics Portletdescriptor is used to configure specific
extended settings of portlets and plugins. It consists of the file
WEB-INF/gentics-portlet.xml
.
![]() | Note |
---|---|
It is not necessary to define the default plugins in the Gentics Portletdescriptor of every portlet application. The default plugins are automatically available to all deployed portlet applications. Only when default settings (e.g. the templates) shall be overwritten for the plugins in a specific portlet application, you need to redefine this plugin in the portlet application. |
Example 4.40. Syntax of the Gentics Portletdescriptor
<portlet-app xmlns="http://www.gentics.com/gentics-portlet-app"> <portlet> <portlet-name>...</portlet-name> <parameter-description> <parameter-definition type="..." name="...">...</parameter-definition> </parameter-description> <start-parameters> <parameter name="...">...</parameter> ... </start-parameters> <templates> ... </templates> <portlet-preferences> <preferences-modifier></preferences-modifier> </portlet-preferences> </portlet> ... <plugin> <plugin-name>...</plugin-name> <plugin-class>...</plugin-class> <parameter-description> <parameter-definition type="..." name="..."/> </parameter-description> <templates> ... </templates> </plugin> ... </portlet-app>
Table 4.154. Configuration parameters in the Gentics Portletdescriptor
Name | Type | Description |
---|---|---|
portlet-app | Structure | Base node of the file. Note that the namespace declaration is needed. |
portlet | Structure | Defines additional settings for a portlet. Not every portlet defined in the Portletdescriptor needs to have extensions defined here. |
portlet-name | String | Name of the portlet like defined in the Portletdescriptor. |
parameter-description | Structure | Description of parameters a portlet uses. |
parameter-definition | Node | Definition of a single portlet parameter. |
parameter-definition.name | String | Name of the portlet parameter. |
parameter-definition.type | String | Type of the portlet parameter. Must be one of
string ,
integer ,
boolean ,
rule ,
node ,
listOfObjects
. |
start-parameters | Structure | Definition of the default values for parameters. |
parameter | Node | Default value for a parameter. The exact format and interpretation of the value depends on the parameter type. |
parameter.name | String | Name of the parameter. |
templates | Structure | Definition of portlet templates. See Section 8.7.4, “Template definitions” on details about definition of templates. You might also want to take a look at Section 8.7.3, “Template Loaders” for detailed information on Template Loaders. |
portlet-preferences | Structure | Additional configuration settings regarding the portlet preferences. |
portlet-preferences.preferences-modifier | String | Class name of a preferences modifier. A preferences modifier is a class that may modify portlet preferences before a portlet handles an action or renders its output. This can for example be used to modify the behaviour of a third party portlet, that relies on portlet preferences. |
plugin | Structure | Definition of a plugin. |
plugin-name | String | Name of the plugin. |
plugin-class | String | Full qualified classname of the Java Class
that implements the functionality of the
plugin. The class must implement the interface
com.gentics.api.portalnode.plugin.GenticsPlugin
and is recommended to extend
com.gentics.api.portalnode.plugin.AbstractGenticsPlugin
. |
parameter-description | Structure | See above. |
templates | Structure | See above. |
The Portlet Cache can be used to let Gentics Portal.Node cache the render output of a Portlet. This can lead to drastic performance improvements.
To activate the Portlet Cache for a specific Portlet you have to modify the Portlet Descriptor portlet.xml
and add a <expiration-cache> setting (after <portlet-class>) - This defines the maximum number of seconds the output should be cached. You can disable caching by specifying 0 or use -1 if you don't want the cache to expire.
Example 4.41. Portlet Cache Configuration Example
This example would enable the Portal to cache the render output of this portlet for 10 seconds.
<portlet> <portlet-name>HelloCachedWorld</portlet-name> <portlet-class>com.gentics.HelloWorld</portlet-class> <expiration-cache>10</expiration-cache> ... </portlet>
![]() | Note |
---|---|
To use the Portlet Cache it also has to be activated in the Portal Configuration. See “Portlet Cache” (Section 8.2.7) for more information. |
Before making use of the Portlet Cache you should have a basic understanding on how it works and when the cache is cleared.
According to the Portlet Specification (JSR 168) the render output of a Portlet is cached (and therefore it's render() method not called) as long as the Expiration Cache has not expired and no action or render request was targeted at the specific Portlet.
In addition to this definition Gentics Portal.Node will invalidate the cache of a Portlet if any property setters are invoked. This way you can e.g. set properties of any portlet in a Reaction of “PNodes” (Section 11.1.3) or within a “GeneralViewAction” (Section 2.2.8.14) without having to worry about caching.
![]() | Warning |
---|---|
When using Portlet Caching you need to make sure that your portlet has no outside dependencies. This means you should not reference anywhere within your portlet (e.g. in your views or visible rule of the pnode) to properties outside of your own portlet. Instead, always use “Property Setters” (Section 7) if the state of your portlet should change. |