PSML

• Page
• Layout Fragments
• Portlet Fragments
• Fragment References
• Fragment Properties
• Portlet Preferences
• Dynamic Page
• Page Template
• Page Fragment
• Fragment Definition
• Folder
• Link
• Global Page Security
• Titles and Metadata
• Defaults
• Security Constraints
• Menus
• PSML Document XML Schemas

PSML is an acronym for Portal Structure Markup Language. It was created to allow content structure and abstraction within Jetspeed. PSML defines how portlets are aggregated, laid out, and decorated on a portal page. Note that page layout is not a part of the Java Portlet Standard API. Thus PSML is a Jetspeed-specific implementation. Also note that PSML in Jetspeed-2 is different from PSML in Jetspeed-1. This document can be used as a reference guide to the elements of a PSML resource.

PSML files capture portal site information related to pages, folders, links, and global security constraints for the portal. PSML elements can be defined in separate documents arranged in a hierarchy of directories in the file system. The folder structure of the PSML documents mirrors the portal URL space. Typically, the PSML root directory is accessed as a resource at /WEB-INF/pages within the jetspeed web application. It is also possible to store PSML definitions in the database; the folder and document arrangement of the PSML hierarchy is maintained there as well.

The following PSML documents/elements are defined below:

Here is an example PSML file for a portal site page, (*.psml):

<?xml version="1.0" encoding="UTF-8"?>
<page>
  <!-- page info -->
  <title>Welcome to Jetspeed 2</title>
  <metadata name="title" xml:lang="fr">Ma Premiere Page de PSML</metadata>
  <metadata name="title" xml:lang="es">¡Bienvenido a Jetspeed 2!</metadata>
  <metadata name="title" xml:lang="hu">Köszönti a Jetspeed 2!</metadata>

  <!-- page decoration -->
  <defaults skin="orange" layout-decorator="tigris" portlet-decorator="tigris"/>

  <!-- page fragments -->
  <fragment id="100393" type="layout" name="jetspeed-layouts::VelocityOneColumn">
    <fragment id="100939" type="portlet" name="j2-admin::LocaleSelector">
      <property name="row" value="0"/>
    </fragment>                                
    <fragment id="100345" type="layout" name="jetspeed-layouts::VelocityTwoColumns">
      <property name="row" value="1"/>
      <property name="sizes" value="33%,66%"/>
      <fragment id="100121" type="portlet" name="j2-admin::LoginPortlet">
        <property name="row" value="0"/>
        <property name="column" value="0"/>
      </fragment>                                
      <fragment id="100171" type="portlet" name="demo::UserInfoTest">
        <property name="row" value="0"/>
        <property name="column" value="1"/>
      </fragment>    
    </fragment>
  </fragment>

  <!-- security constraints -->
  <security-constraints>
    <security-constraints-ref>public-view</security-constraints-ref>
  </security-constraints>
</page>

Here is an example PSML file for portal site dynamic page, (*.dpsml):

<?xml version="1.0" encoding="UTF-8"?>
<dynamic-page content-type="*" inheritable="true">
  <title>Jetspeed 2 Portals Content</title>
  <fragment id="default-content-layout" type="layout" name="jetspeed-layouts::VelocityTwoColumns">
    <property name="sizes" value="80%,20%" />
    <fragment id="default-content-dynamic-content" type="portlet" name="j2-admin::DynamicWebContentPortlet" decorator="gray-gradient-noborder">
      <property name="row" value="0" />
      <property name="column" value="0" />
      <preference name="SRC">
        <value>http://portals.apache.org/</value>
      </preference>
      <preference name="PORTALPATH">
        <value>/content/</value>
      </preference>
    </fragment>
    <fragment-reference id="default-content-wp-reference" refid="wp-definition">
        <property name="row" value="0"/>
        <property name="column" value="1"/>
    </fragment-reference>
  </fragment>
</dynamic-page>

Here is an example PSML file for portal site page template, (*.tpsml):

