Raphael,
thank you for taking the time to write this excellect description !
See some first comments and questions below.
Raphael Luta wrote:
> [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".
The meaning of the term "screenlet" cannot easily be found out without the
definition. Perhaps we might use a more self-explaining term like
"portlet view" ?
> 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.
An administrator needs not necessarily be the owner of the entire
portal. There may be cases where a portal consists of a number of
independent portal instances. Each of these instances may have one
or more administrators.
> 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.
What does the last sentence mean ?
> 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.
What is the toolbox object ?
> 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.
Is "$" used for macro-ivocation ?
> - 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>
I think it is a good idea to separate the layout/L&F from the definition
of individual portlet views.
> [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. ]
Yes, potentially, the database may contain a record for each registered
portlet, portlet view, pane, ...
I think we need a carefully designed interface for accessing this
information
which should be equally suited for persistence in databases as well as XML
files. Below the interface, providers for database or XML-file persistence
should be pluggable.
> 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
I think we also have to specify a portal content model and an OO API to
access it. Then we can define a default reperesentation of that model in
an appropriate markup language.
> * The jetspeed toolbox available whithin templates must be fully
> described
Can you give examples of the functionality you would envision in the
toolbox ?
> * Should we allow the use of variables as entry parameters within pane
> definitions ?
Can you give examples ?
> * Are there any specific requirements for handling form submissions ?
I think we need a generic mechanism transparent to portlet programmers that
assures that form submissions are routed to the right destination (e.g.
portlet)
through the portlet container.
>
> --
> 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]
