PSML - Portal Site Markup Language

Following last week discussion on the list, here's a proposition
for an evolution of the Portlet Markup Language to allow
a more extensive description of a site.

Note:
This is a draft and may heavily be changed as soon as I'll
really try to implement it... :)

The following schema is NOT directly backward compatible
because I renamed 'entry' to 'portlet', but was still designed
with backward compatibility in mind.

The main additions to the previous format are:
- addition of layout and skin elements:
    . layout elements are structural hints to build the resulting page 
    . skin are simple display properties which may easily delegated 
      to the client (for example as CSS stylesheets...)
- extension of the parameter element to allow typecasting
  for automatic customization screen building
- introduction of panes for portlets grouping
- possibility of profile definition to automatically create 
  user portlets set from a base template
- decorrelation of portlets instanciation, portlet definition and 
  channel definition:
  - a pane should use portletRef to indicate its wish to use
    a given portlet (with maybe some additional infos).
    The portletRef use a custom portlet URL to reference the portlet
    which may be defined in the local file or in a registry
    
    portlet URL format:
    
    portlet:[//<registry host>:<port>/]<portlet name>[:<portlet dependent extension>]
    
    for example:
        portlet:MailPortlet
        portlet://myregistryserver:1199/RSSPortlet
        portlet:RSSPortlet://relativity.yi.org/jetspeed.rss
    
  - a portlet defintion should provide the implementation classname 
    and default properties for the portlet operation
    It may also notify the Factory that it's a stateless portlet
    using the pool element
    
  - a portlet should reference a channel through a registry lookup
    URL
    
    channel:[//<myhost>:<port>]/<context>?[<format type>]?[<lang>]?[<XPath filter>]
   
    example:
    
    channel:/Computers/WindowsNT?rss??[name='WindowsWorld']
    
    The channel named WindowsWorld in RSS format found in the Computers/WindowsNT
    categories
    
    channel:/??fr?

    Any available channel in French
    
    Other URLs types are also supported and should be used while there's no
    channel registry implementation available.
    
I hope to be able to provide a working implementation of a Factory using
these properties before the week-end.

Any comments, feedback, criticism welcome.

8<--------- PSML.xsd ----8<-------8<-------------8<-----------
<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- 
PSML - Jetspeed Portal Site Markup Language
Version: $Id$
Authors:  Kevin A. Burton <burton@apache.org>
          Raphaël Luta <luta.raphael@networks.vivendi.net>
     
This markup allows description of customized user portal 
interface. It is actually the merge of 2 description formats
based on 2 distinct root elements:
- portlets: description of current user portlets set
- profiles: templates for easy creation of portlets
  for new users

Channels used by syndication portlets should be defined externally
(for example in OCS) and referenced by URL in this markup
-->

<schema>

<!-- root element for profile registry type file -->
<element name="profiles">
    <archetype>
        <element ref="profile"/>
    </archetype>
</element>

<!-- profile definition, is actually a named portlets element
without associated user but with a title and description
-->
<element name="profile">
    <archetype content="elemOnly">
        <element ref="title"  minOccurs="0"/>
        <element ref="description"  minOccurs="0"/>
        <element ref="controller" minOccurs="0" maxOccurs="1"/>
        <element ref="layout"  minOccurs="0"/>
        <element ref="skin"  minOccurs="0"/>
        <element ref="parameter"  minOccurs="0"/>
        <element ref="pane"  minOccurs="1"/>
        <element ref="portlet"  minOccurs="1"/>
        <attribute name="name" type="string"  minOccurs="0" default="default"/>
    </archetype>
</element>

<!-- 
    Portlet set definition object

    This element should be the root element in a file keyed
    to a specific user for the portlet set description of this
    user
    
    user: Turbine login of user owner of this portlet set  
    controller: Classname of the controller responsible for
                displaying this set

    TBD: should we define also a control element for PortletControl ?
    
    portlet: local portlet definitions, these definitions should 
    be put in a portlet registry file
    
    pane: entity for grouping portlets and assigning common properties

    skin, parameter, layout: see their entries
-->
<element name="portlets">
    <archetype content="elemOnly">
        <element ref="controller" minOccurs="0" maxOccurs="1"/>
        <element ref="layout"  minOccurs="0"/>
        <element ref="skin"  minOccurs="0"/>
        <element ref="parameter"  minOccurs="0"/>
        <element ref="pane"  minOccurs="1"/>
        <element ref="portlet"  minOccurs="1"/>
        <attribute name="user" type="string"  minOccurs="0" default="default"/>
    </archetype>
</element>

<!-- 
    Allow groups of portlets to share common properties. Most
    useful for defining "virtual screens" of portlets
    
    TBD: should this element be kept or replaced by a layout
    element in individual portlets ?
    
    title defines the display name of the pane
-->
<element name="pane">
    <archetype content="elemOnly">
        <element ref="title" minOccurs="0"/>
        <element ref="portletRef" minOccurs="0"/>
        <element ref="layout" minOccurs="0"/>
        <element ref="skin" minOccurs="0"/>
        <element ref="parameter" minOccurs="0"/>
        <attribute name="name" type="string"  minOccurs="0"/>
    </archetype>
</element>

<!-- Main portlet definition

    if pool is defined and > 0, portlet is considered stateless
    and pool instances at most are created by the Factory
    
    url element must contain an URL value which may be:
        - absolute or relative HTTP (/content/text.rss)
        - external FILE or HTTP (http://www1.test.com/mychannel.rss)
        - jetspeed channel URL (channel:///?rss?en?[name='Test'])
-->
<element name="portlet">
    <archetype>
        <element ref="classname" minOccurs="1" maxOccurs="1"/>
        <element ref="url" minOccurs="0" maxOccurs="1"/>
        <element ref="pool" minOccurs="0" maxOccurs="1"/>
        <element ref="layout" minOccurs="0"/>
        <element ref="skin" minOccurs="0"/>
        <element ref="parameter" minOccurs="0"/>
        <element ref="metainfo" minOccurs="0" maxOccurs="1"/>
        <attribute name="name" type="string"  minOccurs="1"/>
        <attribute name="application" type="boolean"  minOccurs="1" default="false"/>
        <attribute name="type" type="string"  minOccurs="0" default="stateful">
        </attribute>
    </archetype>
</element>

<!-- 
    The main element of content, should link to an existing
    portlet definition which will provide implementation
    details (such as classname).
    
    May override some parameters defined in the portlet
    definition and some some metainfo defined in the channel
    description (if there's one).
    
    url element must contain an URL value which may be:
        - absolute or relative HTTP (/content/text.rss)
        - external FILE or HTTP (http://www1.test.com/mychannel.rss)
        - jetspeed channel URL (channel:///?rss?en?[name='Test'])
-->
<element name="portletRef">
    <archetype>
        <element ref="url" minOccurs="0" maxOccurs="1"/>
        <element ref="parameter" minOccurs="0"/>
        <element ref="metainfo" minOccurs="0" maxOccurs="1"/>
        <element ref="layout" minOccurs="0"/>
        <element ref="skin" minOccurs="0"/>
        <attribute name="href" type="string"  minOccurs="1"/>
    </archetype>
</element>

<!--
    This element is a property used by the controller or control 
    to describe preferred layout structure.    
    This is only a hint, contoller may safely ignore any layout
    element.
    Some hints may be specified only for some controllers by specifying
    the controller classname in the controller attribute.

    The available list of properties is defined by the current controller
    and set by the controller or controller customization pane 
    
    When the value attribute is empty, should use the string representation of the
    element content as value
-->
<element name="layout">
    <archetype>
        <attribute name="name" type="string"  minOccurs="1"/>
        <attribute name="value" type="string" minOccurs="0"/>
        <attribute name="controller" type="string"  minOccurs="0"/>
    </archetype>
</element>

<!--
    This element is a property used by the control or controller to 
    customize the visual appearance of the portlet, pane or portlet set.

    These elements should have as allowed property names, valid CSS1 
    properties.
    They should never influence the structural representation of the screen

    The available list of properties is defined by the current control or
    controller and set by the control(ler) or control(ler) customization pane 

    When the value attribute is empty, should use the string representation of the
    element content as value
-->
<element name="skin">
    <archetype>
        <attribute name="name" type="string"  minOccurs="1"/>
        <attribute name="value" type="string" minOccurs="0"/>
    </archetype>
</element>

<!-- 
    This element is a property defining a user parameter required by the
    portlet operation.
    These parameters must not be ignored.
    They are set by the portlet customization screen

    When the value attribute is empty, should use the string representation of the
    element content as value
-->
<element name="parameter">
    <archetype>
        <group order="all">
            <element ref="maxInclusive" minOccurs="0"/>
               <element ref="minInclusive" minOccurs="0"/>
            <element ref="enumeration" minOccurs="0"/>
        </group>
        <attribute name="name" type="string"  minOccurs="1"/>
        <attribute name="value" type="string" minOccurs="0"/>
        <attribute name="type" type="string" minOccurs="0"/>
    </archetype>
</element>

<!--
    Encapsulation for meta-data info, should probably be moved
    to Dublin Core by using namespaces
-->
<element name="metainfo">
    <archetype>
        <element ref="title" minOccurs="0" maxOccurs="1"/>
        <element ref="description" minOccurs="0" maxOccurs="1"/>
    </archetype>
</element>

<!-- 
    Subset of XML Xchema definition for property
    constraints
-->
<element name="enumeration">
    <archetype content="elemOnly">
        <element ref="litteral" minOccurs="1"/>
    </archetype>
</element>
<element name="minInclusive" type="integer"/>
<element name="maxInclusive" type="integer"/>
<element name="litteral" type="string"/>

<!-- Misc text elements -->
<element name="classname" type="string"/>
<element name="pool" type="integer"/>
<element name="controller" type="string"/>
<element name="title" type="string"/>
<element name="description" type="string"/>
<element name="url" type="string"/>

</schema>
8<--------- end PSML.xsd 8<-------8<-------------8<-----------

Example markup:

8<--------- default.xml 8<-------8<-------------8<-----------
<?xml version="1.0"?>
<portlets user="luta">
    <controller>DefaultPortletController</controller>
    <layout name="defaultPane">HomePage</layout>
    <layout name="columnNumbers">3</layout>
    <layout name="showTitles">true</layout>
    <layout name="stylesheet" controller="XMLPortletController">file:///test/test.xsl</layout>
    <skin name="background-color" value="#ffeeee"/>
    <skin name="color" value="black"/>
    <skin name="font-family" value="Arial, Helvetica"/>
    
    <pane name="HomePage">
        <layout name="columnNumbers" value="2"/>        
        <layout name="columnNumber" value="1"/>    
        <layout name="columnPosition" value="1"/>        

        <portletRef href="portlet:RSSPortlet">
            <layout name="columnNumber">1</layout>        
            <layout name="columnPosition">2</layout>        
            <skin name="margin" value="10px,10px,10px,10px"/>
            
            <url>channel:///?rss?fr?[name='ComputerWorld']</url>
            <metainfo>
                <title>My Preferred Channel</title>
            </metainfo>
        </portletRef>

        <portletRef href="portlet:CocoonPortlet">
            <layout name="columnNumber">1</layout>
            <url>file:///d:/test/test.xml</url>
            <parameter name="stylesheet">d:/test/foo.xsl</parameter>
        </portletRef>
        
        <portletRef href="portlet:RSSPortlet://relativity.yi.org/jetspeed.rss"/>
    </pane>

    <pane name="Mail">
        <layout name="columnNumbers">1</layout>        
        <skin name="left-margin" value="5px"/>
        
        <portletRef href="portlet:MailPortlet" application="true">
            <metainfo>
                <title>My Mail Account</title>
            </metainfo>
        </portletRef>
    </pane>
</portlets>
8<--------- end default.xml 8<-------8<-------------8<------------

8<--------- profiles.xml 8<-------8<-------------8<---------------
<?xml version="1.0"?>
<profiles>
    <profile name="ComputerGeek">
        <title>GeekWorld</title>
        <description>Selection of channels of interest for computer geeks</description>
        <pane name="Personal Computers">
            <portlet href="portlet:RSSPortlet">
                <url>http://www.computergeek.com/channel.rss</url>
            </portlet>
            <portlet href="portlet:FilePortlet">
                <url>file:///d:/www/computers/welcome.xhtml</url>
            </portlet>
        </pane>
    </profile>
</profiles>
8<--------- end profiles.xml 8<-------8<-------------8<-----------

8<--------- portletregistry.xml 8<-------8<-------------8<--------
<?xml version="1.0"?>
<portlets>
    <portlet name="RSSPortlet">
        <classname>org.apache.jetspeed.RSSPortlet</classname>
        <parameter name="channels" type="URL">file:///parameters/channels.xml</parameter>
        <parameter name="itemDisplayed" type="int" value="10">
            <minInclusive>0</minInclusive>
        </parameter>
        <parameter name="showDescriptons" type="boolean">true</parameter>
        <parameter name="showImages" type="boolean">false</parameter>        
    </portlet>
    <portlet name="RSSPortlet://relativity.yi.org/jetspeed.rss">
        <classname>org.apache.jetspeed.RSSPortlet</classname>
        <url>http://relativity.yi.org/jetspeed.rss</url>
        <parameter name="itemDisplayed" type="int" value="4"/>
        <parameter name="showDescriptons" type="boolean">true</parameter>
        <parameter name="showImages" type="boolean">true</parameter>        
    </portlet>
    <portlet name="DatePortlet">
        <pool>5</pool>
        <classname>org.apache.jetspeed.DatePortlet</classname>
        <parameter name="timeZone" type="string" value="GMT"/>
        <parameter name="dateTimeFormat" type="string">%d/%m/%Y %H:%M</parameter>
    </portlet>
    <portlet name="MailPortlet" application="true">
        <classname>org.apache.jetspeed.MailPortlet</classname>
        <parameter name="numOfMessages" type="int" value="30"/>
        <parameter name="protocol" type="string" value="IMAP">
            <enumeration>
                <litteral>IMAP</litteral>
                <litteral>MH</litteral>
                <litteral>POP3</litteral>
            </enumeration>
        </parameter>        
    </portlet>
</portlets>
8<--------- endportletregistry.xml 8<-------8<-------------8<-----