Jetspeed2.0中的PSML介绍

原文出处：

http://portals.apache.org/jetspeed-2/guides/guide-psml.html

Page

Defaults

Layout Fragments

Portlet Fragments

Fragment Properties

Portlet Preferences

Folder

Link

Global Page Security

Titles and Metadata

Security Constraints

Menus

PSML是门户结构标记语言（Portal Structure Markup Language）的缩写。它是用来在jetspeed中进行内容结构化和抽象的。PSML定义了在一个portal页面上如何将portlets进行整合、布局、装饰的。注意，页面规划并不是Portlet标准接口，因此PSML是jetspeed自己的实现方式。同时需要声明的是PMSL在jetspeed-2里不同于jetspeed-1。这篇文章可以作为对PSML资源元素描述的一个参考指南。

PSML文件也可以获得其它相关的门户站点信息，如页、文件夹、链接和全局安全限制。每个这些主要的PSML元素都可以从文件系统中各层目录里定义的不同文件中获得。通常的，这个目录在jetspeed应用的/WEB-INF/pages下。

下面是一个关于page定义的例子：

<?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>

下面是一个关于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>

<!-- 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>

下面是一个关于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>

下面是一个关于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：

<page>元素是一个简单的容器可包含与portal站点页面有关的其他PSML元素。这个元素一直定义在以.pmsl为扩展名的文件中，此文件存放在与父文件夹相关的适当文件目录中。在page元素中有两个有效属性：

属性	描述
hidden	一个布尔属性，用来说明page是否应当出现在门户站点菜单或其他导航元素里。
version	一个通用版本跟踪的属性。目前在jetspeed2中并不使用。

<page>元素包含一些其他的PSML元素：

元素	描述
title?	缺省的页面标题。这个页面标题被当作是一个详细描述，并且在一些decorators中如果short-title被当作菜单标题的话可用作滚动的文本说明。如果没有指定，Jetspeed2将试图定义一个标题从包含page元素的文件名。
short-title?	可选元素，定义缺省的页面短标题。在一些decorators中被当作菜单标题。如果没有指定，使用title内容。
defaults	为页面和其中的片段指定装饰（decorations）。每个页面都需要此元素。
fragment	分层片段的根。所有页面都需要一个根片段。
metadata*	为页面指定当地语言的标题和短标题。
menu*	为页面指定额外的或忽略被继承的菜单。
security- constraints?	定义页面的内部安全约束。如果没有指定，继承父文件夹的安全约束。

Defaults:

在page元素中的<defaults>元素定义了缺省的布局装饰和缺省的portlet装饰。缺省的布局装饰应用于所有的没有decorator属性的布局片段。缺省的portlet装饰应用于所有的没有decorator属性的portlet片段。defaults元素包含三个属性：

属性	描述
layout- decorator	用来展现页面的布局装饰名称。这个属性为必填项。
portlet- decorator	用来展现页面片段的缺省portlet装饰名称。这个属性为可选项，但一般都设置。
skin	一个通用的装饰属性，在decorators中引用去控制页面和片段的表达。目前在Jetspeed2中并没使用。

例子：

<page>

...

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

...

</page>

Layout Fragments:

在page元素中的布局<fragment>元素是一个分层的容器，用来保存portlet片段和嵌套的布局片段。Page元素的根片段必须是一个布局片段，即使这个页面只有一个portlet片段。布局片段依赖于父布局片段因此支持’row’和’column’布局特性。另外，也支持’sizes’特性来控制多层列的布局特性。这个元素有三个必须的属性：

属性	描述
id	必填项。用来识别片段，在整个站点所有的片段中必须是唯一的。这个值对于Jetspeed2是不透明的，可以遵循任何一种可产生唯一值的约定。因为片段也许由Jetspeed2内部缓存了，对退出页的任何修改都需要新的ids来保证修改被Jetspeed2获得。
type	必填项。所有布局片段都必须设置为’layout’。
name	必填项。用来识别片段布局的portlet名称。这个名称产生来自于在portlet.xml文件里指定的’portlet-app-id::portlet-id’。下面列出了在Jetspeed2支持的布局portlet名称： jetspeed-layouts::FrameLayoutPortlet jetspeed-layouts::VelocityOneColumn jetspeed-layouts::VelocityOneColumnNoActions jetspeed-layouts::VelocityThreeColumns jetspeed-layouts::VelocityThreeColumnsNoActions jetspeed-layouts::VelocityThreeColumnsTable jetspeed-layouts::VelocityTwoColumns jetspeed-layouts::VelocityTwoColumns2575 jetspeed-layouts::VelocityTwoColumns2575NoActions jetspeed-layouts::VelocityTwoColumnsNoActions jetspeed-layouts::VelocityTwoColumnsSmallLeft jetspeed-layouts::VelocityTwoColumnsSmallLeftNoActions jetspeed-layouts::VelocityTwoColumnsTable