<?xml version="1.0" encoding="UTF-8"?>
<page-template>
  <title>Portal Template</title>
  <fragment id="template-top" type="layout" name="jetspeed-layouts::VelocityOneColumn">
    <page-fragment id="template-top-page-template">
      <property name="row" value="0"/>
    </page-fragment>
    <fragment id="template-top-login" type="portlet" name="j2-admin::LoginPortlet">
      <property name="row" value="1"/>
    </fragment>                                
    <fragment-reference id="template-top-wp-reference" refid="wp-definition">
      <property name="row" value="2"/>
    </fragment-reference>
  </fragment>
</page-template>

Here is an example PSML file for portal site fragment definition, (*.fpsml):

<?xml version="1.0" encoding="UTF-8"?>
<fragment-definition>
  <title>Current Weather</title>
  <fragment id="wp-definition" type="portlet" name="demo::WeatherPortlet"/>
</fragment-definition>

Here is an example PSML file that defines portal site folder, (folder.metadata):

<?xml version="1.0" encoding="UTF-8"?>
<folder>
  <!-- folder description -->
  <title>Root Folder</title>  
  <metadata name="title" xml:lang="fr">Répertoire racine</metadata>
  <metadata name="title" xml:lang="es">Carpeta raiz</metadata>

  <!-- default page decorations -->
  <defaults layout-decorator="tigris" portlet-decorator="tigris"/>

  <!-- order of documents in folder -->
  <document-order>Jetspeed2.link</document-order>
  <document-order>Jetspeed2Wiki.link</document-order>
  <document-order>apache_portals.link</document-order>
  <document-order>apache.link</document-order>

  <!-- portal site menus -->
  <menu name="page-navigations">
    <separator>
      <text>Top Pages</text>
      <metadata name="text" xml:lang="fr">Page haut</metadata>
      <metadata name="text" xml:lang="es">Páginas más populares</metadata>
    </separator>
    <options>/Administrative</options>
    <separator>
      <text>Profiled Pages</text>
      <metadata name="text" xml:lang="es">Páginas del Perfil</metadata>
    </separator>
    <options regexp="true">/p[0-9][0-9][0-9].psml</options>
    <separator>
      <text>Non Java Pages</text>
      <metadata name="text" xml:lang="es">Ejemplos sin java</metadata>
    </separator>
    <options>/non-java</options>
  </menu>

  <!-- security constraints -->
  <security-constraints>
    <security-constraints-ref>public-view</security-constraints-ref>
  </security-constraints>
</folder>

Here is an example PSML file for a portal site link, (*.link):

<?xml version="1.0" encoding="UTF-8"?>
<link target="top">
  <!-- link description -->
  <title>Jetspeed 2 Home Page</title>
  <url>http://portals.apache.org/jetspeed-2/</url>
  <metadata name="title" xml:lang="es">Jetspeed 2</metadata>
</link>

Here is an example PSML file for the portal site page security, (page.security):

<?xml version="1.0" encoding="UTF-8"?>
<page-security>
  <!-- global admin constraints -->
  <security-constraints-def name="admin">
    <security-constraint>
      <roles>admin</roles>
      <permissions>view, edit</permissions>
    </security-constraint>
  </security-constraints-def>
  <global-security-constraints-ref>admin</global-security-constraints-ref>

  <!-- public constraints -->
  <security-constraints-def name="public-view">
    <security-constraint>
      <users>*</users>
      <permissions>view</permissions>
    </security-constraint>
  </security-constraints-def>
  <security-constraints-def name="public-edit">
    <security-constraint>
      <users>*</users>
      <permissions>view, edit</permissions>
    </security-constraint>
  </security-constraints-def>
</page-security>

Page

The <page> element is a simple container to hold other PSML elements associated with a portal site page. This element is persisted as a file with a '.psml' extension in the appropriate file system directory associated with the parent folder. There are two valid attributes for the page element:

The <page> element contains a number of other PSML elements:

Example: see intoductory examples above.

Layout Fragments

The page layout <fragment> element is a hierarchical container used to hold portlet fragments and nested layout fragments. The root fragment of a page must be a layout fragment, even when only one portlet fragment is part of the page. Layout fragments are subject to layout of the parent layout fragment and thus support the 'row' and 'column' layout properties. In addition, they also support the 'sizes' layout property used to control multicolumn layout proportions. There are 3 required attributes for this element:

The layout <fragment> element contains a number of other PSML elements:

Example:

