[This document is a functional description of the new layout
system. Comments, remarks, criticisms welcome...
The actual implementation proposal will come after this
document requirements are somewhat stabilized]
Jetspeed layout system, part 2: Functional description
Raphaël Luta <[EMAIL PROTECTED]>
Definitions:
============
1. Portal configuration
A portal configuration is a set of user properties, defined for a complete
portal site, that is used by Jetspeed engine to customize the portal site.
A configuration will usually be media type dependent. A given media type
may be associated with several configurations for the same user profile.
2. Pane
A pane is a customizable layout component which can be included in the
main portal templates. Each pane is responsible for the layout and
rendering of its customized content elements.
3. Portlet
A portlet is the base customizable content producing unit in Jetspeed.
The functional description will usually not separate the portlet, as
portal-independent component model and the portlet, as part of the
Jetspeed layout system.
When such a distinction is necessary, the former will be called "portlet"
and the latter "screenlet".
Actors:
=======
This description may refer to the following actors:
1. Administrator:
The administrator is the owner of the portal. He's responsible for
designing the site templates and functionalities, configuring the
initial properties files and defining the appropriate permissions.
The administrator must understand the template language used by
its site screens as well as the configuration files semantics.
2. User:
The user is a client of the site, which is assigned specific portal
configurations. A user does not necessary refer to a physical
entity (it may be an anonymous user, a group, etc...).
No specific knowledge is required for the user.
Portal site definition
======================
A portal site is defined by the portal administrator who needs
to configure different files :
- screen templates (which may use any template language supported
by Turbine) defining the different pages for the site.
Each template may access a jetspeed toolbox object which,
among other functionalities, will enable the administrator
to include configurable panes in the site templates.
Example:
index.vm:
<table width="100%" cellspacing="0" cellpadding="0">
<tr>
<td valign="top">
$jetspeed.Pane("home_main")
</td>
<td valign="top">
$jetspeed.Pane("general_tools").Customize(false)
$jetspeed.Pane("user_tools")
</td>
</tr>
</table>
[Note: the example markup proposed above is just used for
descriptive purpose]
When browsing this portal page, the named panes defintions
will be loaded from the current user configuration.
- default portal configuration files
These files describe the various panes available for use within the
site as well as the portlets included in these panes.
example:
default.psml
<configuration>
<panes>
<pane name="home_main">
<!-- responsible for managing the L&F (skin) of this pane -->
<window-manager ref="MyYahooWM"/>
<!-- responsible for the layout of the pane contents -->
<layout-manager ref="MultiColumnManager">
<column-max>3</column-max>
</layout-manager>
<!--
<entry ref="rss_jetspeed">
<column>0</column>
</entry>
<entry ref="rss_turbine">
<column>0</column>
</entry>
<entry ref="rss_jakarta.apache.org">
<column>1</column>
</entry>
</pane>
<pane name="user_tools"/>
<pane name="hobbies_left"/>
<pane name="hobbies_right"/>
</panes>
<screenlets>
<screenlet name="rss_jakarta.apache.org">
<portlet ref="RSS"/>
<url>http://jakarta.apache.org/overview.rss</url>
<show-description>false</show-description>
<max-items>5</max-items>
</screenlet>
<screenlet name="..."/>
</screenlets>
</configuration>
[Note; this markup is just for description purpose and may be different
than the one actually implemented]
[Note: The information stored within these files may actually be persusted
in a relational SQL database or LDAP directory for complex sites
requiring a high-performance, distributed backend. ]
The administrator may have to configure several configuration files for
supporting various usage profiles of his site.
- general layout registry
This registry describes the available global layout elements available.
It mainly describes the window and layout managers available.
example:
<registry>
<layout-manager name="MultiColumnManager">
<classname>org;apache.jetspeed.managers.VelocityManager</classname>
<template>multi_column.vm</template>
</layout-manager>
<window-manager name="MyYahooWM">
<classname>org;apache.jetspeed.managers.VelocityManager</classname>
<template type="html">my_yahoo.vm</template>
<template type="wml">my_yahoo_wml.vm</template>
</window-manager>
</registry>
[Note; this markup is just for description purpose and may be different
than the one actually implemented]
- portlet registry
The administrator may also need to modify the portlet registry in order
to add specific portlets for his site.
The portlet registry is part of the reusable component model of Jetspeed and
will be described in the Portlet container desxcription.
Note 1:
It's possible to emulate the current layout behavior by using the following
template
jetspeed1_2.vm
$jetspeed.Pane("default")
and defining as many configuration files as there are site pages, all defining
the "default" pane.
Note 2:
The new PSML syntax will have the following properties :
- no recursive definitions: a pane element cannot contain another pane
- separation of contexts: the panes element will only contain layout and
skin properties, the entries element will only contain portlet operational
definitions.
Managers
========
2 types of managers are used within the layout system:
Window managers
---------------
Their role is to decorate customizable elements with visual aids and
links for accessing the portal operation for a given element (for example
customize, maximize, minimize, reemove, etc...).
A window manager may be specified at the following place:
- in a configuration element: it applies for all the portal pages and all
the panes unless overridden by a more specific manager.
- in a pane element, it applies for all the pane elements but not the
pane itself
- in a template, where it applies either for the complete template when
speficied stand-alone (overriding any pane specific manager) or
applying only for a pane when specified as an argument to this pane.
Layout managers
---------------
Layout managers are responsible for positioning the contents of
a pane according to the layout properties attached to an entry and
render the complete pane content.
Portal operations
=================
Links
-----
In order to help building the site navigation between pages or between
portlets, panes, etc... The Jetspeed engine will also provide in the
template context a link object which can be used to build links to
other configurations, pages, panes, screenlets. This link may also
specify a pre-defined portal action.
Example:
$jetspeed.link
-> self-referential link
$jetspeed.link.setConfiguration("work_html")
-> display same template in another configuration
$jetspeed.link.setConfiguration("work_html").setAction("Customize")
-> customize the given configuration
$jetspeed.link.setPane("user_tools").setAction("Minimize")
-> minimize the user_tools pane in the current template
$jetspeed.link.setPane("user_tools").setEntry(2).setAction("Info")
-> display information on the third entry of the user_tools pane
Customization
-------------
Portal customization will enable the user to do the following operations:
- create a new configuration
- modify the properties of a pane
- modify the contents of a pane (adding/removing entries or changing their
layout properties)
- modify the parameters of a given portlet
If a user customizes any element, the portal will always implicitly create
a user-specific configuration if it does not already exists.
During a page layout, the user-specific configuration will always be searched
first for a given pane or entry. If its doesn't contain the pane, the portal
will fallback to the default configuration.
When a single entry is customized and the user specific configuration does
contain the appropriate pane, the whole pane is copied first in the user
configuration.
Multi-device operation
======================
* It is anticipated that a given portal configuration will usually only
support one media-type (for example: default HTML conf, default WML conf,
etc...).
This behavior is dependent on the Profiler implementation.
* A site page may or may not be media-type dependant, depending on the
administrator writing the page template
* A pane definition is meda-type independant but may contain media-dependant
elements. In case some element doesn't handle a given media-type when
rendered, it is ignored.
* For some media-type, the template rendered output may be post-processed
by an adapter which may modify the generated output.
* If an adpater is configured for a given media-type, it will also act
as an URL cache and returns responses without content regeneration.
Example:
* WML without adapter:
user A - request home page --> RequestMapper (selects template)
|
V
Profiler (selects configuration)
|
V
user A <--- send response -- template rendering
The rendered content may actually be unreadable by user A because of
size of the aggregated result
* WML with adapter:
user A - request home page --> RequestMapper (selects adapter)
|
V
WMLAdapter (selects template)
|
V
Profiler (selects configuration)
|
V
template rendering
|
V
Adapter (parses result and fragment
| result in smaller chunk)
V
user A <--- send response -- first result chunk
user A - request chunk 2 --> RequestMapper (selects adapter)
|
V
WMLAdapter (chunk required, fetch from cache)
|
V
user A <--- send response -- second result chunk
Items yet to be defined
=======================
* All the markup languages used for configuration need to be completely
specified
* The jetspeed toolbox available whithin templates must be fully
described
* Should we allow the use of variables as entry parameters within pane
definitions ?
* Are there any specific requirements for handling form submissions ?
--
Raphaël Luta - [EMAIL PROTECTED]
Vivendi Universal Networks - Services Manager / Paris
--
--------------------------------------------------------------
To subscribe: [EMAIL PROTECTED]
To unsubscribe: [EMAIL PROTECTED]
Search: <http://www.mail-archive.com/[email protected]/>
List Help?: [EMAIL PROTECTED]
