8. Portal Configuration File

8.1. Introduction

The Portal Configuration File is located at ${com.gentics.portalnode.confpath}/default.portal.xml and contains the basic configuration of the portal server.

8.2. general-section

8.2.1. Introduction

The general-section is used to define general parameters that are needed to run Gentics Portal.Node.

Example 3.2. Structure of the general-section

<general-section>
  <parameters>
    <parameter id="[paramname]">[paramvalue]</parameter>
	...
  </parameters>
  <properties>
    <property id="[propertyname]">[propertyvalue]</property>
    ...
  </properties>
  <bookmarks>
    <bookmark pathinfo="[pathinfo]" destination="[destinationpath]">
      <parameters>
        <parameter id="[parameter]">[staticvalue]</parameter>
        <parameter id="[parameter]" mapped="[requestparameter]"/>
        ...
      </parameters>
    </bookmark>
    ...
  </bookmarks>
</general-section>
					

8.2.2. Portal server response settings

Table 3.11. Portal parameters for response settings

NameDescriptionDefault
portal.serversignatureTrue if the poral shall add a signature header (X-Server) to every response, false if not server signature header shall be sent.true

8.2.3. Portal server activation

Table 3.12. Portal parameters for activation feature

NameDescriptionDefault
portal.activation.auto True or false, whether the portal server shall automatically try to (re-)activate, when no valid license.key found (e.g. the hardware checksum changed). For SDK installations, this parameter is ignored and activations are always done interactively. false
portal.activation.dialog True or false, whether the activation shall be done with an activation dialog or must be done manually. For SDK installations, this parameter is ignored and activations are always done interactively. false
[Warning]Warning

For portal server installations, where the portal parameter portal.activation.dialog is set to true and the license becomes invalid (e.g. due to changes in the systems configuration), any user accessing the portal with a browser would see the activation dialog. To prevent this happening in production environments, it is STRONGLY recommended to turn this feature off, once the installation is successfully activated!

8.2.4. Updates

Table 3.13. Portal parameters for update checking

NameDescriptionDefault
portal.update.checkTrue or false, whether to check for updates on each startup. Writes upate status information to console when enabled.true

8.2.5. Template Engine 2

Table 3.14. Portal parameters for the Template Engine 2

NameDescriptionDefault
portal.templateengine2.compatibilitymodeTrue or false, whether the Template Engine 2 is in compatibility mode or not. When the Template Engine 2 is in compatibility mode, all available imps will also be available directly under their respective id (e.g. $date for the DateFormatter). The compatibility mode is DEPRECATED and should not be used. Address the imps like $portal.imps.[impid] instead.false

8.2.6. Portlet Template Finder Cache

The Portlet Template Finder Cache may provide you with a performance gain if a whole lot of component templates are used.

Table 3.15. Portlet Template Finder Cache

NameDescriptionDefault
portal.templatefinder.cacheEnable templatefinder caching, where best matching component templates are cached.false

8.2.7. Portlet Cache

The Portlet Cache can be used to cache the render output of Portlets supporting Expiration Cache as defined by the Portlet Specification (JSR 168). See “Portlet Cache” (Section 4.5) for more information.

Table 3.16. Portal parameters for Portlet Cache

NameDescriptionDefault
portal.portlet.cacheEnables or Disables caching of Portlets.false

8.2.8. Portal Template Configuration

The design, the used portlets and the adjustment of the used portlets of a portal are defined by the Gentics Portal.Node Portal Template. For details on the structure and content of the Portal Template see Section 11.1, “Portaltemplate” .

[Note]Note

When using Portal Pages, the portal template and with it all configuration parameters in this section are not used.

See “pages-section” (Section 8.9) and “Portal Pages Implementation” (Section 14) for details on Portal Pages.

Table 3.17. General portaltemplate parameters

NameDescriptionDefault
portal.template.templateengine2Whether the portaltemplate itself shall be rendered using the Template Engine 2. See Section 11.4, “TemplateEngine2” for details on the Template Engine 2. Enabling this parameter is quite performance expensive.FALSE
portal.template.hiderequesttimeWhether to disable and hide the HTML comment line at the of the template, containing the time taken by the portal to process this request, excluding network response time. A logger can be used instead.FALSE

There are two possible ways to provide the portal template to the portal:

  1. The portal template is loaded from a Gentics Content.Node; 3.6 content repository.

    Table 3.18. Portal parameters for content repository-based portaltemplate

    NameDescriptionDefault
    portal.template.datasourceId of the datasource where the template shall be loaded from. The datasource has to be configured in the Section 8.6, “datasource-section” and must be of type contentrepository .NULL
    portal.template.contentidContentid of the portaltemplate.NULL
  2. The portal template is provided as a file in the servers filesystem. For this, the absolute path of the file must be configured.

    Table 3.19. Portal parameters for file-based portaltemplate

    NameDescriptionDefault
    portal.template.fileAbsolute path to the portaltemplate file. This path may contain Section 2, “System properties” and it is recommended to locate the file relative to com.gentics.portalnode.confpath .NULL

8.2.9. PLink Processor

PLinks are links to documents that are stored in the Gentics .Node ContentRepository and are displayed with a portlet of type GenticsContentModule. In order to have PLinks that are placed outside of GenticsContentModules correctly working, the id of a GenticsContentModule has to be configured here as well.

<plink>s have two different types of locations:

  1. Inside a content that is shown in a GenticsContentModule. In this case, the default behaviour of the link is to trigger the onSelect event of this portlet. This event can be caught in a <reaction> and the business logic implemented accordingly. Note that this behaviour can be modified by setting the portal parameter portal.plinkprocessor.forceall (see below).

  2. Outside of GenticsContentModules (in content rendered by other portlets or even in the portal template itself). These <plink>s will trigger the onSelect event of the configured plinkprocessor .

For details on the portlet see Section 4, “GenticsContentModule”. Details on configuring and placing portlets and implementing reactions can be found in Section 11.1.3, “PNodes”

Table 3.20. Portal parameters for plink processor

NameDescriptionDefault
portal.plinkprocessorId of the “GenticsContentModule” (Section 4) that will process all <plink>s that are not placed inside content rendered in GenticsContentModules. When the parameter portal.plinkprocessor.forceall is set to true, the plinkprocessor will process all <plink>s.NULL
portal.plinkprocessor.forceallIf set to true all >plink>s will be rendered using the provided portal.plinkprocessor as their target. Enable to ensure backwards compatibility to Gentics Portal.Node versions prior to 3.2.false

8.2.10. Fileupload Configuration

Fileupload parameters are mainly used to limit the default maximum fileupload size.

Table 3.21. Portal parameters for fileuploads

