11. Templates

11.1. Portaltemplate

11.1.1. Introduction

The portaltemplate defines the basic layout of the portal page and the portlets that are rendered in the portal page. In most cases, the portaltemplate is a HTML page that is extended by special Gentics Portal.Node3 XML tags. The portaltemplate will be loaded at the start of the portal's webapplication. If changes have been made in the portaltemplate the portal's webapplication has to be restarted.

11.1.2. pportal Tag

The pportal tag contains the styledefintion of the frames that encapsulate the content of the different portlets.

Example 4.53. Syntax of the pportal tag

<pportal>
  <modulestyles default="...">
    <modulestyle id="..." actionstyle="...">
      <framestyle>
        <windowstate>...</windowstate>
        ...
        <frame>...</frame>
      </framestyle>
      ...
    </modulestyle>
    ...
  </modulestyles>
  <actionstyles>
    <actionstyle name="...">
      <actiontemplate>...</actiontemplate>
      <actionseperator>...</actionseperator>

      <action type="...">
        <icon>...</icon>
        <alt>...</alt>
      </action>
      ...
    </actionstyle>
   </actionstyles>
</pportal>
					

Table 4.166. Parameters of the pportal-tag

NameTypeDescription
modulestylesStructureDefinition of the modulestyles.
modulestyles.defaultStringId of the default modulestyle. If not set, the first defined modulestyle will be the default.
modulestyleStructureDefinition of a single modulestyle
modulestyle.idStringId of the modulestyle.
modulestyle.actionstyleStringId of the actionstyle to be used with this modulestyle.
framestyleStructureDefinition of how a portlet frame shall be rendered for specific windowstates. Each modulestyle may contain multiple framestyles (for different windowstates).
framestyle.windowstateStringWindowstate for which this framestyle shall be used. May be one of maximized, normal or minimized. The same framestyle may be used for multiple windowstates (more than one <windowstate>-Node in the framestyle definition).
framestyle.frameStringTemplate for the portlet frame. May contain the following placeholders:
  • <box> content of the portlet window that is rendered by the portlet itself. In windowstate minimized, no portlet content will be rendered at all.

  • <boxtitle> title of the portlet, eventually rendered as >a href=""< when a titleaction is defined for the portlet.

  • <boxaction> all available boxactions. These include icons for changing the portletmode and windowstate, when they are not rendered with specific placeholders described below.

  • <windowstates> boxactions for switching the windowstates. When this placeholder is not given, the icons for switching the windowstates are rendered as part of <boxaction>.

  • <portletmodes> boxactions for switching the portletmodes. When this placeholder is not given, the icons for switching the portletmodes are rendered as part of <boxaction>.

  • <moduleid> id of the portlet.

actionstylesStructureDefinition of how icons for window actions are rendered. The window actions include icons for switching windowstates and portletmodes.
actionstyleStructureDefinition of a single actionstyle.
actionstyle.nameStringId of the actionstyle.
actiontemplateStringTemplate for an icon for a window action. May contain the following placeholders:
  • <icon> name of the action icon as defined below.

  • <url> url to activate the window action.

  • <alt> alt-text (description) of the window action as defined below.

  • <moduleid> id of the portlet.

actionseperatorStringTemplate for the separator to be rendered between action icons.
actionStructureDefinition for a specific portlet window action.
action.typeString

Definition of the action for which this style shall be used.

This may be portletmode.[mode] for the portletmode [mode], windowstate.[state] for the windowstate [state] or the name of a specific defined portlet action (without the prefix on).

action.iconStringDefinition of the action icon that will be rendered into <icon> from the actiontemplate.
action.altStringDescriptive alt-text of the action.
11.1.2.1. Defining Custom Actions

To define a custom action which can be used for a pnode/pbox and be catched in a reaction you need to follow the following three simple steps:

  1. Create a new action in the actionstyles / actionstyle tag:

    <action type="CustomAction">
      <icon>edit</icon> <!-- Select a custom icon here -->
      <alt>New Custom Action</alt>
    </action>
    							
  2. Add the action to your pnode/pbox:

    <action name="CustomAction">
      <visible>true</visible>
    </action>
    							
  3. Use a reaction in your pnode/pbox to catch this action:

    <reaction event="portal.pboxes.SimpleViewTest.onCustomAction">
      <!-- do whatever you want here ... -->
    </reaction>
    							

11.1.3. PNodes

The portaltemplate may contain <pnode> tags, each one defining an instance of a portlet with optional parameters and customized templates. Each <pnode> implicitly defines also a pbox with the same id. For details on pboxes see Section 11.1.4, “PBoxes” .

Example 4.54. Syntax of a pnode tag

<pnode type="..." id="...">
  <style>...</style>
  <isvisible>[<prule>...</prule>]</isvisible>
  <windowstate>...</windowstate>
  <title>...</title>
  <titleaction>...</titleaction>
  <actions>
    <action name="...">
      <visible>[<prule>...</prule>]</visible>
    </action>
    ...
  </actions>
  <reactions>
    <reaction event="...">
      ...
    </reaction>
    ...
  </reactions>
  <parameters>
    <parameter name="...">[<pobject>...</pobject>]</parameter>
    ...
  </parameters>
  <templates>
  </templates>
</pnode>
					

Table 4.167. Parameters of the pnode tag