布局<fragment>元素包含一些其他的PSML元素：

元素	描述
fragment*	指定的片段元素不是被这个布局片段布置的portlet片段就是嵌套的布局片段。所有的子片段都需要有property元素来指定他们在这个布局中的位置。在布局片段中的片段不会导致没有内容产生。
property*	布局片段可以有一个可选的’sizes’特性用来指定多层列的布局比例。嵌套的布局片段也可以有’row’和/或’column’特性来确定在父布局中它自己的位置。
security- constraints?	可选项，在片段和它的子片段中定义的内部安全约束。Unlike、页、文件夹和链接约束，只有’view’权限可以被约束。如果没有指定，片段继承在page中定义的安全约束。

例子：

<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>

Portlet Fragments:

portlet<fragment>用来识别页面中的portlets。Portlet片段依赖于父布局片段因此支持’row’和’column’布局特性。这个元素包含下列属性：

属性	描述
id	必填项。用来识别片段，在整个站点所有的片段中必须是唯一的。这个值对于Jetspeed2是不透明的，可以遵循任何一种可产生唯一值的约定。因为片段也许由Jetspeed2内部缓存了，对退出页的任何修改都需要新的ids来保证修改被Jetspeed2获得。
type	必填项。所有portlet片段都必须设置为’portlet’。
name	必填项。用来识别片段布局的portlet名称。这个名称产生来自于在portlet.xml文件里指定的’portlet-app-id::portlet-id’。
skin	一个通用的装饰属性，在decorators中引用去控制页面和片段的表达。目前在Jetspeed2中并没使用。
decorator	用来展现片段的缺省portlet装饰名称。这个属性是可选项，但如果没有指定的话page元素中的defaults元素就必须指定一个缺省的portlet装饰。
state	portlet片段的初始状态。目前这个属性的唯一值是’hidden’。

Portlet<fragment>包含一些其他的PSML元素：

元素	描述
property*	父片段可能有’row’和/或’column’特性来确定在父布局中的位置地点。
title?	可选项，portlet片段标题的文本元素。可忽略在portlet.xml中的title设置。
preference*	在portlet片段里指定最初的用户选项设置，忽略在portlet.xml中设置的portlet选项。反之，User preferences 忽略这些值
security- constraints?	可选项，在片段中定义的内部安全约束。Unlike、页、文件夹和链接约束，只有’view’权限可以被约束。如果没有指定，片段继承在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>

Fragment Properties:

fragment的<property>元素用来指定片断的特性。这些特性通常是用来指定portlet布局参数和portlet在页面上的位置地点。Property元素有3个属性：

属性	描述
layout (deprecated)	与特性相关的布局片段portlet符号名。这个属性支持兼容性。布局和portlet片段的严格的分层结构说明任何一个单独的片段和它的特性都依赖于一个布局片段portlet。
name	片段特性名称。Jetspeed2布局portlets支持’row’,’column’和’sizes’3个特性。
value	片段特性值。’row’和’column’允许基于0的值，’sizes’特性允许HTML框架标记’rows’和’cols’属性（比如，’25%,75%’）。

例子：

<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>

Preference:

portlet fragment中的<preference>元素允许定义portlet选项。为在页面中的portlet实例设置缺省的portlet选项提供了一种更简便的方法，不需要在portlet应用的portlet.xml文件里复制一个portlet定义。

选项的优先顺序：用户定义>片段定义>portlet.xml定义

<preference>元素的属性：

属性	描述
name	选项名称
readOnly	布尔型，标示用户是否可以改变这个选项值。

<preference>元素包含的元素：

元素	描述
value+	与选项相关的值，文本元素。

例子：

<fragment id="uhtemp-1012" type="portlet" name="demo::BookmarkPortlet">

...

<preference name="Google" readOnly="false">

<value>http://www.google.com</value>

</preference>

...

</fragment>

Folder：

<folder>元素是一个简单的容器，用来保存与一个门户站点文件夹相关的其他PSML元素。这个元素定义在相关的文件系统目录下的folder.metadata文件里。包含两个属性：