<page>
  ...
  <fragment id="100393" type="layout" name="jetspeed-layouts::VelocityOneColumn">
    <fragment id="100939" type="portlet" name="j2-admin::LocaleSelector">
      <property name="row" value="0"/>
    </fragment>                                
    <fragment id="100345" type="layout" name="jetspeed-layouts::VelocityTwoColumns">
      <property name="row" value="1"/>
      <property name="sizes" value="33%,66%"/>
      <fragment id="100121" type="portlet" name="j2-admin::LoginPortlet">
        <property name="row" value="0"/>
        <property name="column" value="0"/>
      </fragment>                                
      <fragment id="100171" type="portlet" name="demo::UserInfoTest">
        <property name="row" value="0"/>
        <property name="column" value="1"/>
      </fragment>    
    </fragment>
  </fragment>
  ...
</page>

Portlet Fragments

The portlet <fragment> element is used to identify portlets on the page. Portlet fragments are subject to layout of the parent layout fragment and thus support the 'row' and 'column' layout properties as required by the layout. There are many valid attributes for this element:

The portlet <fragment> element contains other PSML elements:

Example:

<fragment id="100393" type="layout" name="jetspeed-layouts::VelocityOneColumn">
  ...
  <fragment id="100939" type="portlet" name="j2-admin::LocaleSelector">
    <property name="row" value="0"/>
  </fragment>                                
  ...
</fragment>

Fragment References

The <fragment-reference> element is used to insert an external fragment definition fragment hierarchy into the containing page, dynamic page or page template. Fragment references cannot appear in fragment definitions. The referenced fragment may be either a layout fragment or portlet fragment. Attributes and child elements of the fragment reference element override the settings in the referenced fragment. The fragment reference element supports one additional attribute not supported by layout fragments or portlet fragments:

The following layout fragment and portlet fragment attributes and child elements are not supported by the fragment reference element: name, type, fragment, fragment-reference, and page-fragment.

Example:

<fragment-reference id="template-top-wp-reference" refid="wp-definition">
  <property name="row" value="2"/>
</fragment-reference>

Fragment Properties

The fragment <property> element is use to specify named properties for fragments. These properties are used commonly to specify layout portlet parameters and portlet positional location within the page. The property element has 3 supported attributes:

Examples:

<fragment id="100876" type="portlet" name="j2-admin::LoginPortlet">
  ...
  <property name="row" value="2"/>
  <property name="column" value="1"/>
  ...
</fragment>

<fragment id="103456" type="layout" name="jetspeed-layouts::VelocityTwoColumns">
  ...
  <property name="sizes" value="33%,66%"/>
  ...
</fragment>

Preferences

The portlet fragment <preference> elements allow for the defining of default portlet preference values. This provides an easier avenue for the setting of default portlet preferences for a portlet instance on a page without having to duplicate portlet definitions within the portlet application's portlet.xml.

Preference precedence: User Defined > Fragment Defined > portlet.xml Defined.

The <preference> element attributes:

The <preference> element contains these elements:

Example:

<fragment id="uhtemp-1012" type="portlet" name="demo::BookmarkPortlet">
  ...
  <preference name="Google" readOnly="false">
    <value>http://www.google.com</value>
  </preference>
  ...
</fragment>

Dynamic Page

The <dynamic-page> element defines a reusable page that is used to display any matching portal content request URLs in the portal site. Individual dynamic pages are selected by the portal site mappings of the portal URL paths and content type. Apart from this matching process, content pages are identical to concrete page definitions. There are two attributes supported by the dynamic page element in addition to the page element attributes and child elements:

Example:

<dynamic-page content-type="doc" inheritable="false">
  ...
  <fragment id="default-content-layout" type="layout" name="jetspeed-layouts::VelocityTwoColumns">
    ...
  </fragment>
  ...
</dynamic-page>

Page Template

The <page-template> element specifies a template page that defines top level fragment and fragment references to be included in all concrete pages and dynamic pages in the portal site. A required single page fragment must be part of the page template fragment hierarchy. When pages are merged into the template, this fragment is replaced with the root fragment of the displayed concrete page and dynamic page. With the exception of the page fragment, the page template element supports all page attributes and child elements identically.