NameDescriptionDefault
portal.upload.maxFilesizeMaximum allowed fileupload size in bytes.1048576 (1mb)
portal.upload.sizeThresholdUploads larger than the given bytesize will temporarily be stored in the filesystem (repositoryPath. Smaller uploads will be kept in memory.4096 (4kb)
portal.upload.repositoryPathThe path where upload files will temporarily be stored when their size exceed sizeThreshold.${java.io.tmpdir}

8.2.11. ViewPlugin Configuration

ViewPlugin configuration parameters are used to modify the general behaviour of the viewplugin.

Table 3.22. Portal parameters for the viewplugin.

NameDescriptionDefault
portal.viewplugin.checkviewchanges Whether changes in the view files shall be checked periodically or not. This helps in development environments since changes in view files are automatically recognized and the files are reloaded. It is strongly recommended that in production environments this is set to false for performance reasons!true
portal.viewplugin.doubleclickprotection

This parameter is the portal-wide setting of the double-click protection of views. When the double-click protection is true for a specific view, the portal will check whether an action request directed to the view contains the renderkey which was generated the last time the view was rendered. This prevents unwanted effects when users use the browsers back button and submit a form from a portalpage that was fetched from the browsers history.

The portal-wide setting may be overwritten per ViewPortlet or event per view (see “ViewPortlet” (Section 3) and “Views” (Section 2.2.6) for details).

true
portal.viewplugin.disableviewreferences With this parameter, the support for the deprecated view references can be disabled. Doing so will significantly reduce the memory consumption per user session. It is therefore strongly recommended, that view references are disabled by setting this parameter to true , unless they are used in the implementation. false

8.2.12. Datasources Configuration

Datasources configuration parameters are used to modify the general behaviour of datasources.

Table 3.23. Portal parameters for datasources

NameDescriptionDefault
portal.datasources.autorepair

Flag to switch off the auto-repair functionality of Gentics Portal.Node. When auto-repair is turned on, all datasources of type contentrepository are checked and the server tries to repair the datasources by adding missing columns. Modifications in the data structure may fail due to database permission settings or may be long running operations (for example when the table is very large). Therefore an administrator may opt to turn the auto-repair off by setting this parameter to false and make eventually necessary modifications manually during an update process.

This global setting can be overwritten for specific datasources. See “Datasources of type contentrepository” (Section 8.6.3.1) for details.

true

8.2.13. ExpressionParser Configuration

These parameters can be used to use and configure the new “ExpressionParser” (Section 10) in favor of the old RuleParser.

Table 3.24. Portal parameters for the ExpressionParser

NameDescriptionDefault
portal.expressionparser

When this parameter is set to false , the ExpressionParser is not used and Gentics Portal.Node runs in compatibility mode (all rules, filters and reactions are processed in a way that is compatible with older versions of Gentics Portal.Node ) . When set to true (default value) , the ExpressionParser is used. Note that some rules, filters or assignment commands might be incompatible with the new ExpressionParser (or might be interpreted in a different way). To find possible problems, it is recommended to use the test mode and the log-level for the logger com.gentics.lib.expressionparser to DEBUG while upgrading an existing Gentics Portal.Node implementation to the ExpressionParser. With this setting, the ExpressionParser will be used, but generate a lot more log messages for possibly incompatible expressions. See Section 9, “Logging” for details on setting the log level and Section 10, “ExpressionParser” for details on the ExpressionParser.

true
portal.expressionparser.treatEmptyStringAsNull

When portal.expressionparser is set to true or test (the ExpressionParser is used, default), this parameter modifies the behaviour of comparisons [object.attribute] == "" . When portal.expressionparser.treatEmptyStringAsNull is set to false , the comparison is only true for empty strings (not for null values, meaning that the attribute is not set). When set to true , the comparison is also true for null values.

false

8.2.14. Dictionaries Configuration

Parameters for configuration of general dictionary handling. See “Dictionaries” (Section 8.5.3) for details.

Table 3.25. Portal parameters for Dictionaries

NameDescriptionDefault
portal.dictionaries.modificationCheckInterval

Modification check interval for all dictionary files in seconds. When set to -1, no modification check is done and dictionary changes will become available only on restart of Gentics Portal.Node (recommended for production systems). A setting of 0 will check on every access to a dictionary.

-1 (no modification check)

8.2.15. Portal pages Configuration

Parameter for switching on/off the usage of portal pages. See “pages-section” (Section 8.9) and “Portal Pages Implementation” (Section 14) for details on portal pages.

When portal pages are used, the “Portal Template Configuration” (Section 8.2.8) is completely replaced by the “Portlet Entities Configuration” (Section 13) .

Table 3.26. Portal parameters for Portal pages

NameDescriptionDefault
portal.pages

With this parameter the multiple portal pages can be activated. When set to false (default), the portal template will be rendered.

false
portal.portlet.entities.file

Path to the file configuring the portlet entities. This path must be set, when portal pages are used. See “Portlet Entities Configuration” (Section 13) for details on portlet entities.

NULL

8.2.16. URL Mapping Configuration (Beautiful URLs)

Parameter for switching on/off the usage of “urlmapping-section” (Section 8.10)

Table 3.27. Portal parameters for Portal pages

NameDescriptionDefault
portal.urlmappings

Enables usage of the urlmapping section.

false

8.2.17. Portlet Reloading

Global configuration for portlet reloading (see “Portlet Reloading” (Section 6.3.3)). These global settings can be overridden by PNode parameters (see “Parameters of all Gentics Portlets” (Section 2.3)).

Table 3.28. Portal parameters for Portlet Reloading

NameDescriptionDefault
portal.portletreload

Enables portlet reloading for all portlets.

false
portal.portletreload.allclasses

Replace all elements, regardless of CSS class (see portal.portletreload.replaceclasses).

true
portal.portletreload.replaceclasses

Enables portlet reloading only for elements (links, forms) which have at least one of the specified CSS classes. List all CSS classes as a comma-separated list.

NULL
portal.portletreload.replaceform

Enables portlet reloading for forms (replace the default submit action).

true
portal.portletreload.replacelink

Enables portlet reloading for links (replace the default onclick action).

true

8.2.18. Namespace Compliance

Parameter for switching on/off the JSR 168 compliant generation of namespaces.

For historic reasons, the namespaces generated for render or resource responses contained special characters like "." (dots), which is not compliant to the portlet specification. With this portal parameter, this behaviour can be changed.

Table 3.29. Portal parameters for Namespace compliance

NameDescriptionDefault
portal.namespace.compliance

Enables generation of JSR 168 compliant namespaces.

false

8.2.19. Login Behaviour

Parameter to influence the login behaviour: When switched off, logging in will create a new portal session, which is the original behaviour. When switched on, logging in will keep the portal session together with all current settings. Logging out will always create a new portal session.

The new login behaviour will also reduce the memory consumption per session.

Table 3.30. Portal parameters for Login Behaviour

NameDescriptionDefault
portal.keepsessiononlogin

Enables the behaviour to keep the portal session when logging in.

false

8.2.20. Parameters for configuring the markup aggregation

With the following parameters, the aggregation of markup provided by portlets can be configured.

Table 3.31. Portal parameters for markup aggregation

NameDescriptionDefault
portal.headeratend

When this parameter is set to true , any markup provided by portlets that should be added to the head section sent to the client will be appended to the end of the head section. When set to false (which is the default), that markup will be prepended to any existing <head> content.

false

8.2.21. Portal Properties

Portal Properties are used to store portal-wide settings for use in views or velocity templates. These settings can be accessed and set via portal.properties.[propertyname], where propertyname is the id of the property you defined. So if you would like to define your company name for use in the portal it should look as stated below.

Example 3.3. Portal Property configuration

<general-section>
  ...
  <properties>
    <property id="companyname">MyCompany Inc.</property>
  </properties>				
</general-section>
					

Now, if you'd like to use the property you just have defined in an velocity template, you can simply use $portal.properties.companyname. Please keep in mind that the portal has to be restarted for the new properties set in the portal configuration file to take effect. Portal Properties can also be used in views as the following example depicts.

Example 3.4. Usage of Portal Property inside a view

...
<buttoncomponent>
  <label>Click Me!</label>
  <actions>
    <action class="EchoAction">
      <parameters>
        <parameter id="CompanyName" mapped="portal.properties.companyname"/>
      </parameters>
    </action>
  </actions>
</buttoncomponent>
...
					

This example creates a buttoncomponent inside an existing view. On click of the button the company name ist echoed into the logfile.

8.2.22. Bookmarkable URLs

The section for bookmarkable URLs defines the pathinfo and parameters for bookmarkable URLs and how they are mapped to normal portal request URLs.

Bookmarkable URLs are constructed like http://[hostname]:[portname]/Portal.Node/go/[path-info]?[query-string] , where path-info identifies the URL definition in this section and query-string may contain request parameters that can be mapped to the destination URL.

The destination URL is [destinationpath]?[query-string] , where destinationpath is defined for the bookmarkable URL and query-string is constructed from the defined parameters . Every parameter may either have a static value, or may be mapped from an incoming request parameter.

Example 3.5. Bookmarkable URL

<bookmarks>
  <bookmark pathinfo="/minimize" destination="/Portal.Node/portal">
    <parameters>
      <parameter id="gentics.rm" mapped="portlet"/>
      <parameter id="gentics.pb" mapped="portlet"/>
      <parameter id="gentics.ws">minimized</parameter>
    </parameters>
  </bookmark>
</bookmarks>
                    

Will forward the bookmarkable URL http://hostname/Portal.Node/go/minimize?portlet=AdministrationPortlet to http://hostname/Portal.Node/portal?gentics.rm=AdministrationPortlet&gentics.pb=AdministrationPortlet&gentics.ws=minimized (which minimizes the portlet AdministrationPortlet in the pbox AdministrationPortlet ).

8.3. authentication-section

8.3.1. Introduction

This section contains the configuration of the used Authentication Managers and the anonymous user profile.

Example 3.6. Structure of the authentication-section

<authentication-section>
  <authentication-descriptor default="...">
    <authentication id="...">
      <Description>...</Description>
      <class-name>...</class-name>
      <parameters>
        <parameter id="...">...</parameter>
      </parameters>
      <mapping>
        <map from="..." to="..."/>
        ...
      </mapping>
    </authentication>
    <authentication id="...">
    </authentication>
    ...
  </authentication-descriptor>
  <anonymous-user>
    <domain name="..." authentication="...">
      <anonymous id="...">
        <anonymous-parameter id="...">...</anoymous-parameter>
      </anonymous>
    </domain>
  </anonymous-user>
</authentication-section>
					

8.3.2. Configuration Details

Table 3.32. Configuration of Authentication Managers

NameTypeDescription
authentication-descriptorStructureBase node for the definition of authentication managers
authentication-descriptor.defaultStringId of the default (primary) authentication manager that is used for access management.
authenticationStructureNode that defines a single authentication manager.
authentication.idStringId of this authentication manager. must be unique within all authentication manager ids.
DescriptionStringDescription of this authentication manager.
class-nameStringFull qualified class-name of the java class that implements the authentication manager. The class must implement the class com.gentics.portalnode.auth.AuthenticationSystem
parametersStructureDefinition of the parameters for this authentication manager.
parameterNodeDefinition of a single parameter for this authentication manager, the value is given as node value.
parameter.idStringId of the parameter to set.
mappingStructureDefinition of parameter mappings from the user repository to the portal user parameters.
mapNodeDefinition of a single parameter mapping.
map.fromStringOriginal parameter name in the user repository.
map.toStringName of the parameter for the portal user.
anonymous-userStructureDefinition for the user profile for the anonymous user.
domainStructureUser profile for an anonymous user for a given domain pattern. The domain pattern must match the hostname under which the user reaches the portal.
domain.nameStringPattern of the hostname to match. May contain * as wildcard for arbitrary characters.
domain.authenticationStringId of the authentication manager that is the default for this domain.
anonymousStructureDefinition of anonymous user parameter for a given authentication manager.
anonymous.idStringId of the authentication manager.
anonymous-parameterNodeDefinition of a single anonymous parameter. The value is given as node value.
anonymous-parameter.idStringId of the anonymous parameter.

Table 3.33. Parameters for all AuthenticationManagers

NameDefaultDescription
secondaryrulenull Rule for checking, whether an authentication manager shall be used as secondary authentication manager (if it is not the primary auth manager). The rule will allow access to the current request (as request.*) and the user, with all data from the primary and the other secondary authentication managers, that already added their data (as user.*).

8.3.3. PNAuthenticationManager

This authentication manager is implemented by the class com.gentics.portalnode.auth.manager.PNAuthenticationManager and provides authentication based on a datasource of type contentrepository. For details on configuration of datasources, see Section 8.6, “datasource-section” .

[Note]Note

Please note that request parameters have to be prefixed with "p." when a user should be logged in using an external HTTP request. e.g. "_PNlogin" will become "p._PNlogin" since Gentics Portal.Node will automatically prefix userrequestparameter, passwordrequestparameter and logoutrequestparameter internally.

Table 3.34. Parameters for the PNAuthenticationManager

NameDefaultDescription
userrequestparameter_PNloginName of the request parameter that holds the login name of the user requesting authentication.
passwordrequestparameter_PNpasswordName of the request parameter that holds the (unencrypted) password.
logoutrequestparameter_PNlogouturlName of the request parameter that identifies a logout request.
logoutrequestvaluetrueValue of the request parameter that identifies a logout request.
datasourceid{required}Id of the datasource that holds the user profiles. Must be a datasource of type contentrepository .
objecttype{required for secondary authentication managers}Objecttype of the user objects in the datasource.
userattributeloginUser attribute that holds the login name and therefore identifies the user profile.
passwordencryptionMD5The used encrytion method for the password. May be one of plaintext (no encryption), MD5 or SHA-1.
loginrule{required for primary authentication managers}The filterrule that will find the user profile matching the given login data, which are provided as data.login and data.password (encrypted). It is strongly recommended that data.login is matched against the object attribute configured in the parameter userattribute, but the rule may as well contain other relevant filter criteria.
8.3.3.1. PNAuthenticationManager as primary authentication system

When this authentication manager is used as primary authentication system, it will authenticate requests that contain login data as values of the userrequestparameter and passwordrequestparameter. The configured loginrule is used as filter for a search in the datasource and if it returns objects, the user is supposed to be authenticated. The returned object should be unique and should be the user profile of the authenticated user. When no objects are returned in the search, the authentication fails and the user remains anonymous.

8.3.3.2. PNAuthenticationManager as secondary authentication system

When this authentication manager is used as secondary authentication system, it will not use any loginrule but will just store any additional set user attributes in the datasource. The datasource object holding the additional user profile is defined by

  • object.obj_type == objecttype

  • object.userattribute == [userid from the primary authentication system]

8.3.4. LDAPAuthenticationManager

This authentication manager is implemented by the class com.gentics.portalnode.auth.manager.LDAPAuthenticationManager and provides authentication based on a datasource of type ldap. For details on configuration of datasources, see Section 8.6, “datasource-section” .

Table 3.35. Parameters for the LDAPAuthenticationManager

NameDefaultDescription
ldapDatasourceName(required)Id of the datasource that holds the user profiles. Must be a datasource of type ldap .
ldapVersion(optional)LDAP Version the server is using. Defaults to 3 if no value provided.
ldapPort(optional)Port of the ldap server. Defaults to 389 if no value provided.
ldapHost(required)Hostname (or ip address) of the ldap server.
userDNAttribute(required)the user’s attribute which forms the complete DN when concatenated with baseDN, eg: mail or cn. Do NOT add equals or comma here!
filterRule(optional)allows you to specify a custom filter rule. The filter rule used by default is: object.USERDNATTRIBUTE == login.name. USERDNATTRIBUTE is the userDNAttribute you specified, while login.name is the login name the user entered in the authentication form. When specifying a custom filter rule you can use the variables login.name and login.pass which will be resolved to the user's login name or password respectively. A custom rule could look as follows: object.uid == login.name && object.class = "Person". Note that the deprecated placeholders $loginName and $loginPass still can be used, but it is recommended to use login.name and login.pass instead.
8.3.4.1. Mode of Operation

The LDAPAuthenticationManager determines a user's DN by executing an LDAP search via the LDAP datasource specified, filtered by filterRule. If an object is returned the LDAP Authentication Manager will try to bind with the password provided by the login form. On successful bind the user is authenticated and provided with his properties which where retrieved during LDAP search.

Another vital configuration part is the mapping section, since only attributes which are configured in this section will be available as user properties when the user is logged in. So eg. if you forget to map a user's mail attribute you won't be able to read his mail address.

8.3.4.2. Example

Here is an example configuration which includes authentication and datasource section from default.portal.xml.

...
<authentication-section>
  <authentication-descriptor default="LDAP">
    <authentication id="LDAP">
      <Description>LDAP Authentication Module</Description>
      <class-name>com.gentics.portalnode.auth.manager.LDAPAuthenticationManager
        </class-name>
      <parameters>
        <parameter id="ldapDatasourceName">ldap</parameter>
        <parameter id="userDNAttribute">uid</parameter>
        <parameter id="userPasswordAttribute">userPassword</parameter>
        <parameter id="ldapPort">389</parameter>
        <parameter id="ldapHost">localhost</parameter>
        <parameter id="filterRule"><![CDATA[object.uid == "$loginName"]]&lt;
          </parameter>
      </parameters>
      <mapping>
        <map from="cn" to="cn" />					
        <map from="givenName" to="givenName" />
        <map from="mail" to="mail" />
      </mapping>
    </authentication>			
  </authentication-descriptor>
  <anonymous-user>
    <domain name="*" authentication="LDAP">
      <anonymous id="LDAP">
        <anonymous-parameter id="userid">max.mustermann@gentics.com
          </anonymous-parameter>
        <anonymous-parameter id="firstname">Max</anonymous-parameter>
        <anonymous-parameter id="lastname">Mustermann</anonymous-parameter>
        <anonymous-parameter id="cn">Max Mustermann</anonymous-parameter>
      </anonymous>
    </domain>
  </anonymous-user>
</authentication-section>
<datasource-section>
  <datasource-handles>
    <datasource-handle typeid="ldap" id="ldap_handle">
      <parameter name="host">localhost</parameter>
      <parameter name="port">389</parameter>
      <parameter name="basedn">dc=abc,o=def</parameter>
      <parameter name="binddn"/>
      <parameter name="password"/>
    </datasource-handle>			
  </datasource-handles>
  <datasources>
    <datasource id="ldap" typeid="ldap">
      <parameter name="binddn"/>
      <handles>
        <handle>ldap_handle</handle>
      </handles>
    </datasource>			
  </datasources>
</datasource-section>
...
				
8.3.4.3. Limitations

Currently the LDAP Authentication Manager cannot handle multivalue attributes.

8.3.5. SiteMinderAuthenticationManager

This authentication manager is implemented by the class com.gentics.portalnode.auth.manager.SiteMinderAuthenticationManager and provides authentication based on CA eTrust® SiteMinder® module for the Apache WebServer. It currently supports singon and read operations.

Table 3.36. Parameters for the SiteMinderAuthenticationManager

NameDefaultDescription
collectionsNULL

List of SiteMinder attributes that contain collections of attributes. Separated by ';'

The values of the attributes listed here should follow this structure: attribute1=key1:value1|key2:value2^attribute2=value3^... . This would set user parameters as follows:

  • attribute1 = Map

    • key1 = value1

    • key2 = value2

  • attribute2= = value3

authentication_keySM_UNIVERSALID

Specifies the header attribute which will be checked to verify if a user is logged in.

decodeUTF8false

This parameter can be set to true in case of incorrectly encoded Siteminder headers. Normally, request headers should be encoded according to the request encoding, but in special situations Siteminder does not respect the request encoding, but adds additional headers in ISO-8859-1 encoding. When the request encoding is set to 'UTF-8' (which is normally true for usual server configurations), setting this property will let the SiteminderAuthenticationManager decode the headers, which were incorrectly interpreted by the application server as being 'UTF-8' into correct 'UTF-8'.

8.3.6. RemoteUserAuthenticationManager

This authentication manager is implemented by the class com.gentics.portalnode.auth.manager.RemoteUserAuthenticationManager and provides authentication based on the RemoteUser information provided by the HttpServletRequest instance (return value of the method javax.servlet.http.HttpServletRequest.getRemoteUser() ).

This allows coupling the portal authentication to authentication mechanisms provided by the underlying application server, or by independent implementations e.g. in ServletFilters.

Since passing additional attributes of the authenticated individual to the Web Application is not in the scope of the Servlet Specification, this authentication manager provides the possibility to pass user attributes to the portal by storing them as a java.util.Map either in the session or as request attribute (depending on the setting of the parameter attributescope described below) under the key com.gentics.portalnode.remoteuserdata .

Table 3.37. Parameters for the RemoteUserAuthenticationManager

NameDefaultDescription
attributescopesession

When this parameter is set to session , the authentication manager expects the Map of user attributes to be stored in the session, when set to request it expectes them to be stored as request attribute.

8.3.7. GCNAuthenticationManager

This authentication manager is implemented by the class com.gentics.portalnode.auth.manager.GCNAuthenticationManager and provides authentication by login to a Gentics Content.Node 5 backend system.

When the GCNAuthenticationManager is configured as primary Authentication Manager and a User tries to login (e.g. with the GenticsLoginModule), the Portal Server will POST the login credentials to the configured backendb url. This means that the given URL must be reachable by the Portal Server, NOT the client.

The GCNAuthenticationManager can also be configured as secondary Authentication Manager behind another one (e.g. SiteMinderAuthenticationManager). In that case, either a mapping for username and password or for the headers for the authentication request (or both) need to be configured.

Table 3.38.  Parameters for the GCNAuthenticationManager

NameDefaultDescription
urlNULL

URL to the backend system which will be used to authenticate the portal user, e.g. http://localhost/.Node/ . This parameter is mandatory.

headerNULL

Configuration of the request headers which must be added to the authentication request, when the backend is configured to authenticate by request headers (e.g. for use with SiteMinder).

The headers need to be configured as comma separated list of key/value pairs, which are separated by the character '='. Keys are the names of the request headers, values are expressions, which resolve to the header values, based on the portal user attributes which might be provided by other authentication managers.

Example: UID=sm.UID,GIVENNAME=sm.GIVENNAME,SN=sm.SN,MAIL=sm.MAIL,CN_GRUPPE=sm.CN_GRUPPE In this example, the header values are mapped from the primary Authentication Manager (with id sm).

usernameNULL Expression which resolves to the value to be used as username when authenticating as secondary Authentication Manager. The expression is evaluated based on the current user object. (See description of header parameter).
passwordNULL Expression which resolves to the value to be used as password when authenticating as secondary Authentication Manager. The expression is evaluated based on the current user object. (See description of header parameter).
cookieNULL Comma separated list of cookie names, that will be forwarded to the authentication request.
timeout5000 Timeout in ms before getting the connection fails.
sockettimeout5000 Timeout in ms before connecting or reading from the socket fails.
connectionretry3 Number of retries for establishing a connection to the authentication URL.
refreshinterval600 Interval in seconds for keeping the backend session alive. The default is 600s (10 minutes).
backendLoginRetryInterval0

This parameter specifies the number of seconds to wait to retry a failed login request to the GCN backend. The value 0 will retry on every request. Logins to the GCN backend are unsuccessful if the user authenticated with the primary authentication system doesn't have a GCN account (e.g. read-only privileges for the content in the portal, but no editing privileges in the GCN backend). Another reason may be that the GCN backend may be temporarily unavailable. Retrying unsuccessful logins may cause performance problems if there are many users that can be authenticated with a primary authentication system but can't be authenticated with the GCNAuthentication manager as a secondary authentication system - each request by the user (browser) would cause an additional internal authentication request.

The following table lists the properties which are readable for authenticated users.

Table 3.39.  User Properties from GCNAuthenticationManager

NameDescription
firstnameFirst name of the user
lastnameLast name of the user
fullnamefirstname lastname
emaileMail Address of the user
descriptionDescription of the user
loginLogin name of the user
useridAlias for login
groups List of group ids the user is member of.
sid Gentics Content.Node 5 session id
sessionSecret Gentics Content.Node 5 session secret
sessionToken Gentics Content.Node 5 session token

8.4. formatter-section

8.4.1. Introduction

The formatter section contains the configuration of the Gentics Portal.Node Imps.

Imps are small helper classes that provide useful functionality, mostly used in templates - e.g. to output formatted data. In prior versions of Gentics Portal.Node they used to be called Formatters.

Example 3.7. Syntax of the formatter-section

<formatter-section>
  <formatter id="...">
    <class-name>...</class-name>
    <parameters>
      <parameter id="...">...</parameter>
	  ...
    </parameters>
  </formatter>
  ...
</formatter-section>
					

8.4.2. Configuration

Table 3.40. Configuration of imps

NameTypeDescription
formatterStructureDefinition of an imp.
formatter.idStringId of the imp. Must be unique within all imp-ids.
class-nameStringFull qualified java class-name of the class implementing the imp's features.
parametersNodeConfiguration parameters for the imp.
parameterNodeValue of one configuration parameter.
parameter.idStringId of the configuration parameter.

8.5. language-section

8.5.1. Introduction

The available languages in the portal. This is the basic configuration needed for internationalization. The currently selected language of the user can be read and set with the portal property path portal.language.id. See Section 8, “Portal Property Paths” for Details on property paths.

Example 3.8. Structure of the language-section

<language-section>
  <languages default="...">
    <language id="..." locale="..."/>
    ...
  </languages>
</language-section>
					

8.5.2. Configuration

Table 3.41. Configuration of Languages

NameTypeDescription
languagesStructureBase node for the language definitions.
languages.defaultStringId of the default language.
languageNodeA single language definition.
language.idStringId of the language definition.
language.localeStringLocale of the language definition. The locale may consist of up to three parts, separated by '_' (underscore):
  1. lowercase two-letter ISO-639 code of the language

  2. uppercase two-letter ISO-3166 code of the country

  3. vendor and browser specific code for the variant

Examples: use de for German, de_AT for Austria, de_DE for Germany, en for English, en_GB for UK, en_US for US, ... See http://java.sun.com/j2se/1.4.2/docs/api/java/util/Locale.html for details on Locales.

8.5.3. Dictionaries

For implementation details, see Section 12.2, “Language Handling”.

8.5.3.1. Syntax

The basic Syntax of dictionary files is key=value. Note that if the key contains spaces, they have to be escaped with \. Also if the value contains newlines, they have to be escaped in the same way.

Example 3.9. Example dictionary

welcome\ text=Welcome,\
this is Gentics Portal.Node brought to you by $name.
custom.diclaimer2=All my rights reserved.
						

The values may contain variables in the syntax $[a-zA-Z0-9]+, which might be filled with dynamic data.

8.5.3.2. Package Dictionaries

The package dictionaries are located at ${com.gentics.portalnode.home}/META-INF/dictionaries/portal.[languageid].property , are maintened by Gentics and should not be changed. Changes will be lost after the next product update. Changes should be done by creating a custom dictionary file in your configuration path.

8.5.3.3. Custom Dictionaries

Custom dictionaries are located at ${com.gentics.portalnode.confpath}/dictionaries/portal.[languageid].property .

If you want to customize the package dictionary, create an empty file in this directory and add the items you want to customize from the Package dictionary by copy pasting the corresponding lines. It’s not suggested to copy the whole file, since future changes in the package dictionary of uncustomized items will not be visible any more.

If you want to add new items, it’s suggested to do this in a custom section, with a custom prefix, to prevent unintentional overwriting of already existing words.

8.5.3.4. Portlet application Dictionaries

Portletapplication dictionaries are located at /WEB-INF/dictionaries/portal.[languageid].property in the respective portlet application's directory.

Portlet application dictionaries are the means to translate portlet application specific words and package the dictionaries within the portlet application. These dictionaries have higher priority than the package or custom portal dictionaries.

8.6. datasource-section

8.6.1. Introduction

The datasource-section is used to define different datasources that are available to the portal. The datasources are used by the portal modules.

Every datasource has an id, a type and can have one or more handles.

This section is split up into a datasource section and a datasource handle section.

Example 3.10. Structure of the datasource-section

<datasource-section>

   <datasource-handles>
        <!-- the datasource-handles -->
   </datasource-handles>

   <datasources>
        <!-- the datasources  -->
   </datasources>

</datasource-section>
					

8.6.2. Defining datasource-handles

Each datasource handle is defined by an unique id, and typeid and can have several parameters.

8.6.2.1. Handle type sql

This handle type defines datasource handles that provide access to sql-databases. The database connection can be created in two ways: Directly by Portal.Node using jdbc database drivers, or created by the underlying application server and provided as jndi ressources.

[Warning]Warning

When using a handle of type "sql" together with Jakarta Tomcat 5.0 be sure to place the jdbc driver package at {catalina.base}/common/lib/. Otherwise you will not be able to connect to the database.

Table 3.42. Parameters for jdbc connections

NameDescriptionRequiredDefault value
typemust be set to jdbc for poolable connections created by Portal.Node. This is the preferred method of creating database connections. xmust be set to jdbc
driverClassFull qualified class name of the driver class to use for the connection. The jdbc driver package must be located somewhere in the classpath of Portal.Node. Important note for Jakarta Tomcat 5.0: The jdbc driver package must be located in the directory {catalina.base}/common/lib/.x 
urlConnection url to use for connecting to the database. The url may contain system propertiesx 
username Username for connecting to the database. Note: when at least one driver. parameter is set, the username must be given as driver.user and this parameter will be ignored.   
passwd Password for connecting to the database. Note: when at least one driver. parameter is set, the password must be given as driver.password and this parameter will be ignored.   
driver.* Any parameter that is prefixed with driver. will be passed as custom parameter to the JDBC driver (without the prefix driver.).   
pooling.maxActiveMaximum number of active connections in the connection pool. 8
pooling.minIdleMinimum number of idle connections in the connection pool (initial size of the pool). 0
pooling.maxIdleMaximum number of idle connections in the connection pool. If more than maxIdle unused connections exist in the pool, some are closed. 8
pooling.whenExhaustedActionAction to be taken when the pool is exhausted. Must be one of
  • block the client will block and wait for a free connection.

  • fail the request for a connection will fail immediately.

  • grow the pool will grow (a new connection is created).

 block
pooling.maxWaitThe maximum amount of time (in millis) the client will wait for a free commection when the pool is exhausted and whenExhaustedAction is block. -1 will wait forever. -1
pooling.testOnBorrowWhether a connection should be checked before given to the client. false
pooling.testOnReturnWhether a connection should be checked when returned to the pool. false
pooling.testWhileIdleWhether idle connections in the pool should be checked regularly by the idle object evictor thread. false
pooling.timeBetweenEvictionRunsMillisThe number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.. -1
pooling.numTestsPerEvictionRunThe number of objects to examine during each run of the idle object evictor thread (if any). 3
pooling.minEvictableIdleTimeMillisThe minimum amount of time in milliseconds an object may sit idle in the pool before it is eligable for eviction by the idle object evictor (if any). 3600000 (30 minutes)
pooling.validationQueryThe query to be used to validate connections. Should at least return one row. null
shutDownCommand The command (query) to be sent to the database when the handle is closed during the shutdown of Gentics Portal.Node . This has to be set dependent on the database type.  null
cachedbmetadata With this option, the handle can be configured to cache database metadata, in cases where the database structure does not change in runtime, and multiple calls to the method getMetaData() of the JDBC connector leads to performance problems.  false
dbschema This specifies the dbschema name to be used when fetching the database metadata. If left empty, no schema name will be used to get the database metadata (default).  null
[Note]Note

All pooling parameters may also be used without the prefix pooling. , but the new syntax with prefix is encouraged.

[Warning]Warning

When at least one driver. parameter is set, the parameters username and passwd will be ignored and the login data must be given as driver.user and driver.password .

Example 3.11. Example of a jdbc datasource-handle

<datasource-handle typeid="sql" id="sample">
  <parameter name="type">jdbc</parameter>
  <parameter name="url">
    jdbc:hsqldb:${com.gentics.portalnode.home}/WEB-INF/config/db/sample
  </parameter>
  <parameter name="driverClass">org.hsqldb.jdbcDriver</parameter>
  <parameter name="driver.user">sa</parameter>
  <parameter name="shutDownCommand">SHUTDOWN</parameter>
</datasource-handle>
						

Table 3.43. Parameters for jndi connections

NameDescriptionRequiredDefault value
typemust be set to jndi for jdbc connections provided by the underlying J2EE application server xmust be set to jndi
nameName under which the DataSource is bound to the JNDI context (excluding the prefix).x 
contextContext under which the DataSource is bound. java:comp/env
shutDownCommand The command (query) to be sent to the database when the handle is closed during the shutdown of Gentics Portal.Node . This has to be set dependent on the database type.  null

Example 3.12. Example of a jndi datasource-handle

<datasource-handle typeid="sql" id="sample">
	<parameter name="type">jndi</parameter>
	<parameter name="name">jdbc/sample</parameter>
</datasource-handle>
						
8.6.2.2. Handle type ldap

This Handle type provides access to an LDAP server.

Table 3.44. Parameters for ldap Handles

NameDescriptionRequiredDefault value
hostHost of the LDAP server. localhost
portPort number of the LDAP server. 389
binddnDN to use for binding to the LDAP server for authentication.x 
passwordPassword to use for binding to the LDAP server for authentication.x 
scopeScope for searches in the LDAP. Must be one of base|one|sub. one
poolsizeSize of the connection pool. 20
timeoutTimeout in ms before the access fails. 5000
sockettimeoutTimeout in ms before connecting or reading from the socket fails. 5000

8.6.3. Defining datasources

A datasource is defined by an ID, a datasource type and one or more datasource handles. Readonly datasources support the usage of multiple datasource handles. Additionally for some datasource types, parameters may be defined.

[Note]Note

The datasource ID may not be set to false.

Example 3.13. Datasource examples

<datasources>
  <datasource id="sample" typeid="contentrepository">
	<parameter name="versioning">false</parameter>
	<parameter name="versioning.autoupdate.interval">60</parameter>
	<handles>
	  <handle>sample</handle>
	</handles>
  </datasource>
  <datasource id="ldap" typeid="ldap">
    <parameter name="binddn">ou=MyApplications,dc=mycompany,dc=com</parameter>
    <handles>
      <handle>ldap_connection1</handle>
      <handle>ldap_connection2</handle>
      <handle>ldap_connection3</handle>
    </handles>
  </datasource>
<datasources>
					

Table 3.45. General Parameters for datasources

NameDescriptionDefault
backgroundvalidation Whether the connectivity of handles shall be checked periodically in the background. This option is only available when more than one handle is configured for the datasource. When the background validation is activated and more than one handle is configured for the datasource, all handles are checked every backgroundvalidation.interval ms (default: 10 minutes). When a invalid handle is detected (e.g. the server cannot be reached) the handle is taken out of service, until it is checked again after the configured interval. true
backgroundvalidation.interval Interval in milliseconds for the background checking of handles. 600000 (10 Minutes)
8.6.3.1. Datasources of type contentrepository

Datasources of type contentrepository provide access to sql-based databases that must follow a strict database-scheme. See Section 4.3, “ContentRepository” for more details. These datasources can only use handles of type sql and allow

  • Runtime manipulation of objects and attributes stored in the repository

  • Multivalue attributes

  • Storing of binary data

Datasources of type contentrepository support cache warming, which pre-loads configured objects and attributes into the cache. This is in contrast to standard caching, which does not load and cache these items until they are used for the first time.

Additionally, datasources of type contentrepository also allow filesystem attributes, which moves stored data from the databank to the file system. This allows for streaming of large files and can lead to better performance. In order to activate this option, the attribute.path parameter must be set, which is the absolute path to the base folder where the attributes will be stored.

Table 3.46. Parameters for datasources of type contentrepository

NameDescriptionDefault
versioningWhether versioning shall be used for this datasource.false
versioning.autoupdate.intervalThe interval in seconds for the autoupdate job which performs future changes (when versioning is set to true).60
cache With this parameter, the datasource cache can be switched on. Datasource cache will increase performance when accessing objects coming from this datasource.false
cache.synccheckingWhen enabling the datasource cache for datasources that are filled by Gentics Content.Node;, you should set this to true . When syncchecking is enabled, Gentics Portal.Node checks frequently for an updated contentrepository and will clear all relevant caches.false
cache.syncchecking.interval Interval in seconds for background checks whether the updatetimestamp of a Content Repository has changed (when cache.syncchecking is enabled). 10
cache.syncchecking.differential When the datasource parameters cache and cache.syncchecking are enabled for this datasource, setting this parameter to true will modify the behaviour of clearing the caches when datasource modifications are detected: By default, all datasource caches (queries, objects, attributes) are cleared, but with differential syncchecking, only the modified objects (and their attributes) are removed from the cache (together with all query results). true
cache.attribute.[attributename] When caching for this datasource is activated, all attributes would be cached. With this setting, the caching for the attribute attributename can be deactivated. true
cache.attribute.[attributename].region With this parameter, the cache region for attribute attributename can be defined. This can be used to have better control of how specific attributes will be cached. gentics-portal-contentrepository-atts
cache.foreignlinkattributesSetting this parameter to true will enable the caching also for foreign link attributes (when the cache is enabled at all). This should not be done for writeable datasources, because the cache for foreign linked attributes can not be dirted correctly and this will most likely lead to inconsistent cache data. If you use caching for a datasource filled from Gentics Content.Node; and have cache.syncchecking set to true, you should also set cache.foreignlinkattributes to true.false
cache.warming.onInit Enable true or disable false cache warming on startup. true
cache.warming.filter Filter used to determine which objects should be cached. If a syntactically incorrect filter is configured, cache warming will be disabled. true
cache.warming.attributes Comma-separated list of attributes to be cached. If no attributes are specified, cache warming will be disabled. Furthermore, if a syntactically incorrect list is entered, cache warming will also be disabled. empty
attribute.path The absolute path to the folder that should be used to store file system attributes (additional subfolders will be created here). empty
sanitycheck Enable/disable the sanitycheck of the datasource handles on startup. When the sanitycheck is enabled (default), Gentics Portal.Node checks the database structure (tables and columns) of all datasource handles upon startup of the server. true
sanitycheck2 Enable/disable the extended sanitycheck of the datasource handles on startup. When the sanitycheck2 is enabled (default is disabled), Gentics Portal.Node performs extended checks on the database structure. When an incompatibility is found, the datasource will not be available (and error messages will be found in the server logs). false
autorepair Flag to overwrite the global autorepair setting. See “Datasources Configuration” (Section 8.2.12) for details on auto repair. Do not overwrite the global setting
compatibility.integerasstring Compatibility setting for treating attributes of type 3 (Integer) as Strings. This should only be turned on, when this old and deprecated behaviour is required by the implementation. false
setUpdatetimestampOnWrite

When this flag is set to true, every insert/update/delete on the datasource will also update the timestamp lastupdate in the table contentstatus. This setting in conjunction with the parameters cache and cache.syncchecking can be used to synchronize caches between multiple Gentics Portal.Node instances that write into the same datasource.

Note: This flag should not be used in the CRSync process (because the CRSync updates the lastupdate timestamp once the synchronization is done, regardless of this flag).

Note: For performance reasons it is recommended to set the flag cachedbmetadata for the datasource handle (see “Handle type sql ” (Section 8.6.2.1) for details).

false
prefetchAttribute.threshold This parameter modifies the behaviour for attribute prefetching when the datasource uses caches. See “Attribute Prefetching” (Section 4.3.3) for an explanation of how the attribute prefetching works and can be configured. 1000
prefetchAttribute.cacheMissThreshold This parameter modifies the behaviour for attribute prefetching when the datasource uses caches. See “Attribute Prefetching” (Section 4.3.3) for an explanation of how the attribute prefetching works and can be configured. 100
prefetchAttribute.cacheMissThresholdPerc This parameter modifies the behaviour for attribute prefetching when the datasource uses caches. See “Attribute Prefetching” (Section 4.3.3) for an explanation of how the attribute prefetching works and can be configured. 20
autoprefetch Enabling this feature will have some or all (depending on the setting of autoprefetch.attributes ) optimized attributes be prefetched with a single sql statement. false
autoprefetch.attributes Comma separated list of optimized attributes that will be autoprefetched, when autoprefetch is set to true . Leaving this empty will autoprefetch ALL optimized attributes. [empty] (prefetch all optimized attributes)
8.6.3.2. Datasources of type ldap

The LDAP datasource currently provides only read access to the ldap attributes. Writing is currently not supported.

[Note]Note

When displaying results from an LDAP datasource, you need to make sure a Rule is set. - To show everything you could use

(objectClass=*)

to select all.

Table 3.47. Parameters for datasources of type ldap

NameDescriptionDefault
searchDNSearchBaseDN for searches in the datasource.NULL
scopeScope for searches in the datasource. Must be one of base|one|sub.take setting from handle.
maxResultsThe maximum number of records this LDAP datasource will ever return. (0 for unlimited)1000
cacheWith this parameter, the datasource cache can be switched on. Datasource cache will increase performance when accessing objects coming from this datasourcefalse
dnattribute Name of the attribute that will hold the DNs of the fetched LDAP entries. The DN is the unique identifier of an entry in LDAP. To successfully obtain the DNs of LDAP entries, this parameter must be set to an attribute name that does not yet exist as attribute in LDAP itself. name
binaryattributes Comma separated list of LDAP attributes that contain binary data. If an attribute with binary data is fetched from LDAP and not listed here, the output is non deterministic. [empty]

8.7. template-section

8.7.1. Introduction

The template-section contains configuration for the Gentics Template Engine 2. This configuration consists of four parts:

  1. General parameters

  2. Implementation specific parameters (velocity)

  3. Template loaders

  4. Portal-wide template definitions

Example 3.14. Syntax of the template-section

<template-section>
  <velocity-parameters>
    <parameter id="...">...</parameter>
    ...
  </velocity-parameters>
  <parameters>
    <parameter id="...">...</parameter>
    ...
  </parameters>
  <template-loaders>
    <template-loader id="...">
      <class-name>...</class-name>
      <parameters>
        <parameter id="...">...</parameter>
        ...
      </parameters>
    </template-loader>
    ...
  </template-loaders>
  <templates>
    <template loader="...">
      <classes>
        <class id="...">...</class>
        ...
      </classes>
      <parameters>
        <parameter id="...">...</parameter>
        ...
      </parameters>
      <source>...</source>
    </template>
    ...
  </templates>
</template-section>
					

8.7.2. General Parameters

The overall behaviour of the TemplateEngine2 can be configured with the general parameters.

Table 3.48. General Parameters of the TemplateEngine2

NameDescriptionDefault
portletapp.loader.modificationCheckInterval Modification check interval in seconds for all portletapplication template loaders (these are the template loaders which are addressed by gentics.porletapp). Set to -1 for no modification check (recommended for production systems). -1
velocity.allow_caching

Parameter to enable caching of parsed velocity templates.

[Note]Note

This option requires the StringResourceLoader and it will use the cache region:

gentics-velocity-template-processor.

Please make sure to have the following velocity-parameters defined:

<!-- Remove line wraps ! -->
<parameter 
  id="string.loader.description">
    String Resource Loader
</parameter>
<parameter 
  id="string.resource.loader.class">
org.apache.velocity.runtime.resource
    .loader.StringResourceLoader
</parameter>
<parameter id="resource.loader">
  string
</parameter>
<parameter id="input.encoding">
  UTF-8
</parameter>
                        	        
false

8.7.3. Template Loaders

Template loaders define how templates can be loaded.

8.7.3.1. Portletapplication Template Loader

For every deployed portlet application, there will automatically exist a portlet application template loader that loads templates from files in the directory /WEB-INF/templates from within the portlet application's context path. This portlet application template loaders are addressed with the loaderid = gentics.portletapp and can only be used in template definitions in the respective portlet application.

[Note]Note
Since the loaderid = gentics.portletapp is reserved for the portlet application template loaders, it is not possible to define a custom template loader with this id.
8.7.3.2. FileLoader

The FileLoader is implemented by the class com.gentics.portalnode.templateengine.loader.FileLoader and loads templates from files, relative to a base directory.

Table 3.49. Parameters of the FileLoader

NameDefaultDescription
path(required)Base path of the FileLoader. The pathname might (and should) contain system properties. See Section 2, “System properties” for details on the available system properties.
modificationCheckInterval -1Interval (in seconds) between checks for file changes. Set to -1 for no check changes (recommended for production environments), 0 for checks on every access to the templates.

Table 3.50. Template parameters for Templates loaded from the FileLoader

NameDefaultDescription
filename(required)Path of the template file, relative to the path configured with the FileLoader.

8.7.4. Template definitions

The configuration of templates consists of two parts:

  1. The Classification to defined what the template is used for (which component will use this template).

  2. The loader and parameters to locate the template or the source of the template itself.

Example 3.15. Syntax of a template definition

<template loader="...">
  <classes>
	<class id="...">...</class>
	...
  </classes>
  <parameters>
	<parameter id="...">...</parameter>
	...
  </parameters>
  <source>...</source>
</template>
					

Table 3.51. Configuration parameters for a template definition

NameTypeDescription
loaderStringId of the template loader to locate the template source.
classesStructureXML Structure of the template classification.
classNodeOne part of the classification. The value is the node value.
class.idStringKey of the classification part.
parametersStructureXML Structure defining the template parameters needed to locate the template with the template loader. See Section 8.7.3, “Template Loaders” for additional information.
parameterNodeOne parameter for the template loader.
parameter.idStringKey of the parameter. Available keys depend on the used template loader and are described there.
sourceStringSource of the template, when it could not be located using the template loader, or no loader was given at all.

See Example 4.6, “ViewPlugin Template Customisation Example” for an example.

8.8. administration-section

8.8.1. Introduction

The administration section holds necessary configuration for administrative purposes such as the deployer used by the AdministrationPortlet to deploy portletapplications.

Example 3.16. Syntax of the administration-section

<administration-section>
  <deployer>
    <class-name>...</class-name>
    <parameters>
      <parameter id="...">...</parameter>
      ...
    </parameters>
  </deployer>
</administration-section>
					

8.8.2. Deployer

A deployer is a java class the implements the functionality needed to deploy/undeploy portletapplications on the underlying Web Application Server. The configuration consists of the class-name and specific parameters.

8.8.2.1. TomcatDeployer

The TomcatDeployer is the deployer used for Jakarta Tomcat. It is implemented by the class com.gentics.portalnode.genericmodules.admin.TomcatDeployer.

Table 3.52. Parameters for TomcatDeployer

NameTypeDescription
managerUsernameStringUsername of a Tomcat user role manager. For details on creation of Tomcat users see http://tomcat.apache.org/tomcat-5.5-doc/index.html .
managerPasswordStringPassword of the Tomcat user
managerUrlStringURLURL to access the Tomcat manager application. Typically of the form http://[hostname]:[port]/manager (NOT http://[hostname]:[port]/manager/html !)
appBaseStringPath to the base directory of webapplications. May contain system properties. Typically ${catalina.base}/webapps .

8.9. pages-section

8.9.1. Introduction

The pages-section contains the configuration of the portal pages.

Example 3.17. Syntax of the pages-section

<pages-section>
  <parameters>
    <parameter id="...">...</parameter>
    ...
  </parameters>
  <pages>
    <page id="...">
      <rule>...</rule>
      <properties>
        <property id="...">...</property>
        ...
      </properties>
      <positions>
        <position id="..." defaultwindowstate="..." allowedwindowstates="...">
          <portlets>
            <portlet id="..." windowstate="..."/>
            ...
          </portlets>
        </position>
        ...
      </positions>
    </page>
    ...
  </pages>
</pages-section>
					

Table 3.53. Configuration parameters for the pages definition

NameTypeDescription
parametersNodeDefinition of general portal pages parameters.
parameters.parameterStringThe value of a single parameter.
parameters.parameter.idStringId of the portal page parameter (must be unique within all portal page parameters).
pagesNodeConfiguration of the portal pages.
pages.pageNodeConfiguration of a single portal page.
pages.page.idStringId of the portal page (must be unique within all portal pages).
pages.page.ruleString Optional rule to determine accessibility of the portal page. When a portal page has a rule configured, the portal page will only be visible and accessible when the rule matches.
pages.page.propertiesNodeOptional set of properties of the portal page.
pages.page.properties.propertyStringValue of a single portal page property.
pages.page.properties.property.idStringId of the portal page property.
pages.page.positionsNodeConfiguration of the positions within the portal page.
pages.page.positions.positionNodeConfiguration of a single position within the portal page.
pages.page.positions.position.idStringId of the position. Must be unique within the positions of this portal page.
pages.page.positions.position.defaultwindowstate String The default windowstate for portlets in this position. If not specified, the default windowstate is normal
pages.page.positions.position.allowedwindowstates List of Strings (separated by spaces) List of allowed windowstates for portlets in this position. When not specified, all windowstates are allowed in this position. Any attempt to change the windowstate of a portlet to a restricted value will not modify the windowstate at all. The portal.events.portlet.onBeforeWindowStateChange event will be triggered, but not the portal.events.portlet.onWindowStateChange event. See “Portlet events” (Section 3.5) for details about the events.
pages.page.positions.position.portletsNodeConfiguration of the portlets contained in the position.
pages.page.positions.position.portlets.portletNodeConfiguration of a single portlet contained in the position.
pages.page.positions.position.portlets.portlet.id String

Id of the portlet as defined in a <pnode> in the portal template. See “PNodes” (Section 11.1.3) for details on definition of portlets.

pages.page.positions.position.portlets.portlet.windowstateStringWindowstate of the portlet in the position.

8.9.2. General Parameters for portal pages

Table 3.54. 

NameDescriptionDefault
store

When this parameter is set, the portal server will try to store the possibly customized portlet positions on portal pages, when the user session is invalidated (for example when the user logs out). The portlet positions are serialized into a xml representation and then assigned to the object defined by this parameter.

Typically, this parameter will be set to something like portal.user.customizedsettings , to store the customized settings into the user content repository, when using a PNAuthenticationManager .

When a new session is created (for example, when the user logs in), this value is read and merged with the configuration of the portlet positions.

It is also possible to store the current portlet position prior to logout by reading the property path portal.pagesetting and setting this into e.g. portal.user.customizedsettings (or whatever property is defined as store). See “Portal Property Paths” (Section 8) for details about portal property paths.

See “Persisting and restoring customized portlet positions” (Section 14.4) for details on how persistence of portlet positions works.

null (no storing of portlet positions)
store.rule

Expression which defines the rule to determine, whether storing/restoring of portlet positions shall be performed.

A typical implementation would set this to portal.user.isloggedin to store portlet positions only for logged in users.

true

[Note]Note
Implementation note: Every position in a page may contain each portlet only once.

8.10. urlmapping-section

8.10.1. Introduction

The urlmapping-section allows configuration of "Beautiful URLs" which are URLs that look like those used for serving static files. For example

http://www.gentics.com/Portal.Node/portal/?gentics.rm=LoginModule

can be transformed to:

http://www.gentics.com/Portal.Node/portal/LoginModule

This is achieved by mapping the parameters to entries in the URL. This allows "Beautiful URLs" on the portal layer transparent to the actual portlet. This feature needs to be activated with a portal parameter (see Section 8.2.16, “URL Mapping Configuration (Beautiful URLs)” ).

An URL mapping describes the transformation of parameters to entries and vice versa. It defines which parameter is mapped to a certain position in the generated URL. Multiple different mappings can be defined. When a URL is generated or parsed the appropriate mapping is chosen. This decision is based on the parameters and on the order of the mapping entries. The most precise mapping should be definded in the first entry. If that mapping is not applicable the next one will tried and so on.

[Note]Note

Naming: given the URL http://www.gentics.com/Portal.Node/portal/content/pub/directory/file.html

  1. http://www.gentics.com/: The protocol and host name for the URL. These are currently completely ignored for beautiful URLs.
  2. /Portal.Node: The Context Path under which the web application is registered in the application server. (Also not used for url mappings.)
  3. /portal: The Servlet Path, which is used to route the request to the Portal.Node PortalServlet. Other possible values would be public or secure. (Also not used for url mappings.)
  4. content/pub/directory/file.html: Pathinfo which consists of multiple entries that are separated by slashes.

When a URL is rendered, the parameters are analyzed to determine whether an appropriate URL mapping can be applied to transform the parameters to entries in the path.

Beautiful URLs try to stay as simple as possible. It basically takes the whole "pathinfo" (Everything in the URL after the context path but before the query string) and separates it into single "segments". (A segment is everything between two slashes (/) within a pathinfo.) Afterwards it matches these segments against the urlmapping configuration from top to bottom. Once a matching urlmapping is found all segments are mapped to the corresponding request parameters and stored in the servlet request which will then be transparently read by Gentics Portal.Node and all portlets.

The main difference between Beautiful URLs and “Bookmarkable URLs” (Section 8.2.22) is that Beautiful URLs work in both directions. Every Portlet URL which is generated will be matched against the urlmappings to create Beautiful URLs.

Example 3.18. Syntax of the urlmapping-section

<urlmapping-section>
	<parameters>
		<parameter id="...">...</parameter>
	</parameters>
	<mapping>
		<pathtransformation>
			<segment>static</segment>
			<segment urlparameter="..." greedy="..." />
			...
			<hidden urlparameter="..">...</hidden>
			...
		</pathtransformation>
		<parameters>
			<parameter id="...">...</parameter>
			<parameter id="..."><expression>...</expression></parameter>
		</parameters>
	</mapping>
</urlmapping-section>

				

Table 3.55. Configuration section for the urlmapping definition

NameTypeDescription
parametersNodeParameters for all url mappings. See Table 3.56, “Parameters for url mappings”
mappingNodeRepresents one url configuration.
mapping.pathtransformationNodeDefines, how the transformation from the original url to the path of the beautiful url will be done. Of course this implicitly also defines how incoming beautiful urls will be parsed and re-transformed into the original urls.
mapping.pathtransformation.segmentNode A segment entry represents one part of the url between two slashes. It can be either defined using a static content, or dynamically mapped to a request parameter.
mapping.pathtransformation.segment.urlparameterStringName of the request parameter from the original url that shall be mapped to this segment in the beautiful url.
mapping.pathtransformation.segment.greedyBoolean Indicates that this segment can contain one or more slashes (e.g. a directory path). This attribute is optional and there can be at most one greedy segment for each mapping. Furthermore only segments with greedy set to true will match empty URL parameters. (Make sure to check out “Restrictions” (Section 8.10.3)).
mapping.pathtransformation.hidden Node This defines, which request parameters will be hidden from the beautiful url. The definition includes the required value of the request parameter, which means that this mapping will only match, when all urlparameters, that will be hidden have the defined values.
mapping.pathtransformation.hidden.urlparameterStringName of the request parameter, which must have the defined value and will be hidden, when transforming to a beautiful url
mapping.parametersNodeAdditional configuration parameters for this mapping. See Table 3.56, “Parameters for url mappings”
mapping.parameters.parameterString or <expression>Value of the parameter, which can either be static (a String) or an expression.
mapping.parameters.parameter.expressionStringExpression String

Table 3.56. Parameters for url mappings

NameDescription
render.prefix Affects the prefix for rendered urls. It can be configured either separately for every mapping or globally for the whole urlmapping-section. The value can also be an expression (see “ExpressionParser” (Section 10) and “Generation of URLs that do not start with /Portal.Node/portal” (Section 8.10.4)).
[Warning]Warning

Once urlmapping is activated (Section 8.2.16, “URL Mapping Configuration (Beautiful URLs)”) using the portal parameter "Beautiful URLs" are used for all rendered portlet URLs. Because of the way they work this means that all URLs in your portal will be absolute URLs. This means that if your current setup relies on an proxy or anything which transforms incoming URLs you have to be careful and probably use the configuration parameter 'render.prefix' (see “Generation of URLs that do not start with /Portal.Node/portal” (Section 8.10.4) for details). Additionally it has to be noted, that hardcoded relative links to the portal will no longer work as expected and should therefore be made absolute as well.

Example 3.19. URL Config Example


<urlmapping-section>
	<mapping>
		<pathtransformation>
			<segment>content</segment>
			<segment urlparameter="p.pub_dir" greedy="true" />
			<segment urlparameter="p.filename" />
			<hidden urlparameter="gentics.am">GenticsContentModule</hidden>
			<hidden urlparameter="gentics.pb">GenticsContentModule</hidden>
		</pathtransformation>
	</mapping>
</urlmapping-section>

				

With the above URL mapping configuration the following two URLs are equal:

http://localhost:42880/Portal.Node/portal/content/directory/page.html
http://localhost:42880/Portal.Node/portal
  ?gentics.am=GenticsContentModule
  &gentics.pb=GenticsContentModule
  &p.pub_dir=directory
  &p.filename=page.html

The transformation works as following:

  1. The first segment is a static value.
  2. The next segment is mapped to the value of the urlparameter p.pubdir=directory
  3. And the last segment is mapped to the value of the urlparameter p.filename=page.html
  4. The urlparameter gentics.am=GenticsContentModule is hidden from the generated URL because this mapping defines a fixed value for this urlparameter and both the urlparameter name and value matched. The same applies for the urlparameter gentics.pb

Because the segment for p.pub_dir is greedy this works even if the value of p.pubdir contains slashes:

http://localhost:42880/Portal.Node/portal
  ?gentics.am=GenticsContentModule
  &gentics.pb=GenticsContentModule
  &p.pub_dir=documents/public/pages
  &p.filename=page.html

will be transformed to:

http://localhost:42880/Portal.Node/portal/content/documents/public/pages/page.html
[Note]Note

By default the GenticsContentModule does not generate URLs using pub_dir and filename, but by contentid. Please see Section 4, “GenticsContentModule” for the configuration settings to modify this behaviour.

Your portal configuration can use multiple different URL mappings. Before a URL is rendered (and eventually transformed) a correct mapping must be selected. This is primarily done using the hidden urlparameters, e.g. if the URL didn't have the urlparameter gentics.pb=GenticsContentModule this mapping would not be applicable. Thus the URL will be rendered as usual with all the urlparameters.

8.10.2. Conflicting configurations

The mapping between the original URL and the beautiful URL must be unique and reversable. This ensures that generated beautiful URLs can be transformed back into the correct original URL. The portal server ensures this reversability during generation of beautiful URLs and will not transform a URL if the result would be ambiguous. The following example shows a configuration with conflicting mappings which would lead to ambiguous URLs:

Example 3.20. 

Given the following configuration:

<mapping>
	<pathtransformation>
		<segment urlparameter="p.pub_dir"/>
		<segment urlparameter="p.filename"/>
		<hidden urlparameter="gentics.rm">GenticsContentModule</hidden>
	</pathtransformation>
</mapping>
<mapping>
	<pathtransformation>
		<segment urlparameter="gentics.pb"/>
		<segment urlparameter="gentics.ws"/>
		<hidden urlparameter="gentics.rm">SimpleViewExample</hidden>
	</pathtransformation>
</mapping>

the URL

/Portal.Node/portal?gentics.rm=SimpleViewExample&gentics.pb=main&gentics.ws=maximized

would be transformed using the second mapping into:

/Portal.Node/portal/main/maximized

However the URL

/Portal.Node/portal?gentics.rm=GenticsContentModule&p.pub_dir=main&p.filename=maximized

would also be transformed to

/Portal.Node/portal/main/maximized

As you can see the transformation is not reversible and the generated beautiful URL is ambiguous! It is not possible to restore the original parameters correctly. In case of such conflict the original (not beautiful) URL will be rendered as fallback.

8.10.3. Restrictions

There are a few restrictions regarding the parameters. In case of violation of any of these rules no mapping will be applied and the classic URL will be rendered.

  • Non-greedy segments must not contain any slashes.
  • Greedy segments must not start or end with a slash.
  • Greedy segments must not contain double-slashes.
  • A mapping can have at most one greedy segment.
  • The value of a non-greedy segment must not be empty.
  • If the value contains special characters it will be encoded according to W3C specifications. The only exception are slashes in greedy segments which will be preserved.

[Tip]Tip

During development you might want to enable the logger com.gentics.portalnode.urlmapping.URLMappingConfiguration at level WARN or even DEBUG.

8.10.4. Generation of URLs that do not start with /Portal.Node/portal

In cases, where the generated URLs shall not begin with /Portal.Node/portal , the configuration parameter render.prefix can be used to modify the default behaviour. It can be used in two different ways:

  1. Set the configuration parameter render.prefix to /Portal.Node to generate URLs that do not contain the part /portal (for example /Portal.Node/content/pub/dir/filename.html ). Note that it is compulsive that the entry right after /Portal.Node is none of

    • /portal
    • /public
    • /secure
    • /go
    • /ws
    • /profiler
    • /static

    . The best way to achieve this, is to configure static segments in the first place with different values.

  2. Set the configuration parameter to a completely different value (e.g. /content ). When doing this, it is also necessary to route those URLs to the portal, for example by using a web server in front of the application server, that rewrites the incoming URLs to start with /Portal.Node/portal .

8.10.4.1. Restrictions of the render.prefix

  • The render.prefix must begin with /
  • The render.prefix must not end with /

8.10.5. URL Parameters

To create optimal url mapping configurations it is useful to know the meaning of the URL parameters used by Gentics Portal.Node.

Table 3.57. Gentics Portal.Node URL parameters

NameMeaning
gentics.amUsed for action URLs and contains the id of the portlet.
gentics.rmUsed for render URLs and contains the id of the portlet.
gentics.pbContains the id of the pbox of the URLs target, when no portal pages are used, otherwise the parameter will contain the position id of the portlet.
gentics.ppThe Portal Page which should be rendered. (Usually is only part of the URL when the active portal page is switched.)
gentics.wsThe window state the portlet should be switched to.
gentics.pmThe portlet mode in which the portlet should be rendered.
gentics.tsThe current timestamp used in a few URLs to prevent caching (Should never appear in an url mapping.)
gentics.rltrue for portlet reload requests. The response is not a fully rendered portal page but a JSON object. (See “Portlet Reloading” (Section 6.3.3))
p.*All portlet parameters are prefixed with p. to distinguish them from Gentics Portal.Node specific parameters.