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:
Provide multiple different variants of presentation. For example one could define two pages, one with two columns, one with three.
Thematically distribute the portlets among several pages (e.g. one page for content presentation, one for administration tasks, etc.)
Serve different virtual portals using the same infrastructure.
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.
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
Class | Required | Description |
---|---|---|
type | x | Must be set to "portalpage". |
portalpage | The portal page id. |
Table 4.171. Template Variables for Portal Page Templates
Name | Type | Description |
---|---|---|
$portal.pages | List | List of all visible portal pages |
$page in $portal.pages | Object | A specific portal page |
$page.id | String | Id of the portal page |
$page.positions | List | Portlet positions of the portal page. |
$page.positions.[positionid] | Object | Portlet position with the id |
$page.positions.[positionid].portlets | List | Ordered list of portlets currently in the position. |
$portlet in $page.positions.[positionid].portlets | String | Renders 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.properties | List | Properties of the page as defined in the portal pages configuration. |
$page.switchUrl | String | URL 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.renderUrl | String | URL 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.page | Object | Current portal page (which must not necessarily be the currently rendered portal page), provides access to further attribute of the current portal page (see above). |
$page | Object | Currently rendered portal page, provides access to further attributes like $page.positions, ... (see above). |
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
Class | Required | Description |
---|---|---|
type | x | Must 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:
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
Name | Type | Description |
---|---|---|
$portlet | Object | The portlet object. Provides access to portlet data. |
$portlet.id | String | Id of the portlet. |
$portlet.title | String |
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
|
$portlet.content | String | The rendered portlet content, or empty, when the portlet is not visible. |
$portlet.titleaction | Object | The titleaction, if one was defined. |
$portlet.actions | Collection | Collection of portletactions |
$action in $portlet.actions | Object | A portletaction object |
$action.id | String |
Id of the action. Is either
|
$action.portletmode | String |
The portletmode for portletmode switching
actions,
|
$action.windowstate | String |
The windowstate for windowstate switching
actions,
|
$action.url | String | URL to activate the action. |
$action.properties.[property id] | String | Property as it was configured either in the pnode or in the defaultactions. |
$action.alt, $action.icon | String | Deprecated elements configured using <icon> tag - This should be replaced by properties. |
$portlet.parameters | Map | Portlet parameters. |
$portlet.parameters.[name] | (various) |
Value of the portlet parameter
|
$portlet.properties | Map | Portlet properties |
$portlet.properties.[name] | (various) |
Value of the portlet property
|
$position.id | String | Id ofthe currently rendered portletposition. |
$position.index | Integer | Index of the portlet in the position, starts with 0. |
This section describes, how portal implementations can allow users to customize the positioning of portlets on portal pages.
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.
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.
To store the new portlet positions, call the
$portal.portletpositionchange
URL and supply
the following parameters:
Table 4.174. Portlet Position Customization URL Parameters
Name | Type | Description |
---|---|---|
gentics.rl | Boolean | True 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. |
positions | List | A list of portlet position IDs which will be updated by this request. |
[portlet position ID] | List | The list of portlet IDs in the order in which they appear in this portlet position. |
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.
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).