Understanding the Layout Manager

This document explains how the PageSeeder user interface (UI) components, including pages, blocks, and menus, are controlled by the Layout Manager Configuration file (Layout Manager Config 1.4 (obsolete)).

The layout manager is a project-level configuration. So any changes affect all groups in the project.

Overview

The configuration file is an XML file that must be valid against the layout manager DTD. Following are explanations of the main rules: 

• The root element is <layout-config> plus a @version attribute.

• The children elements are the following:

• <content-security-policy> – to specify a Content Security Policy .
• <navigation> – determines the tabs at the top of the page.
• <blocks>, <dialogs>, <pages> – determines the rest of the interface components.

Following is a example configuration file to illustrate the basic logic of the layout manager.

<layout-config version="1.4">
  <content-security-policy> ... </content-security-policy>
  <navigation> ... </navigation>
  <blocks> ... </blocks>
  <dialogs> ... </dialogs>
  <pages> ... </pages
</layout-config>

Note: Before making any changes to config.xml, read the Developer Guidelines for customizing the user interface.

Content Security Policy

The layout manager can automatically include the Content-Security-Policy HTTP header to all pages based on your configuration.

Content Security Policy (CSP) helps to detect and mitigate certain types of malicious activity, including Cross Site Scripting (XSS) and data injection attacks. By default, PageSeeder excludes any content sourced from other sites.

<content-security-policy>
  <directive name="default-src" value="'self'"/>
  <directive name="script-src"  value="'self' 'unsafe-inline' 'unsafe-eval'"/>
  <directive name="style-src"   value="'self' 'unsafe-inline'"/>
  <directive name="object-src"  value="'none'"/>
  <directive name="img-src"     value="'self' data:"/>
</content-security-policy>

<content-security-policy> element

The <content-security-policy> element is a container for a list of <directive> elements.

<directive> element

The <directive> element defines the directives to include in the security policy. It supports the following attributes.

For example:

<content-security-policy>
  <directive name="default-src" value="'self'"/>
  <directive name="img-src" value="*"/>
  <directive name="media-src"
             value="media.example.org asset.example.net"/>
  <directive name="script-src" value="cdn.example.com"/>
</content-security-policy>

Would automatically send the following header:

Content-Security-Policy: default-src 'self'; 
                         img-src *; 
                         media-src media.example.org asset.example.net;
                         script-src cdn.example.com

(space added for readability)

For more details, see the following:

• Content Security Policy on W3C 
• Content-Security-Policy on the Mozilla developer Network 

Navigation

The navigation element contains a list of <menu> elements that each contain a list of <link> elements.

<menu> element

Each menu supports the following attributes.

<link> elements

Menus contain links which are defined by link elements. <link> elements are empty elements and support the following attributes.

Following are menu examples:

<menu title="Home">
  <link title="My Home" default="true" idref="home" />
  <link title="Group Home" scope="group,project" idref="group-home" />
  <link title="Search" scope="group,project"
        idref="group-search" optional="true" />
</menu>

<menu title="Comments" scope="group">
  <link title="New" idref="group-comment-new" />
  <link title="List" idref="group-comments" default="true" />
  <link title="View" idref="group-comment-thread" optional="true" />
</menu>

Interface components

A PageSeeder interface component can be a block, a dialog or a page. All three components have similar definitions.

Shared attributes

Shared elements

All user interface components can specify the following elements:

• <url> – the URL to access the UI component. There could be more than one url element in a component (and there is at least one).
• <servlet> – there can be zero, one or multiple servlets for each component. They indicate servlets to invoke to produce content that is not included in the generic properties. The servlets are invoked in order.
• <generator> – there can be none, one or multiple generators for each component. They indicate generators to invoke to produce content that is not included in the generic properties. The generators are invoked in order.
• <script> – an optional element, it describes a Javascript file which should be imported when loading the page.

<url> element

This element defines which URL match the parent UI component and contains the following attributes.

Here are examples of url elements:

<url pattern="/document/publish" />
<url pattern="/fullpath/*" />
<url pattern="/path/{+path}" scope="group" />
<url pattern="/labels{;days-ago}/{label}" />

<servlet> element

This element is used to specify a Java Servlet to invoke. The resulting data is then transformed to display the content. It can have the following attributes.

A <servlet> element can have zero or several children parameter elements.

<generator> element

This element is used to specify a PageSeeder generator to invoke. The resulting data is then transformed to display the content. It can have the following attributes.

A <generator> element can have zero or several children parameter elements.

<parameter> element

This element is used to specify a parameter to transmit to a servlet or generator. It can have the following attributes.

Here are a few examples of parameters:

<parameter name="xformat"     value="xml" />
<parameter name="groupName"   value="" />
<parameter name="ps-docPath"  value="{@uri.docpath}"/>
<parameter name="history"     value="{$history}"  default="all"/>
<parameter name="days-ago"    value="{#days-ago}" />

<script> element

This element is used to define a Javascript file used by the component on top of the default scripts for the component.

It contains only one attribute called @src which should contain the name of the script.

The default script file must be located in the script folder:

webapp/weborganic/layout/script/

and the custom script must be in:

webapp/WEB-INF/config/template/[project]/style/layout/script

Example:

<script src="document_view.js"/>

Blocks

Blocks are user interface components that are designed to be included in a page and cannot be displayed on their own.

<block> element

See the following examples:

<block id="document-search-box" scope="group" title="Document search">
  <url pattern="/document/search/box"/>
  <script src="document_search_box.js"/>
</block>

<block id="group-members" scope="project,group,document" title="Members">
  <url pattern="/member/list"/>
  <generator class="com.pageseeder.membership.ListMembersForGroup" />
</block>​​​​​​​

<block id="block-404" title="Not found!">
  <url pattern="/404"/>
</block>

<block-set> element

When the same blocks are displayed consistently on pages, it’s possible to group them in a <block-set> which can be referenced in the page, instead of referencing each block individually.

A <block-set> is a container for a set of <block-ref> elements:

<block-set id="default-set"
  <block idref="group-members"/>
  <block idref="labels">
</block-set>

Dialog

A dialog is similar to a Page except that it is designed to be displayed as a standalone component in a dialog or modal window.

Dialogs are therefore devoid of blocks or navigation components.

<dialog id="dialog-about" title="About PageSeeder" scope="server">
  <url pattern="/about"/>
  <generator class="com.pageseeder.system.About" />
  <generator class="com.pageseeder.publish.About" />
  <generator class="com.pageseeder.search.About" />
</dialog>

Pages

A page includes one or more Blocks using <block-ref> and <blockset-ref> elements. 

As many <block-ref> elements as required are used to specify the Blocks to include on the Page, however, it is easier to manage this by creating, then referencing a blockset using <blockset-ref>.

There is only one attribute on a <block-ref> or <blockset-ref> element and it is required: @idref. It refers to the id of an existing block or block set in the Configuration file (@idref attribute).

Following is an example page listing the comments on a group:

<page id="comments"
      scope="server"
      title="Comments"
      style-id="group-comments">
  <url pattern="/comments"/>
  <generator class="com.pageseeder.comment.GetDiscussions">
    <parameter name="pagesize"       value="{$pagesize}" default="10" />
    <parameter name="page"           value="{$page}" />
    <parameter name="comments"       value="last" />
    <parameter name="returngroups"   value="user"/>
  </generator>
  <script src="lib/jquery.autosize.min.js"/>
  <script src="jquery.psfield.js"/>
  <blockset-ref idref="basic-server-set"/>
</page>

Following is an example of an error page:

<page id="page-404">
  <url pattern="/404"/>
</page>