Gentics Navigation Portlet Documentation
Here you can find documentation about the Gentics Navigation Portlet
Overview
The Gentics Navigation Portlet is able to display a structured form of the folders from the Gentics Content.Node System.
With a velocity template the behaviour and look and feel of the portlet can be configured.
Configuration
Configuration file is located in the portletsuite-config module at:
\src\main\resources\config\rest\navigation{instanceNumber}.properties
The main part of the config are parameters for the Content Connector RequestProcessor of the portlet. You can find documentation for that in the Content Connector Wiki
Velocity Tools (since 1.0.3)
During the velocity evaluation you have access to the base velocity tools implementations in the context
$tools
Here you can find the available tool implementations.
Example:
#set($input = "hello & velocity")## #set($output = $tools.esc.html($input))## $output## returns "hello & velocity"
Navigation Caching
In order to be able to handle big navigation objects with good performance results there is the possibility to enable a JCS Cache. Generally the configuration of the cache works like the Gentics Content Connector cache system.
The cache region is gentics-portletsuite-navigation
Example cache configuration in the cache.ccf file. This file has to be found in the root of the configured gentics config path:
## cache region for Gentics Portlet.Suite navigation portlets jcs.region.gentics-portletsuite-navigation= ## max elements in cache jcs.region.gentics-portletsuite-navigation.cacheattributes.MaxObjects=1000 ## cache time for navigation objects jcs.region.gentics-portletsuite-navigation.elementattributes.MaxLifeSeconds=3600
New since 1.0.7:
By default the NavigationCache now polls the requested Navigation Object in the background by generating a ScheduledThreadPoolExecutor instance that frequently updates the cache objects before the they are marked as invalid. After one initial request for a navigation object there will be no more blocking cache fetching operations.
For that cache there is a new configuration file that has to be located in the default setup path under {com.gentics.portalnode.confpath}/rest/navigationcache.properties:
# specifies the amount of available threads in threadpool for the background navigation fetch jobs threads=2 # specifies the period in seconds before the maxLifeSeconds cache invalidates and the # background navigation job should refetch the navigation object: # maxLifeSeconds - secondsbeforecache = scheduletime # maxLifeSeconds of the JCS Cache region "gentics-portletsuite-navigation" # scheduleTime will be given to the thread pool executor as delay time secondsbeforecache=20
Navigation Rendering
The navigation will be rendered with a configured Velocity template (see parameters below). The available velocity variables are
$request ## the Portlet request $response ## the Portlet response $listtool ## velocity tools list tool $nav ## the navigation object that holds the data $nav.object ## the current navigation object with its attributes ($nav.object.name etc...) $nav.subtree ## the subtree that recursively calls this template for its children (should not be used in performance critical situations. Use a recursive macro that calls $nav.obj.childRepository instead.)
Parameters in the properties file
| Parameter | Type | Description |
|---|---|---|
| startfolder | String | This is the contentId of the startfolder of the Navigation portlet instance. If there is no contentId set by clicking a link or a menu element, the portlet will display this content, e.g. on the first access to a portal page. |
| templatepath | String | This is the path to the velocity template file this portlet instance should use. The template file can be anywhere on the server but it recommended to store it in the configuration folder. |
| rootattribute | String | With this parameter you can define an attribute that should be read from the main content page (displayed by the content portlet) in order to switch
the navigation tree from one node to another. With this functionality it is possible to display a specific navigation for every content page. The navigation instance will allways check for an appended root attribute if it is set. Note: in order to publish those attributes correctly into the content repository there has to be a correct entry in the Gentics Content.Node tag map system. |
| attributes | String | With this parameter there can be defined a custom list of comma separated attributes that should be obtained from the navigation objects fetched by the Content Connector.
When you specify an attribute here you can access it in the navigation template via $nav.object.{attributename}. Note: in order to publish those attributes correctly into the content repository there has to be a correct entry in the Gentics Content.Node tag map system. |
| navigationcache | Boolean | enables the JCS Cache as described here |
If you are changing the configuration don`t forget to rebuild it and eventually redeploy it to your server as described in the setup guide.
Architecture
Javadocs for Class: BaseNavigationPortlet