属性	描述
hidden	一个布尔属性，用来说明folder是否应当出现在门户站点菜单或其他导航元素里。
version	一个通用版本跟踪的属性。目前在jetspeed2中并不使用。

<folder>元素包含了一些其他的PSML元素：

元素	描述
title?	缺省的文件夹标题。这个文件夹标题被当作是一个详细描述，并且在一些decorators中如果short-title被当作菜单标题的话可用作滚动的文本说明。如果没有指定，Jetspeed2将试图定义一个标题从包含folder元素的文件名。
short-title?	可选项，定义缺省的文件夹短标题。在一些decorators中被当作菜单标题。如果没有指定，使用title内容。
default-page?	可选项，定义这个文件夹缺省页面或子文件夹的名称。当文件夹在门户中被直接引用时使用缺省页。在这个文件夹中的任何页或文件夹的名称可以被指定（包括父文件夹的’..’）。如果缺省页没有设置，’default-page.psml’将被使用；如果’default-page.psml’不存在，则这个文件夹中的第一个页将变为缺省页。
document- order*	一个简单元素的任意集合，包括用来定义page、子文件夹和链接成员的排序次序的一个文本名称。成员根据匹配的名字被安排在这些定义的元素次序里。其他的成员将通过名字被存储并且在那些匹配的成员之后出现在菜单和其他的列表里。不支持命名匹配的正则表达式。
metadata*	为文件夹指定当地语言的标题和短标题。
menu*	为文件夹指定额外的或忽略被继承的菜单。
security- constraints?	定义文件夹的内部安全约束。如果没有指定，继承父文件夹的安全约束。

Link:

<link>元素是一个简单的容器，用来保存与一个门户站点链接相关的其他PSML元素。门户链接用来涉及门户站点外部的一些内容。这个元素定义在与父floder相关的文件系统目录下的以’.link’为后缀的文件里。包含两个属性：

属性	描述
target	一个能打开外部内容的任意目标框架名称。如果没有指定，链接的内容将取代门户出现在浏览器中。
version	一个通用版本跟踪的属性。目前在jetspeed2中并不使用。

<link>元素包含了一些其他的PSML元素：

元素	描述
title?	缺省的链接标题。这个链接标题被当作是一个详细描述，并且在一些decorators中如果short-title被当作菜单标题的话可用作滚动的文本说明。如果没有指定，Jetspeed2将试图定义一个标题从包含link元素的文件名。
short-title?	可选项，定义缺省的链接短标题。在一些decorators中被当作菜单标题。如果没有指定，使用title内容。
url	必须的内容url元素。这个元素的文本内容将用来在浏览器中定向到指定的目标地址。
metadata*	为链接指定当地语言的标题和短标题。
security- constraints?	定义链接的内部安全约束。如果没有指定，继承父文件夹的安全约束。

Global Page Security:

<page-security>元素是一个简单的容器，用来保存一些用来声明全局安全约束的其他PSML元素和他们的定义。这个元素定义在page.security文件里并且它总是存放在PSML文件系统目录下的根目录里。包含一个属性：

属性	描述
version	一个通用版本跟踪的属性。目前在jetspeed2中并不使用。

<page.security>元素包含了两个安全约束PSML元素：

元素	描述
security-constraints- def*	任意地定义一些以名称定义的安全约束集合。这些安全约束在page、fragments、floders和link中被引用，并且在这个元素里可促进再次使用和安全维护。
global-security- constraints-ref*	定义的安全约束可应用于这个站点的所有安全约束。各个简单的元素文本涉及到一个名为安全约束的定义被指定在这个元素里。

PSML Titles and Metadata:

Page, folder和link中的<metadata>元素用来定义本地的title和short title文本。这些元素可以在一个PSML里出现任何次数。但多个命名值不应该指定为一个地点。PSML xml 文档通常使用UTF-8编码格式来支持各种各样的字符集。

属性	描述
name	metadata文本的名称。这个名称应当不是’title’就是’short_title’来指定本地的具体标题文本。
xml:lang	metadata文本的地点语言或lange/country选择器。常规的Java地点名称被期待(ISO-639 and ISO-3166)。有效的值将包括’en’和’en_US’。

例子：

<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 Security Constraints:

在pages , fragments , folders , links 和 page security元素中出现的<security-constraints>, <security-constraints-def>, 和<global-security-constraints-ref>元素将单独地在安全约束指导文档里介绍。

Declarative Security Constraints Guide

PMSL Menus:

在 page 和 folder元素中出现的<menu>元素将单独地在菜单指导文档里介绍。

Declarative Menus Guide