4. Portlet implementation

4.1. Introduction

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.

4.2. Portlet Application

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.

4.3. Portletdescriptor

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.

4.4. Gentics Portletdescriptor

4.4.1. Introduction

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]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>
					

4.4.2. Configuration

Table 4.154. Configuration parameters in the Gentics Portletdescriptor

NameTypeDescription
portlet-appStructureBase node of the file. Note that the namespace declaration is needed.
portletStructureDefines additional settings for a portlet. Not every portlet defined in the Portletdescriptor needs to have extensions defined here.
portlet-nameStringName of the portlet like defined in the Portletdescriptor.
parameter-descriptionStructureDescription of parameters a portlet uses.
parameter-definitionNodeDefinition of a single portlet parameter.
parameter-definition.nameStringName of the portlet parameter.
parameter-definition.typeStringType of the portlet parameter. Must be one of string, integer, boolean, rule, node, listOfObjects .
start-parametersStructureDefinition of the default values for parameters.
parameterNodeDefault value for a parameter. The exact format and interpretation of the value depends on the parameter type.
parameter.nameStringName of the parameter.
templatesStructureDefinition 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-preferencesStructureAdditional configuration settings regarding the portlet preferences.
portlet-preferences.preferences-modifierStringClass 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.
pluginStructureDefinition of a plugin.
plugin-nameStringName of the plugin.
plugin-classStringFull 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-descriptionStructureSee above.
templatesStructureSee above.

4.5. Portlet Cache

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]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.

4.5.1. Portlet Cache Behaviour

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]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.