Guide to PSML

最新推荐文章于 2024-07-15 14:10:53 发布

herolily

最新推荐文章于 2024-07-15 14:10:53 发布

阅读量1.7k

点赞数

分类专栏： JetSpeed 文章标签： constraints portlet layout security decorator attributes

JetSpeed 专栏收录该内容

3 篇文章

订阅专栏

1. Guide to PSML

PSML

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

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

</fragment>

</fragment>

</fragment>

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

<title>Root Folder</title>

<metadata name="title" xml:lang="fr">Répertoire racine</metadata>

<metadata name="title" xml:lang="es">Carpeta raiz</metadata>

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

<text>Top Pages</text>

<metadata name="text" xml:lang="es">Páginas más populares</metadata>

</separator>

<options>/Administrative</options>

<text>Profiled Pages</text>

<metadata name="text" xml:lang="es">Páginas del Perfil</metadata>

</separator>

<text>Non Java Pages</text>

<metadata name="text" xml:lang="es">Ejemplos sin java</metadata>

</separator>

</menu>

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

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

<security-constraints-def name="admin">

<security-constraint>

<roles>admin</roles>

</security-constraint>

</security-constraints-def>

<global-security-constraints-ref>admin</global-security-constraints-ref>

<security-constraints-def name="public-view">

<security-constraint>

</security-constraint>

</security-constraints-def>

<security-constraints-def name="public-edit">

<security-constraint>

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

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.

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:

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

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>

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

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>

...

</fragment>

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:

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>

...

...

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

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:

...

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

</preference>

...

</fragment>

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:

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.

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:

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.

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:

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.

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.


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>

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:

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>

...

...

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

[MS1]layout 的概念比较大，是一个大的页面，使每一个Portlet Application的设置，每个Portlet Application 包含多个portlet.

[MS2]这就是portlet