NameTypeDefaultDescription
pnodeStructure Definition of a portlet instance.
pnode.typeString(required) portlet-name of the portlet to be instantiated.
pnode.idString(required)Id of the portlet instance. Must be unique within all <pnode>s and <pbox>es in this portalpage.
styleStringdefault modulestyle. See Section 11.1.2, “pportal Tag” .Modulestyle of the portletinstance.
isvisibleBoolean or PRuletrueWhether the implicit pbox shall be visible or not.
windowstateStringnormalInitial windowstate in which the pbox shall be rendered.
titleStringtitle of the portlet defined in the portlet descriptor.Title of the portlet.
titleactionStringNULLAction to be activated upon link on the portlets title.
actionsStructureNULLDefinition of the portlet window actions.
actionStructureNULLDefinition of a portlet window action. This may also override the default actions for switching portletmodes and windowstates.
action.nameString(required)Name of the portlet window action. See Section 11.1.2, “pportal Tag” for details on action names for the standard actions. Custom actions will trigger an event called portal.pboxes.[pboxid].on[ActionName] when activated.
action.visibleBoolean or PRuletrueWhether the action icon shall be visible or not.
reactionsStructureNULLDefinitions of reactions.
reaction StructureNULLDefinition of a reaction on a specific event. The node value may consist of one or more lines, each one setting a portal property. See Section 7, “Property Setters” for details - reaction property setter have the limitation that you must not use quotes (").
reaction.eventString(required)Full path of the event this reaction shall listen to. The path begins with
  • portal.modules.[moduleid] for portlet events.

    portal.pboxes.[pboxid] for pbox events.

parametersStructureNULLDefinition of parameters for the portlet instance.
parametervariousNULL

Definition of a specific parameter. The allowed values depend on the parameter definition in the Gentics portlet descriptor.

You can use <pobject> to access portal properties, see Section 8, “Portal Property Paths” for more details.

parameter.nameString(required)Name of the parameter to set.
templatesStructureNULLDefinition of specific templates for this portlet instance. See Section 8.7.4, “Template definitions” for details on definition of templates.

11.1.4. PBoxes

The portaltemplate may contain <pbox> tags, each one defining a place where a portlet may be rendered. The difference between a <pnode> tag and a <pbox> tag is that with a <pbox> does not create a new instance of a portlet.

Example 4.55. Syntax of a pbox tag

<pbox id="...">
  <moduleid>...</moduleid>
  <windowstate>...</windowstate>
  <isvisible>[<prule>...</prule>]</isvisible>
</pbox>
					

Table 4.168. Parameters of the pbox tag

NameTypeDefaultDescription
pboxStructure Definition of a place in the portal page where a portlet may be rendered.
pbox.idString(required)Id of the pbox. Must be unique within all pnodes and pboxes of the portal page.
moduleidStringNULLId of a portlet that shall be initially loaded into this pbox.
isvisibleBoolean or PRuletrueWhether the pbox shall be visible or not.
windowstateStringnormalInitial windowstate in which the pbox shall be rendered.

11.2. Portlet Templates

Portlet templates are specified in the Gentics Portlet Descriptor in the <templates> section of a specific portlet or may be overridden in the <pnode> tag in the Portal Template. The loading order is as follows. The first matching is taken.

11.3. Plugin Templates

Plugin templates are specified in the Gentics Portlet Descriptor in the <templates> section of a specific plugin or may be overridden in the <pnode> tag in the Portal Template. The loading order is as follows. The first matching is taken.

11.4. TemplateEngine2

11.4.1. Introduction

Velocity based template engine, with helper objects embedded.

11.4.2. Velocity

Velocity is a simple but powerful template language which is part of the Apache Jakarta Project. For full documentation see: http://velocity.apache.org/.

VTL (Velocity Template Language) has a few predefined language constructs - the most important are listed here:

  • Comments

    Single line comments using two hashes: ## This is a comment

    Multiline comments using #* this is a comment *#

  • References - Indicated using a $ - e.g. $myvar

    There are three types of References in the VTL: variables, properties and methods. Variables are objects which are in the Velocity Context, e.g. using #set( $myvar = "test" ) would set the Variable $myvar

    Properties look like: $myobj.myproperty - Velocity will first try to call the java method .get( "myproperty" ) on the specified object, if it is not found it will try to call .getMyproperty().

    Methods can simply be called using $myobj.myMethod() which would call the method specified and returns the object of the method.

  • Directives and Velocimacros

    To call predefined VTL Directives simply use a hash followed by it's name. e.g.: #set( $var = "value" ), #if( $var == "$value" ) #else #end, #foreach( $var IN $collection ) #end, etc.

    Velocimacros are userdefined directives which look very similar in it's syntax but are defined in a VTL file using: #macro( macroName $argName1 $argName2 ) #end - they are then called using #macroName( $argValue1 $argValue2 )

[Note]Note

The Velocity Template Language is very powerful and most is far beyond the scope of this short Introduction. So if you have never used Velocity before you should head over to the Velocity User Guide to get more in-depth documentation.

11.4.3. Context

The templateengine's context contains usefull objects, which can be addressed through Section 8, “Portal Property Paths” .

$portal - the portal object, including imps and i18n.

$javax.portlet - portlet information, including context, config, request and response.

$portlet - the portlet rendering the template (may be null if the template is not rendered by a portlet)

$plugin - the plugin rendering the template (may be null if the template is not rendered by a plugin)

$position - the current position of the portlet (may be null if the template is not rendered by a portlet)

$ctx - the velocity context