Example:

<page-template>
  ...
  <fragment id="template-top" type="layout" name="jetspeed-layouts::VelocityOneColumn">
    ...
    <page-fragment id="template-top-page-template">
      <property name="row" value="1"/>
    </page-fragment>
    ...
  </fragment>
  ...
</page-template>

Page Fragment

The <page-fragment> element appears exactly once in each page template definition. When the page template is merged with the displayed concrete page or dynamic page, all attributes and child elements override the same settings in the root fragment of the referenced page. No additional layout fragment attributes are supported by the page fragment element. The following layout fragment attributes and child elements are not supported by the page fragment element: name, type, fragment, fragment-reference, and page-fragment.

Example:

<page-template>
  ...
  <fragment id="template-top" type="layout" name="jetspeed-layouts::VelocityOneColumn">
    ...
    <page-fragment id="template-top-page-template">
      <property name="row" value="1"/>
    </page-fragment>
    ...
  </fragment>
  ...
</page-template>

Fragment Definition

The <fragment-definition> element defines a hierarchy of fragments that can be referenced from and merged into in multiple pages, dynamic pages, or page templates. The fragment definition is referenced by the id of the contained root fragment and the fragment hierarchy is merged into the displayed page where referenced. All attributes and child elements of the fragment definition, (with the exception of the root fragment), are not used within the displayed pages. Consequently, only page elements and attributes used to identify, describe, or secure the fragment definition itself are supported: id, security-constraints, version, title, short-title and metadata. Only layout fragments and portlet fragments can appear in the fragment hierarchy, but unlike pages, the root fragment need not be a layout.

Example:

<fragment-definition>
  <title>Current Weather</title>
  <fragment id="wp-definition" type="portlet" name="demo::WeatherPortlet"/>
</fragment-definition>

Folder

The <folder> element is a simple container to hold other PSML elements associated with a portal site folder. This element is persisted as a folder.metadata file in the associated file system directory. There are two valid attributes for the folder element:

The <folder> element contains a number of other PSML elements:

Example: see intoductory examples above.

Link

The <link> element is a simple container to hold other PSML elements associated with a portal link used to reference content external to the portal site. This element is persisted as a file with a '.link' extension in the appropriate file system directory associated with the parent folder. There are three valid attributes for the link element:

The <link> element contains a number of other PSML elements:

Example: see intoductory examples above.

Global Page Security

The <page-security> element is a simple container to hold other PSML elements used to declare global security constraints and their definitions.. This element is persisted as the page.security file and is always located in the root directory of the PSML file system directories. There is only one valid attribute for the page security element:

The <page-security> element contains two security constraints related PSML elements:

Example: see intoductory examples above.

PSML Titles and Metadata

The page, folder, and link <metadata> element is used to define locale specific title and short title text. Any number of these elements may appear within a containing PSML element, but multiple named values should not be specified for a single locale. The PSML xml documents are normally declared with the UTF-8 encoding to support a wide variety of character sets.

Example:

<page>
  ...
  <metadata name="title" xml:lang="fr">Ma Premiere Page de PSML</metadata>
  <metadata name="title" xml:lang="es">¡Bienvenido a Jetspeed 2!</metadata>
  <metadata name="title" xml:lang="hu">Köszönti a Jetspeed 2!</metadata>
  ...
</page>

PSML Defaults

The page and folder <defaults> element defines the default layout decorator and default portlet decorator. The default layout decorator is applied to all top level layout fragments which do NOT have a decorator attribute. The default portlet decorator is applied to all portlet fragments which do NOT have a decorator attribute. Defaults may be inherited from parent folder default elements. There are three valid attributes on the defaults element:

Example:

<page>
  ...
  <defaults skin="orange" layout-decorator="tigris" portlet-decorator="tigris"/>
  ...
</page>

PSML Security Constraints

The <security-constraints>, <security-constraints-def>, and <global-security-constraints-ref> elements that appear in pages, fragments, folders, links, and the page security elements above are documented separately in the the Declarative Security Constraints Guide.

Declarative Security Constraints Guide

PSML Menus

The <menu> element that appears in page and folder elements above are documented separately in the the Declarative Menus Guide.

Declarative Menus Guide