14. Portal Pages Implementation

The use of Portal Pages provide an alternative to the single portal template file for implementing portals. Every request to the portal will render exactly one portal page which aggregates a set of portlets that are placed in so-called "positions" on that page.

Positions allow grouping portlets for layout purposes. Typically, every position on a portal page will consume a specific part of the page (e.g. the left column, the right column and the focus in the center of the page).

Portal Pages can be used for several purposes:

From the administrative point of view, portal pages allow a strict separation between portlet definition (see “Portlet Entities Configuration” (Section 13) ), portlet aggregation (see “pages-section” (Section 8.9) ) and the layout, which is defined in templates for the Template Engine2.

Last but not least, the complete rendering of a portal page is now based on the Template Engine2, which significantly improves the rendering performance.

14.1. Portal Page Templates

The portal page templates define the layout of portal pages and portlet frames. By classification of the templates, it is possible to have portlets be rendered differently, depending on the page, position, windowstate, portletmode and some other parameters.

Example 4.57. Portal Page Template Classification

<classes>
  <class id="type">portalpage</class>
  <class id="portalpage">...</class>
</classes>
				

Table 4.170. Portal Page Template Classes

ClassRequiredDescription
typexMust be set to "portalpage".
portalpage The portal page id.

Table 4.171. Template Variables for Portal Page Templates

NameTypeDescription
$portal.pagesListList of all visible portal pages
$page in $portal.pagesObjectA specific portal page
  $page.idStringId of the portal page
  $page.positionsListPortlet positions of the portal page.
  $page.positions.[positionid]Object

Portlet position with the id [positionid].

  $page.positions.[positionid].portletsListOrdered list of portlets currently in the position.
$portlet in $page.positions.[positionid].portletsStringRenders the portlet with frame.
  $portlet.*(various)

Provides access to the properties as defined in the context for the portlet frame, see “Portlet Frame Templates” (Section 14.2) .

  $page.propertiesListProperties of the page as defined in the portal pages configuration.
  $page.switchUrlStringURL to switch to this portal page (makes it the current portal page). Will fire a portalevent, see “Portal Page events” (Section 3.6) for details.
  $page.renderUrlStringURL to render this portal page, without making it the current portal page. This URL can be used e.g. for rendering different portal pages in popups.
$portal.pageObjectCurrent portal page (which must not necessarily be the currently rendered portal page), provides access to further attribute of the current portal page (see above).
$pageObjectCurrently rendered portal page, provides access to further attributes like $page.positions, ... (see above).

14.2. Portlet Frame Templates

Portlet frame templates define, how the frame around portlet content will look like. Typically the portlet frame templates will contain markup to render the portlet title, portlet action icons and everything else surrounding the portlet content.

In some special situations, it is also necessary to render markup for portlets, which are not visible (but nevertheless contained in a position). For those cases, it is possible to define portlet frames to be used for invisible portlets.

Example 4.58. Portlet Frame Template Classification for visible portlets

<classes>
  <class id="type">portletframe</class>
  <class id="portlet">...</class>
  <class id="portalpage">...</class>
  <class id="windowstate">...</class>
  <class id="style">...</class>
  <class id="position">...</class>
</classes>
				

Example 4.59. Portlet Frame Template Classification for invisible portlets

<classes>
  <class id="type">invisibleportletframe</class>
  <class id="portlet">...</class>
  <class id="portalpage">...</class>
  <class id="windowstate">...</class>
  <class id="style">...</class>
  <class id="position">...</class>
</classes>
				

Table 4.172. Portlet Frame Template Classes

ClassRequiredDescription
typexMust be set to "portletframe" (or "invisibleportletframe").
portlet Id of the portlet.
portalpage Id of the portalpage.
windowstate Windowstate of the rendered portlet.
style Style of the portlet (configured in the pnode in the portaltemplate).
position Id of the position.

When a portlet is rendered in a position of a portal page, the portlet frame is rendered with the best matching template. The optional classification items are considered with the following priority:

  1. portlet
  2. portalpage
  3. windowstate
  4. style
  5. position

A template matching a specific item will always be preferred to other templates matching any number of items with lower priority.

Table 4.173. Template Variables for Portlet Frame Templates

NameTypeDescription
$portletObjectThe portlet object. Provides access to portlet data.
$portlet.idStringId of the portlet.
$portlet.titleString

Title of the portlet as defined in the portlet descriptor. The title will not be internationalized automatically. If you need i18n support for the portlet title, use $portal.i18n($portlet.title) and add the translated portlet titles to your dictionaries.

$portlet.contentStringThe rendered portlet content, or empty, when the portlet is not visible.
$portlet.titleactionObjectThe titleaction, if one was defined.
$portlet.actionsCollectionCollection of portletactions
$action in $portlet.actionsObjectA portletaction object
  $action.idString

