What is PSML?

PSML is an acronym for Portal Structure Markup Language. It was created to allow content structure and abstraction within Jetspeed.

PSML is actually composed of two different (but related) markups:

  • the registry markup which describes all the available resources to the Jetspeed engine. The Registry now supports more than a Portlet Registry. It also has a CapabilityMap Registry, a MediaType Registry, PortletControl Registry, and a PortletController Registry.
  • the site markup which describes which portlets, available in the registry, are actually displayed for a given user, as well as how they are organized on screen and what presentation properties they should use.

Portlet Registry

What is the PortletRegistry?

The PortletRegistry is a central store where Jetspeed can obtain further information about a given Portlet.

The Registry is organized like a flat list of portlets (identified in the markup but the entry element. All Portlets within the Registry must have a unique name.

Registry Entries

The portlets are described in the registry by an Entry description. These entries may be of three distinct types:

instance
This is the basic entry type. An instance entry should provide all the necessary informations to instanciate the portlet (at least the classname). This type of entry is instanciated as is by the Jetspeed engine.
abstract
An abstract entry is a entry which can't be instanciated directly because it misses some required information. It acts as a portlet template, useful for defining common properties for a group of related portlets. This type of entry is never instanciated by Jetspeed.
ref
The ref entry is an entry that define a new entry based on some other entry definition, thus the ref entry definition must reference another registry entry which may be of any type, even other ref entries. The engine will cascade all refs until it finds either an abstract or instance entry. It will then override all the parameters found in the abstract or instance definitions by those found in the ref(s) definition and try to instanciate this portlet.

Examples


<portlet-registry>
    <portlets>
        <portlet-entry type="abstract" name="RSS">
       <classname>
              org.apache.jetspeed.portal.portlets.NewRSSPortlet
       </classname>
           <parameter name="itemdisplayed" value="10" type="int"/>
           <parameter name="stylesheet.text/html"
                      value="/WEB-INF/xsl/rss.xsl"/>
           <parameter name="stylesheet.text/vnd.wap.wml"
                      value="/WEB-INF/xsl/rss-wml.xsl"/>
        </portlet-entry>
...
    </portlets>
</portlet-registry>

Site Markup

Files organisation

Whereas the registry describes all the Portlets in a single file, the markup uses one different file per registered user, thus providing customizability of the interface. With the new profiling service, users can have multiple markup files.

A default site description is used for anonymous access

Site elements

The site markup uses 4 main type of elements which correpsond directly to layout classes.

Entry
Entries describe Portlet elements, just as in the registry markup. However, in the site markup, all entries are of type ref and can't define some basic properties (such as classname or url) for security and performance reasons. These entries may however define some additional properties not available in the registry such as skin and layout properties.
Portlets
Portlets describe a group of Portlet elements (PortletSet). Such groups are useful for setting common layout and presentation properties for the contained portlets. Each portlets may contain either entry elements or nested portlets.
Controller
The contoller element describes the PortletController associated with a given PortletSet. The PortletController implements a layout strategy for the portlets contained in the PortletSet.
Control
The control element which can be found in portlets or entry elements describes the PortletControl associated with object. The PortletControl may provide additionnal functionalities to a portlet and may also add some graphical decorations around the portlet content.
PSML Reference
A reference to another PSML resource which is included into this PSML resource at the specified point in the markup. The reference is specified using a PSML resource locator in the path attribute of the reference PSML element as described here: PSML Locator

In PSML, all properties defined for an element are local to this element, except for the skin properties which are inherited in the component hierarchy.

Examples


<portlets user="default" xmlns="http://xml.apache.org/jetspeed/2000/psml">

  <controller name="org.apache.jetspeed.portal.controllers.RowColumnPortletController">
    <parameter name="sizes" value="70%,30%"/>
    <parameter name="mode" value="row"/>    
  </controller>

  <skin>
    <property name="selected-color" value="#990000"/>
    <property name="title-color" value="#FFCC00"/>
  </skin>

  <portlets>
    <controller name="org.apache.jetspeed.portal.controllers.RowColumnPortletController"/>
    <entry type="ref" parent="http://portals.apache.org/jetspeed-1/channels/jetspeed.rss">
    </entry>
    <entry type="ref" parent="http://www.xmlhack.com/rsscat.php">
    </entry>
  </portlets>

  <portlets>
    <controller name="org.apache.jetspeed.portal.controllers.RowColumnPortletController"/>
    <entry type="ref" parent="http://www.mozilla.org/news.rdf">
      <parameter name="itemDisplayed" value="5"/>
    </entry>
    <entry type="ref" parent="http://www.apacheweek.com/issues/apacheweek-headlines">
      <parameter name="showTitle" value="false"/>
    </entry>

    <reference id="P-ed09142736-10018" path="group/apache/page/news"/>

  </portlets>

</portlets>

PSML Locator

PSML Locators are used to locate PSML References. The path attribute of the reference PSML element defines the locator for another PSML resource. Locators are used to include an entire PSML resource into another PSML resource. This is useful for defining groups of markup once, and then sharing that markup in one or more PSML resources. Here is an example of a Portlet Reference. The locator is defined in the path attribute:


<portlets user="default" xmlns="http://xml.apache.org/jetspeed/2000/psml">
...
  <portlets>
    <controller name="org.apache.jetspeed.portal.controllers.RowColumnPortletController"/>

       <reference id="P-ed09142736-10018" path="group/apache/page/news"/>

  </portlets>
...

Locators are always defined as pairs of parameters. They can also be used as part of a URL. In the example above, there are two pairs of keywords and values:

  • group/apache
  • page/news
The keywords are "group" and "page", and the values are "apache" and "news". "apache" is the name of a group in Jetspeed. Groups are one way to arbitrarily classify PSML resources. "page" is the name of the PSML resource. The extension '.psml' is not needed.

The format of a locator is:

   user/<name>/media-type/<mediaType>/language/<language>/country/<country>/page/<page>
                   
or

   group/<name>/media-type/<mediaType>/language/<language>/country/<country>/page/<page>

or

   role/<name>/media-type/<mediaType>/language/<language>/country/<country>/page/<page>

Where the keywords "group", "group" and "role" are mutually exclusive, and all other parameters are optional. If the page parameter is not specified, the "default" PSML page is located as defined in the JetspeedResources.properties. For all other parameters, if they are not specified, then the media-type, language and country code will be determined from the capabilities of the requesting device (browser). Although you can specify any resource, such as another user's PSML in a locator, Jetspeed will make a security check to determine if you have sufficient authorization to include the PSML resource.

KeywordDescription
userSpecify that the resource is located under the 'user' subtree for the given user in the value parameter. If neither 'user', 'group' or 'role' are specified, the current user's subtree is defaulted.
groupSpecify that the resource is located under the 'group' subtree for the given group in the value parameter.
roleSpecify that the resource is located under the 'role' subtree for the given role in the value parameter.
media-typeSpecify that the resource is for a specific media type as given in the value parameter. Typical media types are "html", "wml", "xml"
languageSpecify that the resource is for a specific language as given in the value parameter. Languages must be specifed as an ISO-639 standard two-character language abbreviation. The language-code is an ISO-639 standard two-character abbreviation.
countrySpecify that the resource is for a specific country as given in the value parameter. Languages must be specifed as an ISO-639 standard two-character language abbreviation. The country-code is an IS0-3166 standard two-character abbreviation.
pageSpecify that the name of the resource in the value parameter. If not specified, uses the default resource.

PSML Database

If you would also like to store your PSML resources in the database, see the instructions here.