The Portal Configuration File is located at
${com.gentics.portalnode.confpath}/default.portal.xml
and contains the basic configuration of the portal server.
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>
Table 3.12. Portal parameters for activation feature
Name | Description | Default |
---|---|---|
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 |
---|---|
For portal server installations, where the
portal parameter
|
Table 3.14. Portal parameters for the Template Engine 2
Name | Description | Default |
---|---|---|
portal.templateengine2.compatibilitymode | True 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 |
The Portlet Template Finder Cache may provide you with a performance gain if a whole lot of component templates are used.
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.
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 |
---|---|
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
Name | Description | Default |
---|---|---|
portal.template.templateengine2 | Whether 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.hiderequesttime | Whether 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:
The portal template is loaded from a Gentics Content.Node; 3.6 content repository.
Table 3.18. Portal parameters for content repository-based portaltemplate
Name | Description | Default |
---|---|---|
portal.template.datasource | Id 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.contentid | Contentid of the portaltemplate. | NULL |
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
Name | Description | Default |
---|---|---|
portal.template.file | Absolute 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 |
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:
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).
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
Name | Description | Default |
---|---|---|
portal.plinkprocessor | Id 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.forceall | If 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 |
Fileupload parameters are mainly used to limit the default maximum fileupload size.
Table 3.21. Portal parameters for fileuploads
Name | Description | Default |
---|---|---|
portal.upload.maxFilesize | Maximum allowed fileupload size in bytes. | 1048576 (1mb) |
portal.upload.sizeThreshold | Uploads larger than the given bytesize will temporarily be stored in the filesystem (repositoryPath. Smaller uploads will be kept in memory. | 4096 (4kb) |
portal.upload.repositoryPath | The path where upload files will temporarily be stored when their size exceed sizeThreshold. | ${java.io.tmpdir} |
ViewPlugin configuration parameters are used to modify the general behaviour of the viewplugin.
Table 3.22. Portal parameters for the viewplugin.
Name | Description | Default |
---|---|---|
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
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 |
Datasources configuration parameters are used to modify the general behaviour of datasources.
Table 3.23. Portal parameters for datasources
Name | Description | Default |
---|---|---|
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
This global setting can be
overwritten for specific
datasources. See
“Datasources of type
| true |
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
Name | Description | Default |
---|---|---|
portal.expressionparser |
When this parameter is set to
| true |
portal.expressionparser.treatEmptyStringAsNull |
When
| false |
Parameters for configuration of general dictionary handling. See “Dictionaries” (Section 8.5.3) for details.
Table 3.25. Portal parameters for Dictionaries
Name | Description | Default |
---|---|---|
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) |
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
Name | Description | Default |
---|---|---|
portal.pages |
With this parameter the multiple
portal pages can be activated.
When set to
| 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 |
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
Name | Description | Default |
---|---|---|
portal.portletreload |
Enables portlet reloading for all portlets. | false |
portal.portletreload.allclasses |
Replace all elements, regardless of CSS class
(see | 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 |
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.
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.
With the following parameters, the aggregation of markup provided by portlets can be configured.
Table 3.31. Portal parameters for markup aggregation
Name | Description | Default |
---|---|---|
portal.headeratend |
When this parameter is set to
| false |
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.
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
).
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>
Table 3.32. Configuration of Authentication Managers
Name | Type | Description |
---|---|---|
authentication-descriptor | Structure | Base node for the definition of authentication managers |
authentication-descriptor.default | String | Id of the default (primary) authentication manager that is used for access management. |
authentication | Structure | Node that defines a single authentication manager. |
authentication.id | String | Id of this authentication manager. must be unique within all authentication manager ids. |
Description | String | Description of this authentication manager. |
class-name | String | Full qualified class-name of the java class that implements the authentication manager. The class must implement the class com.gentics.portalnode.auth.AuthenticationSystem |
parameters | Structure | Definition of the parameters for this authentication manager. |
parameter | Node | Definition of a single parameter for this authentication manager, the value is given as node value. |
parameter.id | String | Id of the parameter to set. |
mapping | Structure | Definition of parameter mappings from the user repository to the portal user parameters. |
map | Node | Definition of a single parameter mapping. |
map.from | String | Original parameter name in the user repository. |
map.to | String | Name of the parameter for the portal user. |
anonymous-user | Structure | Definition for the user profile for the anonymous user. |
domain | Structure | User 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.name | String | Pattern of the hostname to match. May contain * as wildcard for arbitrary characters. |
domain.authentication | String | Id of the authentication manager that is the default for this domain. |
anonymous | Structure | Definition of anonymous user parameter for a given authentication manager. |
anonymous.id | String | Id of the authentication manager. |
anonymous-parameter | Node | Definition of a single anonymous parameter. The value is given as node value. |
anonymous-parameter.id | String | Id of the anonymous parameter. |
Table 3.33. Parameters for all AuthenticationManagers
Name | Default | Description |
---|---|---|
secondaryrule | null | 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.*). |
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 |
---|---|
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
Name | Default | Description |
---|---|---|
userrequestparameter | _PNlogin | Name of the request parameter that holds the login name of the user requesting authentication. |
passwordrequestparameter | _PNpassword | Name of the request parameter that holds the (unencrypted) password. |
logoutrequestparameter | _PNlogouturl | Name of the request parameter that identifies a logout request. |
logoutrequestvalue | true | Value 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. |
userattribute | login | User attribute that holds the login name and therefore identifies the user profile. |
passwordencryption | MD5 | The 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. |
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.
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]
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
Name | Default | Description |
---|---|---|
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. |
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.
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"]]< </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> ...
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
Name | Default | Description |
---|---|---|
collections | NULL |
List of SiteMinder attributes that contain collections of attributes. Separated by ';' The values of the attributes listed here
should follow this structure:
|
authentication_key | SM_UNIVERSALID |
Specifies the header attribute which will be checked to verify if a user is logged in. |
decodeUTF8 | false |
This parameter can be set to
|
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
Name | Default | Description |
---|---|---|
attributescope | session |
When this parameter is set to
|
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
Name | Default | Description |
---|---|---|
url | NULL |
URL to the backend system which
will be used to authenticate the
portal user, e.g.
|
header | NULL |
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:
|
username | NULL |
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).
|
password | NULL |
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).
|
cookie | NULL | Comma separated list of cookie names, that will be forwarded to the authentication request. |
timeout | 5000 | Timeout in ms before getting the connection fails. |
sockettimeout | 5000 | Timeout in ms before connecting or reading from the socket fails. |
connectionretry | 3 | Number of retries for establishing a connection to the authentication URL. |
refreshinterval | 600 | Interval in seconds for keeping the backend session alive. The default is 600s (10 minutes). |
backendLoginRetryInterval | 0 |
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
Name | Description |
---|---|
firstname | First name of the user |
lastname | Last name of the user |
fullname | firstname lastname |
eMail Address of the user | |
description | Description of the user |
login | Login name of the user |
userid | Alias 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 |
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.
Table 3.40. Configuration of imps
Name | Type | Description |
---|---|---|
formatter | Structure | Definition of an imp. |
formatter.id | String | Id of the imp. Must be unique within all imp-ids. |
class-name | String | Full qualified java class-name of the class implementing the imp's features. |
parameters | Node | Configuration parameters for the imp. |
parameter | Node | Value of one configuration parameter. |
parameter.id | String | Id of the configuration parameter. |
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.
Table 3.41. Configuration of Languages
Name | Type | Description |
---|---|---|
languages | Structure | Base node for the language definitions. |
languages.default | String | Id of the default language. |
language | Node | A single language definition. |
language.id | String | Id of the language definition. |
language.locale | String | Locale of the language definition. The locale may consist of up to three parts, separated by '_' (underscore):
|
For implementation details, see Section 12.2, “Language Handling”.
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.
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.
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.
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.
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.
Each datasource handle is defined by an unique id, and typeid and can have several parameters.
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 |
---|---|
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
Name | Description | Required | Default value |
---|---|---|---|
type | must be set to jdbc
for poolable connections created by
Portal.Node. This is the preferred method of
creating database connections. | x | must be set to jdbc |
driverClass | Full 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 | |
url | Connection url to use for connecting to the database. The url may contain system properties | x | |
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.maxActive | Maximum number of active connections in the connection pool. | 8 | |
pooling.minIdle | Minimum number of idle connections in the connection pool (initial size of the pool). | 0 | |
pooling.maxIdle | Maximum number of idle connections in the connection pool. If more than maxIdle unused connections exist in the pool, some are closed. | 8 | |
pooling.whenExhaustedAction | Action to be taken when the pool is
exhausted. Must be one of
| block | |
pooling.maxWait | The 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.testOnBorrow | Whether a connection should be checked before given to the client. | false | |
pooling.testOnReturn | Whether a connection should be checked when returned to the pool. | false | |
pooling.testWhileIdle | Whether idle connections in the pool should be checked regularly by the idle object evictor thread. | false | |
pooling.timeBetweenEvictionRunsMillis | The 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.numTestsPerEvictionRun | The number of objects to examine during each run of the idle object evictor thread (if any). | 3 | |
pooling.minEvictableIdleTimeMillis | The 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.validationQuery | The 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 |
---|---|
All pooling parameters may also be used
without the prefix
|
![]() | Warning |
---|---|
When at least one
|
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
Name | Description | Required | Default value |
---|---|---|---|
type | must be set to jndi
for jdbc connections provided by the
underlying J2EE application server | x | must be set to jndi |
name | Name under which the DataSource is bound to the JNDI context (excluding the prefix). | x | |
context | Context 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 |
This Handle type provides access to an LDAP server.
Table 3.44. Parameters for ldap Handles
Name | Description | Required | Default value |
---|---|---|---|
host | Host of the LDAP server. | localhost | |
port | Port number of the LDAP server. | 389 | |
binddn | DN to use for binding to the LDAP server for authentication. | x | |
password | Password to use for binding to the LDAP server for authentication. | x | |
scope | Scope for searches in the LDAP. Must be one of base|one|sub. | one | |
poolsize | Size of the connection pool. | 20 | |
timeout | Timeout in ms before the access fails. | 5000 | |
sockettimeout | Timeout in ms before connecting or reading from the socket fails. | 5000 |
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 |
---|---|
The datasource ID may not be set to |
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
Name | Description | Default |
---|---|---|
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) |
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
Name | Description | Default |
---|---|---|
versioning | Whether versioning shall be used for this datasource. | false |
versioning.autoupdate.interval | The 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.syncchecking | When 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.foreignlinkattributes | Setting 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
Note: This flag should not be used in the CRSync process (because the CRSync updates the
Note: For performance reasons it is recommended to set the flag | 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) |
The LDAP datasource currently provides only read access to the ldap attributes. Writing is currently not supported.
![]() | 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
Name | Description | Default |
---|---|---|
searchDN | SearchBaseDN for searches in the datasource. | NULL |
scope | Scope for searches in the datasource. Must be one of base|one|sub. | take setting from handle. |
maxResults | The maximum number of records this LDAP datasource will ever return. (0 for unlimited) | 1000 |
cache | With this parameter, the datasource cache can be switched on. Datasource cache will increase performance when accessing objects coming from this datasource | false |
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] |
The template-section contains configuration for the Gentics Template Engine 2. This configuration consists of four parts:
General parameters
Implementation specific parameters (velocity)
Template loaders
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>
The overall behaviour of the TemplateEngine2 can be configured with the general parameters.
Table 3.48. General Parameters of the TemplateEngine2
Template loaders define how templates can be loaded.
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 |
---|---|
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.
|
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
Name | Default | Description |
---|---|---|
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 | -1 | Interval (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. |
The configuration of templates consists of two parts:
The Classification to defined what the template is used for (which component will use this template).
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
Name | Type | Description |
---|---|---|
loader | String | Id of the template loader to locate the template source. |
classes | Structure | XML Structure of the template classification. |
class | Node | One part of the classification. The value is the node value. |
class.id | String | Key of the classification part. |
parameters | Structure | XML Structure defining the template parameters needed to locate the template with the template loader. See Section 8.7.3, “Template Loaders” for additional information. |
parameter | Node | One parameter for the template loader. |
parameter.id | String | Key of the parameter. Available keys depend on the used template loader and are described there. |
source | String | Source 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.
The administration section holds necessary configuration for administrative purposes such as the deployer used by the AdministrationPortlet to deploy portletapplications.
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
.
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
Name | Type | Description |
---|---|---|
managerUsername | String | Username of a Tomcat user role
manager . For details
on creation of Tomcat users see http://tomcat.apache.org/tomcat-5.5-doc/index.html
. |
managerPassword | String | Password of the Tomcat user |
managerUrlString | URL | URL to access the Tomcat manager
application. Typically of the form
http://[hostname]:[port]/manager
(NOT
http://[hostname]:[port]/manager/html
!) |
appBase | String | Path to the base directory of
webapplications. May contain system
properties. Typically
${catalina.base}/webapps
. |
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
Name | Type | Description |
---|---|---|
parameters | Node | Definition of general portal pages parameters. |
parameters.parameter | String | The value of a single parameter. |
parameters.parameter.id | String | Id of the portal page parameter (must be unique within all portal page parameters). |
pages | Node | Configuration of the portal pages. |
pages.page | Node | Configuration of a single portal page. |
pages.page.id | String | Id of the portal page (must be unique within all portal pages). |
pages.page.rule | String | 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.properties | Node | Optional set of properties of the portal page. |
pages.page.properties.property | String | Value of a single portal page property. |
pages.page.properties.property.id | String | Id of the portal page property. |
pages.page.positions | Node | Configuration of the positions within the portal page. |
pages.page.positions.position | Node | Configuration of a single position within the portal page. |
pages.page.positions.position.id | String | Id 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.portlets | Node | Configuration of the portlets contained in the position. |
pages.page.positions.position.portlets.portlet | Node | Configuration 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.windowstate | String | Windowstate of the portlet in the position. |
Table 3.54.
Name | Description | Default |
---|---|---|
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
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
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
| true |
Table 3.55.
Name | Description | Default |
---|---|---|
suppress_gentics_pp |
By setting this parameter to | false |
![]() | Note |
---|---|
Implementation note: Every position in a page may contain each portlet only once. |
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 |
---|---|
Naming: given the URL http://www.gentics.com/Portal.Node/portal/content/pub/directory/file.html
|
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.56. Configuration section for the urlmapping definition
Name | Type | Description |
---|---|---|
parameters | Node | Parameters for all url mappings. See Table 3.57, “Parameters for url mappings” |
mapping | Node | Represents one url configuration. |
mapping.pathtransformation | Node | Defines, 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.segment | Node | 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.urlparameter | String | Name of the request parameter from the original url that shall be mapped to this segment in the beautiful url. |
mapping.pathtransformation.segment.greedy | Boolean | 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.urlparameter | String | Name of the request parameter, which must have the defined value and will be hidden, when transforming to a beautiful url |
mapping.parameters | Node | Additional configuration parameters for this mapping. See Table 3.57, “Parameters for url mappings” |
mapping.parameters.parameter | String or <expression> | Value of the parameter, which can either be static (a String) or an expression. |
mapping.parameters.parameter.expression | String | Expression String |
Table 3.57. Parameters for url mappings
Name | Description |
---|---|
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 |
---|---|
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:
p.pubdir=directory
p.filename=page.html
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 |
---|---|
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.
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.
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.
![]() | Tip |
---|---|
During development you might want to enable the logger |
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:
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
. The best way to achieve this, is to configure static segments in the first place with different values.
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
.
To create optimal url mapping configurations it is useful to know the meaning of the URL parameters used by Gentics Portal.Node.
Table 3.58. Gentics Portal.Node URL parameters
Name | Meaning |
---|---|
gentics.am | Used for action URLs and contains the id of the portlet. |
gentics.rm | Used for render URLs and contains the id of the portlet. |
gentics.pb | Contains 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.pp |
The Portal Page which should be rendered. By adding this parameter, the given Portal Page is rendered, even if it is not the current Portal Page. The current Portal Page will not be changed.
When a Portal Page is rendered with this parameter, all portlet or portal URLs in this page will also contain this parameter, unless the Portal Page property suppress_gentics_pp (see “Properties for portal pages” (Section 8.9.3) for details) is set to true .
|
gentics.ws | The window state the portlet should be switched to. |
gentics.pm | The portlet mode in which the portlet should be rendered. |
gentics.ts | The current timestamp used in a few URLs to prevent caching (Should never appear in an url mapping.) |
gentics.rl | true 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. |