Id of the action. Is either windowstate.* (for windowstate actions) or portletmode.* (for portletmode actions) or the defined id.

  $action.portletmodeString

The portletmode for portletmode switching actions, null for other actions.

  $action.windowstateString

The windowstate for windowstate switching actions, null for other actions.

  $action.urlStringURL to activate the action.
  $action.properties.[property id]StringProperty as it was configured either in the pnode or in the defaultactions.
  $action.alt, $action.iconStringDeprecated elements configured using <icon> tag - This should be replaced by properties.
$portlet.parametersMapPortlet parameters.
$portlet.parameters.[name](various)

Value of the portlet parameter name or null if the parameter is not defined or has no value.

$portlet.propertiesMapPortlet properties
$portlet.properties.[name](various)

Value of the portlet property name or null if the property is not defined or has no value.

$position.idStringId ofthe currently rendered portletposition.
$position.indexInteger Index of the portlet in the position, starts with 0.

14.3. Customizing portlet positions

This section describes, how portal implementations can allow users to customize the positioning of portlets on portal pages.

14.3.1. Customizing portlet positions by property setting

It is possible to modify the portlet positions on a portal page by setting various properties. The property path portal.page provides access to the current portal page and via portal.pages.[pageid] it is possible to access and modify properties of any page by its pageid. For a page object, with the property positions.[positionid], one can access the position positionid (if that position exists on the page), and with positions.[positionid].portlets one will get the list of portlets currently contained in the referenced position.

Modification of the portlet positions can be done in one of the following ways (the following code applies for the current portal page, but can easily be changed to modify an arbitrary portal page):

  • portal.page.positions.[positionid].portlets = insert(portal.page.positions.[positionid].portlets, [portletid], -1, true) will insert the portlet [portletid] as last item in the position [positionid]. When the position already contains this portlet is is moved to the end. By using another number instead of -1 as third parameter to the function insert() it is possible to insert the portlet at an arbitrary position (or moved it there).

    Note that it is necessary to assign the result of the insert() function to the position, since the function would not change the list, but return a modified copy of the list of portlets.

  • portal.page.positions.[positionid].portlets -= [portletid] will remove the portlet portletid from the position.

  • portal.page.reset = true will reset the page to the configured portlet positions.

    foreach(portal.pages, "page", page.reset = "true") will reset all pages to the configured portlet positions.

See “Portal Property Paths” (Section 8) for a full list of all available portal property paths.

14.3.2. Customizing portlet positions by URL

It is possible to customize the portlets currently contained in a position of the current portal page by sending a special URL to the portal server. The base URL is provided as $portal.portletpositionchange in every template. This URL can be used to change portlet positions by AJAX Drag'n'Drop. See “Portlet Drag & Drop” (Section 6.3.4) for details and the SDK Demo Portal for an example.

14.3.2.1. Request

To store the new portlet positions, call the $portal.portletpositionchange URL and supply the following parameters:

Table 4.174. Portlet Position Customization URL Parameters

NameTypeDescription
gentics.rlBooleanTrue to return a JSON response as defined in Section 6.3.1, “Response Format of AJAX enabled requests API”, false to render the whole portal page as response.
positionsListA list of portlet position IDs which will be updated by this request.
[portlet position ID]ListThe list of portlet IDs in the order in which they appear in this portlet position.

Example 4.60. Portlet Position Customization URL Example

/Portal.Node/portal?gentics.pa=portletpositionchange&gentics.pb=
&gentics.rl=true&positions=left&positions=right&left=pageselector
&left=helloworld&right=calculator&right=history
						
14.3.2.2. Response

The response to the portlet position customization URL depends on whether the AJAX parameter gentics.rl was set to true or false. When set to false (which is the default value), the current portal page is simply rendered again. When set to true, the response has the same format as the response to a portlet reload request (see Section 6.3.1, “Response Format of AJAX enabled requests API”) and can contain portlet reload data, if portlets need to be reloaded as a result to their new position.

14.4. Persisting and restoring customized portlet positions

By setting the general portal page parameters store and store.rule (see Section 8.9.2, “General Parameters for portal pages” ), the feature for persisting and restoring portlet positions can be activated.

When a user session is invalidated (for example, when the user logs out), the current portlet positions of all pages the user has visited (and possibly customized) will be persisted into the configured object.

When a user session is created, and persisted portlet position data is found in the configured object, the persisted data is merged with the portlet position setting configured in the portal configuration.

  • Persisted data for portal pages, which are no longer present in the configuration are removed (removing of portal pages from the configuration is immediately effective for all users).

  • Persisted data for positions in portal pages, that no longer have them configured are also removed (removing of positions from portal pages by configuration is immediately effective for all users).

  • Persisted data for positions in portal pages that still exist, override the configured setting (which means that configuration changes will not be affective until the user resets his/her customized settings).