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, layed 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 also capture other portal site information related to pages, folders, links, and global security constraints. Each of these primary PSML elements are captured in separate documents arranged in a hierarchy of directories in the file system. Typically, this directory is accessed as a resource at /WEB-INF/pages within the jetspeed web application.
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 layout="OneColumn" name="row" value="0"/>
</fragment>
<fragment id="100345" type="layout" name="jetspeed-layouts::VelocityTwoColumns">
<property layout="OneColumn" name="row" value="1"/>
<property layout="TwoColumns" name="sizes" value="33%,66%"/>
<fragment id="100121" type="portlet" name="j2-admin::LoginPortlet">
<property layout="TwoColumns" name="row" value="0"/>
<property layout="TwoColumns" name="column" value="0"/>
</fragment>
<fragment id="100171" type="portlet" name="demo::UserInfoTest">
<property layout="TwoColumns" name="row" value="0"/>
<property layout="TwoColumns" 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 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>
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:
| Attribute | Description |
|---|---|
| hidden | A boolean attribute used to indicate that a page should not appear in portal site menus or other navigational elements. |
| version | A general purpose version tracking attribute. Not currently used by Jetspeed2. |
The <page> element contains a number of other PSML elements:
| Element | Description |
|---|---|
| title? | Simple element containing text for the default page title. The title of the page is considered its long description and is used as rollover text in some decorators if the short title is available for the menu text. If not specified, Jetspeed2 will attempt to define a title from the name of the file that contains the page element. |
| short-title? | Optional simple element containing text of the default short title for the page. The short title, if available, is used as menu text in some decorators. If not specified, the title text is used. |
| defaults? | Specifies the decorations for the page and its fragments. Optional defaults can be inherited from parent folders, but layout decorations are required for each page either specified explicitly or in a parent folder. |
| fragment | The root of the fragment hierarchy. All pages require a root Fragment. |
| metadata* | Optionally specifies locale specific titles and short titles for the page. |
| menu* | Optionally specifies additional or overrides inherited menu definitions for the page. |
| security-constraints? | Optionally defines inline security constraints for the page. If not specified, the page inherits the security constraints effective in the parent folder. |
Example: see intoductory examples above.
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:
| Attribute | Description |
|---|---|
| id | The required id is used to identify a fragment and must be unique across all fragments defined within the site. The value is opaque to Jetspeed2 and can follow any convention to guarantee uniqueness. Since fragments may be cached internally by Jetspeed2, any edits to exiting pages may require new ids to ensure the modifications are taken by Jetspeed2. |
| type | This required attribute must be set to 'layout' for all layout fragments. |
| name | The required name of the portlet used to implement the fragment layout. The portlet name generally takes the form of 'portlet-app-name:portlet-name' where portlet-app-name is the web context name, as specified in the portlet.xml files. Here are the supported Jetspeed2 layout portlet names:
|
The layout <fragment> element contains a number of other PSML elements:
| Element | Description |
|---|---|
| fragment* | Specified fragment elements can be either portlet fragments to be laid out by this layout fragment or nested layout fragments. All child fragments will have required property elements to specify their positions in this layout. Specifying no fragments within a layout fragment will result in no content being generated. |
| property* | Layout fragments can have an optional 'sizes' property that can be used to specify multicolumn layout proportions. Nested layout fragments may also have 'row' and/or 'column' properties to identify its positional location in the parent layout. |
| security-constraints? | Optionally defines inline security constraints for the fragment and its child fragments. Unlike, page, folder, and link constraints, only 'view' permissions can be constrained. If not specified, the fragment inherits the security constraints effective in the page. |
Example:
<page>
...
<fragment id="100393" type="layout" name="jetspeed-layouts::VelocityOneColumn">
<fragment id="100939" type="portlet" name="j2-admin::LocaleSelector">
<property layout="OneColumn" name="row" value="0"/>
</fragment>
<fragment id="100345" type="layout" name="jetspeed-layouts::VelocityTwoColumns">
<property layout="OneColumn" name="row" value="1"/>
<property layout="TwoColumns" name="sizes" value="33%,66%"/>
<fragment id="100121" type="portlet" name="j2-admin::LoginPortlet">
<property layout="TwoColumns" name="row" value="0"/>
<property layout="TwoColumns" name="column" value="0"/>
</fragment>
<fragment id="100171" type="portlet" name="demo::UserInfoTest">
<property layout="TwoColumns" name="row" value="0"/>
<property layout="TwoColumns" name="column" value="1"/>
</fragment>
</fragment>
</fragment>
...
</page>
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:
| Attribute | Description |
|---|---|
| id | The required id is used to identify a fragment and must be unique across all fragments defined within the site. The value is opaque to Jetspeed2 and can follow any convention to guarantee uniqueness. Since fragments may be cached internally by Jetspeed2, any edits to exiting pages may require new ids to ensure the modifications are taken by Jetspeed2. |
| type | This required attribute must be set to 'portlet' for all portlet fragments. |
| name | The required name of the portlet used to populate the fragment content. The portlet name generally takes the form of 'portlet-app-id:portlet-id' as specified in the portlet.xml files. |
| skin | A general purpose decorator attribute that can be referenced in the portlet decorators to control fragment presentation. Not currently used by Jetspeed2. |
| decorator | The name of the default portlet decorator used to render the fragments. This attribute is optional, but if it is not specified, the defaults for the page must specify a default portlet decorator. |
| state | The initial state of the fragment portlet; 'hidden' is currently the only valid value for this attribute. |
The portlet <fragment> element contains other PSML elements:
| Element | Description |
|---|---|
| property* | Parent fragments may have 'row' and/or 'column' properties to identify positional location in the parent layout. |
| title? | Optional simple text element containing title for fragment portlet, overridding titles set in portlet.xml. |
| preference* | Specifies initial user preference settings for fragment portlet, overridding any portlet preferences set in portlet.xml. User preferences, in turn, override these values. |
| security-constraints? | Optionally defines inline security constraints for the fragment. Unlike, page, folder, and link constraints, only 'view' permissions can be constrained. If not specified, the fragment inherits the security constraints effective in the page. |
Example:
<fragment id="100393" type="layout" name="jetspeed-layouts::VelocityOneColumn">
...
<fragment id="100939" type="portlet" name="j2-admin::LocaleSelector">
<property layout="OneColumn" name="row" value="0"/>
</fragment>
...
</fragment>
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:
| Attribute | Description |
|---|---|
| layout (deprecated) | The symbolic name of the layout fragment portlet the property is associated with. This attribute is supported for compatibility reasons. The strictly hierarchical structure of layout and portlet fragments implies that any single fragment and its properties can be subject to one layout fragment portlet. |
| name | The fragment property name. Jetspeed2 layout portlets support the 'row', 'column' and 'sizes' properties. |
| value | The fragment property value. The 'row' and 'column' properties accept 0-based indicies values. The 'sizes' property accepts HTML frameset tag 'rows' and 'cols' attributes sytax, (i.e. '25%,75%'). |
Examples:
<fragment id="100876" type="portlet" name="j2-admin::LoginPortlet"> ... <property layout="TwoColumns" name="row" value="2"/> <property layout="TwoColumns" name="column" value="1"/> ... </fragment>
<fragment id="103456" type="layout" name="jetspeed-layouts::VelocityTwoColumns"> ... <property layout="TwoColumns" name="sizes" value="33%,66%"/> ... </fragment>
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:
| Attribute | Description |
|---|---|
| name | The name of the preference. |
| readOnly | Boolean indicating whether or not the user can change the value of this preference. |
The <preference> element contains these elements:
| Element | Description |
|---|---|
| value+ | Simple text element containing a value associated with the named preference. |
Example:
<fragment id="uhtemp-1012" type="portlet" name="demo::BookmarkPortlet">
...
<preference name="Google" readOnly="false">
<value>http://www.google.com</value>
</preference>
...
</fragment>
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:
| Attribute | Description |
|---|---|
| hidden | A boolean attribute used to indicate that a folder should not appear in portal site menus or other navigational elements. |
| version | A general purpose version tracking attribute. Not currently used by Jetspeed2. |
The <folder> element contains a number of other PSML elements:
| Element | Description |
|---|---|
| title? | Simple element containing text for the default folder title. The title of the folder is considered its long description and is used as rollover text in some decorators if the short title is available for the menu text. If not specified, Jetspeed2 will attempt to define a title from the name of the file that contains the folder element. |
| short-title? | Optional simple element containing text of the default short title for the folder. The short title, if available, is used as menu text in some decorators. If not specified, the title text is used. |
| defaults? | Optionally specifies the decorations for the folder or subfolder pages and their fragments. Layout decorations are required for each page either specified explicitly in the individual pages or in a parent folder. |
| default-page? | Optional simple element containing text with the default page or subfolder name for the folder. The default page is used when the folder is directly referenced in the portal. The name of any page or folder in this folder, (including '..' for the parent folder), can be specified. If no default page is set, the page named 'default-page.psml' will be used; if 'default-page.psml' does not exist, the first page in the folder will become the default. |
| document-order* | An optional collection of simple elements containing text names used to define a sort order for page, subfolder, and link members. Members with matching names will be arranged in the order these elements are defined. Other members will be sorted by their names and will appear in menus and other lists after the matching members. Regular expressions for name matching are not supported. |
| metadata* | Optionally specifies locale specific titles and short titles for the folder. |
| menu* | Optionally specifies additional or overrides inherited menu definitions for the folder. |
| security-constraints? | Optionally defines inline security constraints for the folder. If not specified, the folder inherits the security constraints effective in the parent folder. |
Example: see intoductory examples above.
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:
| Attribute | Description |
|---|---|
| target | An optional target frame name in which to open the external content. If not specified, the linked content will replace the portal in the browser. |
| version | A general purpose version tracking attribute. Not currently used by Jetspeed2. |
| skin | A general purpose decorator attribute that can be referenced in the portlet decorators to control link presentation. Menu option elements for the link will adopt this skin value if not otherwise specified. Not currently used by Jetspeed2. |
The <link> element contains a number of other PSML elements:
| Element | Description |
|---|---|
| title? | Simple element containing text for the default link title. The title of the link is considered its long description and is used as rollover text in some decorators if the short title is available for the menu text. If not specified, Jetspeed2 will attempt to define a title from the name of the file that contains the link element. |
| short-title? | Optional simple element containing text of the default short title for the link. The short title, if available, is used as menu text in some decorators. If not specified, the title text is used. |
| url | The required content url element. The text of this element will be used to navigate the specified target frame in the browser. |
| metadata* | Optionally specifies locale specific titles and short titles for the link. |
| security-constraints? | Optionally defines inline security constraints for the link. If not specified, the link inherits the security constraints effective in the parent folder. |
Example: see intoductory examples above.
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:
| Attribute | Description |
|---|---|
| version | A general purpose version tracking attribute. Not currently used by Jetspeed2. |
The <page-security> element contains two security constraints related PSML elements:
| Element | Description |
|---|---|
| security-constraints-def* | Optionally defines a collection of security constraints defined by name. These security constraints are referenced in pages, fragments, folders, and links and in this element to facilitate reuse and security maintenance. |
| global-security-constraints-ref* | Optionally defines security constraints references to be applied to all security constraints in the site. The text of each simple element references a named security constraints definition specified here in this element. |
Example: see intoductory examples above.
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.
| Attribute | Description |
|---|---|
| name | Name of the metadata text. This name should be either 'title' or 'short-title' to specify locale specific title text. |
| xml:lang | The locale language or language/country selector for the metadata text. The conventional Java Locale names are expected, (ISO-639 and ISO-3166). Valid values would include 'en' and 'en_US'. |
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>
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:
| Attribute | Description |
|---|---|
| layout-decorator | The name of the layout decorator used to render the page. This attribute is required, but may be inherited from a parent folder.. |
| portlet-decorator | The name of the default portlet decorator used to render the page fragments. This attribute is optional, but is almost always set. This attribute too may be inherited from parent folders. |
| skin | A general purpose decorator attribute that can be referenced in the decorators to control page and folder presentation. Menu option elements for the page and folder will adopt this skin value if not otherwise specified. Not currently used by Jetspeed2. |
Example:
<page> ... <defaults skin="orange" layout-decorator="tigris" portlet-decorator="tigris"/> ... </page>
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.