Building Portals with Cocoon
http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Main
Dev Guide

Webapps
Overview
Session Contexts
Authentication
Portal

Introduction

The portal engine of Cocoon provides the required functionality to display user dependent content with a user defineable layout.

The Cocoon portal defintion framework is an XML description of the portal and the contained content. The rendering of the portal to the needed format (such as HTML) is done through stylesheets and is therefore very flexible.

A portal definition can be configured for all users (global), for groups of users (group or role) and for the individual user. The portal admininstrator can use the provided tools to configure every aspect of the portal (from colours to content).

Each "blob" of portal content is contained in a "coplet" (Cocoon portlet). coplets can be configured into the portal on a per-user or per-group basis allowing a flexible content definition.

coplets can be minimized, maximized or even removed by the user if he does not wish to see the content. However, the administrator may configure coplets to be mandatory, in which case they may not be removed.

The different portals are administrated by authentication applications. Each application can have its own portal.

This documentation explains the different resources for the portal, the configuration of a portal and how it creates the portal view derived from this information. After that all is put together by creating the needed entries in the sitemap for using and displaying a portal.

The Profile

A portal is built upon a profile which contains all necessary information: the portal possibilites (the available coplets, the possible changes to the layout etc.) and the portal view (the layout for this user and the coplets he chose for himself). This profile is generated when a user logs into the application the portal belongs to. The building of the profile is a very flexible process which allows to have different configurations for different users.

In general the building of the profile consists of four steps:

  1. Building the base profile. This profile defines which possibilites the portal has, which coplets are available to the portal and which parts of the profile can be changed by the user.
  2. Building the global profile. The base profile is enhanced by a global delta which contains a predefined portal view. This predefined portal view is a starting point for all users.
  3. Building the role profile. The global profile is enhanced by a role delta which contains a predefined portal view. This predefined portal view is a starting point for all users of that role.
  4. Building the user profile. The role profile is augmented by a user delta which contains the portal for this specific user. An optional user status profile with often changing information can optional be appended to the profile.

Only step 1 and 2 are mandatory for the building process. Steps 3 and 4 are optional and depend on the configuration of the users and roles in the system.

Each delta (steps 2, 3 and 4) can modify the possibilites of the portal and the configuration of the coplets. But it is not allowed to add new features or coplets. In addition a delta may contain a predefined portal view.

This building process is invoked each time the user logs into the application. So a change to any profile (delta) is incorporated into the user profile: If e.g. a coplet , which a user has choosen for his portal view, is removed from the system, it is not available to the user anymore and therefore also removed from his portal view.

The global delta, the role delta and the user delta are very similar. They only differ in the name of the root node.

The Base Profile

The base profile consists of three data sources:

  1. The layout profile describes the possibilites and layout of the portal.
  2. The coplets profile defines all available coplets for the portal view.
  3. The type profile describes the parts of the profile which can be changed by the user.
The Layout Profile

The layout profile describes the overall layout of the portal including if header or footer are present which colors and fonts are used and so on.

An example profile is shown below. The profile is enclosed in the root node "layout-profile" and consists of the "portal" part and the "coplets" part: 

<layout-profile>
  <portal>
    <!-- This node contains the layout of the portal view -->
    <layouts>
      <layout>
        <!-- The color of the background -->
        <background>
          <color>#ffffff</color>
        </background>
        <!-- The font and color for usual text -->
        <font>
          <type>Arial, Helvetica, sans-serif</type>
          <size>2</size>
          <color>black</color>
        </font>
      </layout>
    </layouts>
    <!-- The following means that the portal has a header area -->
    <header>
      <exists>true</exists>
    </header>
    <!-- The following means that the portal has 3 columns -->
    <columns>
      <number>3</number>
    </columns>
    <!-- The following means that the portal has not a footer area -->
    <footer>
      <exists>false</exists>
    </footer>
  </portal>
  <coplets>
    <!-- This node contains the layout of the coplets -->
    <layouts>
      <layout>
        <title>
          <!-- The layout of the title -->
          <background>
            <color>#46627A</color>
          </background>
          <font>
            <type>Arial</type>
            <size>2</size>
            <color>#ffffff</color>
          </font>
        </title>
        <content>
          <!-- The layout of the content -->
          <font>
            <type>Arial</type>
            <size>2</size>
            <color>#000000</color>
          </font>
          <background>
            <color>#ffffff</color>
          </background>
        </content>
      </layout>
    </layouts>
  </coplets>
</layout-profile>
The coplets Profile

The coplets profile contains all coplets which are available in the system. It is an XML based resource with the root node "coplets-profile". All coplets are defined under a node called "coplets", so an example profile could look like this: 

    <coplets-profile>
  <coplets>
    <coplet id="bankingnews">
      <resource uri="cocoon://coplet-banking.xml"/>
      <transformation>
        <!-- optional xsl transformation -->
        <stylesheet>sunbank/styles/coplet.xsl</stylesheet>
      </transformation>
      <configuration>
        <mandatory>false</mandatory>
        <sizable>true</sizable>
        <active>true</active>
        <timeout>5000</timeout>
        <!-- optional, milliseconds -->
        <messages>
          <!-- optional: Messages -->
          <coplet_not_available>
                           Display this if the coplet is not available.
                        </coplet_not_available>
        </messages>
      </configuration>
      <title>Banking News</title>
      <status>
        <visible>true</visible>
        <size>max</size>
      </status>
    </coplet>
  </coplets>
</coplets-profile>

This example defines one coplet: the bankingnews coplet with the title "Banking News". The title is displayed in the portal view above the coplet content. The most important part is the resource definition. Using this resource the coplet is displayed in the portalview of the user.

  • An uri, e.g.: <resource uri=".."/>. This URI can be a local one which is retrieved using the sitemap or a distant one which is retrieved using an HTTP request. In both cases the resource must deliver valid XML for the coplet content. If you don't use a protocol, the URI is assumed to be a file.
  • A java class delivering the content.

There a several mandatory configuration parameters for a coplet. This configuration parameters can only be changed by the portal administrator. The user cannot change them for his portal view.

  • mandatory: Indicates if the coplet can be removed by the user or if it is always visible.
  • sizable: Is the coplet sizable? If the value is true the user can minimize this coplet in his portal view.
  • active: Using this parameter, a coplet can be deactivated for a distinct period of time. If a coplet is not active it will not displayed to the user even if he has configured it.

In addition there are some optional parameters:

  • timeout: This is the time in milliseconds, the portal waits to get the coplet content. If the content is not available within this time frame, the coplet is declared as not available at the moment. The default value for the timeout can be set in the portal configuration (see next chapter).
  • handlesSizable: If this value is true, the coplet (or better the resource) handles the sizing of this coplet itselt. This means it determines the data to be displayed if the coplet is minimized or maximized. If this value is false the portal displayes the whole coplet if it is maximized and only its title if it is minimized. This is the default behaviour.
  • handlesParameters: If this value is true (which is the default value) the resource gets all configuration and status parameters passed, e.g. if the resource is an uri, the parameters are passed as HTTP request parameters.
  • messages/coplet_not_available: If the coplet is not available (e.g. external data where the server is not available), a message is displayed. With this optional parameter each coplet can get a distinct message which overrides the message provided by the user profile.

The status parameters can be changed by the user for configuring his own portal view:

  • visible: If a coplet is visible it is included in the portal view. If it is not visible it is still configured for the user but it will not displayed.
  • size: Currently two sizes (min and max) are distinquished.

If the source of the coplet needs additional transformation there are two possibilities for doing the transformation. The first one is creating a pipeline in the sitemap for this coplet and the second one usses the coplet configuration for this. As the first one is the usual pipeline creating process only the second one is covered here.

By defining the "transformation" node inside the "coplet" node, the source of the coplet can be transformed with one or more stylesheets. For each stylesheet a "stylesheet" node with the value of the stylesheet path has to be created. The order of appearance determines the order of processing. If e.g. the source of a coplet is a class or a file, there is no need to specify a pipeline only for this coplet. Specifying a file/class as source and a "stylesheet" node has the same effect.

Adding a new coplet

Adding new information to the portal requires four basic steps:

  • Defining the resource containing the information. For external resources only the address (mainly an URI) and the protocol (usually HTTP) is required. Otherwise a new XML resource has to be created with the new content.
  • Defining the stylesheet for the presentation of this content.
  • For local resources: Definition of the pipeline in the sitemap. This pipeline must contain all necessary steps for building the information. It must deliver XML as the serialized format.
  • Adding a new "coplet" node to the coplets profile.

After these steps are finished, the new coplet is automatically available for each user which logs in after the addition. If the coplet is even mandatory it will be added to the portal view of the user.

For more information see the chapter "The Pipelines".

Customizable coplets

Each coplet can have its own configuration, e.g. a weather coplet should display the weather for a particular city etc. 

    <coplets-profile>
  <coplets>
    <coplet id="bankingnews">
      <resource uri="cocoon://coplet-banking.xml"/>
      <customization uri="cocoon://customize-coplet-banking.xml"/>
      <!-- optional -->
      <transformation>
        <!-- optional xsl transformation -->
        <stylesheet>sunbank/styles/coplet.xsl</stylesheet>
      </transformation>
      <configuration>
        <mandatory>false</mandatory>
        <sizable>true</sizable>
        <active>true</active>
        <timeout>5000</timeout>
        <!-- optional, milliseconds -->
        <messages>
          <!-- optional: Messages -->
          <coplet_not_available>
                           Display this if the coplet is not available.
                        </coplet_not_available>
        </messages>
        <customizable>true</customizable>
        <!-- optional -->
        <persistent>false</persistent>
        <!-- optional -->
      </configuration>
      <title>Banking News</title>
      <status>
        <visible>true</visible>
        <size>max</size>
      </status>
    </coplet>
  </coplets>
</coplets-profile>

To declare a coplet as customizable it must get a configuration resource which is displayed to a user of this coplet to enter all required configuration values. This is done with the customization tag. The value for this tag has the same possibilities as the resource tag, usually the uri attribute points to a pipeline.

When a user has configured/choosen a customizable coplet, the portal detects if this coplet has its configuration. If it does not have one, the customization resource of the coplet is displayed in the portal view. Otherwise the coplet itself is displayed.

In addition a customizable coplet can be persistent, e.g. the configuration is saved for a longer period than the current session of the user. If the coplet is not persistent the configuration is lost when the user logs out. The next time he logs in, the customization page is displayed to configure this coplet again.

If you use persistent coplets you have to configure resources for loading and saving the status profile (See configuration). More about writing customizable coplets can be found in the chapter "Writing Customizable coplets".

The Type Profile

The type profile describes the possible values the user can change for his portal view. Using this flexible approach the portal administrator can decide which user can choose what. For example, a normal user might change the layout and content of his portal view, but a guest might not be allowed to change anything, whereas the administrator can change everything.

The type profile is surrounded by the root node "type-profile". It consists of two parts: the typedefs section and the elements section. The type profile can be compared with a programming language. The typedefs section declares all available types and the the elements section declares all variables with their corresponding types. A "variable" defines a place or element in the user profile which can be changed by the user. The possibilites for this element are defined by the type.

The typedefs contains enumerations, e.g. a set of possible values with a user presentable name. In addition the portal has the following predefined types: STRING (arbitrary text), BOOLEAN (true or false), INTEGER (a number) and CARDINAL (a positiv number). 

<type-profile>
  <typedefs>
    <!-- The following types are defined by the portal: (Names are casesensitiv!)
                          STRING, BOOLEAN, ENUMERATION, INTEGER, CARDINAL -->
    <typedef name="backgroundcolor" type="ENUMERATION">
      <value name="weiss">#ffffff</value>
      <value name="hellgrau">#cccccc</value>
      <value name="hellgruen">#aab9bf</value>
      <value name="dunkelgruen">#46627A</value>
    </typedef>
    <typedef name="textcolor" type="ENUMERATION">
      <value name="weiss">white</value>
      <value name="schwarz">black</value>
      <value name="weiss">#ffffff</value>
      <value name="hellgrau">#cccccc</value>
      <value name="hellgruen">#aab9bf</value>
      <value name="dunkelgruen">#46627A</value>
    </typedef>
    <typedef name="copletsize" type="ENUMERATION">
      <value name="Maximized">max</value>
      <value name="Minimized">min</value>
    </typedef>
    <typedef name="columnnumber" type="ENUMERATION">
      <value name="1">1</value>
      <value name="2">2</value>
      <value name="3">3</value>
      <value name="4">4</value>
      <value name="5">5</value>
    </typedef>
  </typedefs>
</type-profile>

The element section has the same structure a the user profile. For each leave which is changeable by the user the elements section contains an entry for the type of this node. The node is enhanced by two attributes: type for the node type and description for a user readable title. This information is used by the portal to present the configuration screen for the portal. It displayes for each changeable leave a form field with the corresponding type. 

<type-profile>
  <elements>
    <layout-profile>
      <portal>
        <layouts>
          <layout>
            <!-- The user can change the background.
                          The possible values are taken from the enumeration
                          backgroundcolor. The user gets the title "Background"
                          displayed for the form field. -->
            <background>
              <color type="backgroundcolor" description="Background"/>
            </background>
            <font>
              <color type="textcolor" description="Font color"/>
            </font>
          </layout>
        </layouts>
        <columns>
          <!-- The user can change the number of columns -->
          <number type="columnnumber" description="Number of columns"/>
        </columns>
      </portal>
    </layout-profile>
    <portal-profile>
      <content>
        <!-- Using the * the following configuration is applied for
                      all columns regardless of their position. -->
        <column position="*">
          <width type="CARDINAL" description="Width"/>
          <coplets>
            <!-- Using the * the following configuration is applied for
                              each coplet. -->
            <coplet id="*" position="*" number="*">
              <status>
                <!-- The user can change the visibility and size
                                  of the coplet -->
                <visible type="BOOLEAN" description="Visible"/>
                <size type="copletsize" description="Size"/>
              </status>
            </coplet>
          </coplets>
        </column>
      </content>
    </portal-profile>
  </elements>
</type-profile>
The Global Profile

The global delta, the role delta and the user delta are very similar. They only differ in the name of the root node. So this chapter only describes the global delta and points out the differences between the deltas at the various place rather than repeating the same information in different chapters.

The global delta is enclosed in the root node "global-delta", the role delta uses the node "role-delta" and the user delta the node "user-delta".

In general a delta defines the differences between two profiles. The portal deltas allow only adding and changing but not removing nodes. Each delta can contain the following parts:

  • The layout delta containing the difference to the layout profile.
  • The coplets delta describing the differences to the coplets profile.
  • The portal profile containing a complete portal view. This part is not a delta. If it is contained in a delta and the profile already has this information, that information is replaced by the one from the delta. Otherwise the delta information is added. For the global profile the portal profile is mandatory.
  • The personal profile. This part contains personal information of the user, e.g. are welcome text. For the global profile this information again is mandatory. It defines the possibilites the user has. The role and the user profile can only change this information. But they cannot add any new nodes.

So here is an example: 

<global-delta>
  <!-- No difference to the base profile -->
  <layout-delta/>
  <!-- No difference to the base profile -->
  <coplets-delta/>
  <!-- This is the starting portal view for all users.
         It has to be defined in the global profile -->
  <portal-profile>
    <!-- This is the content of the portal view -->
    <content>
      <header>
        <coplet id="personalize" position="1">
          <status>
            <visible>true</visible>
            <size>max</size>
          </status>
        </coplet>
      </header>
      <column position="1">
        <width>28%</width>
        <!-- The coplets are displayed in the order of their
                     position attribute in each column. -->
        <coplets>
          <coplet id="administration" number="1" position="1">
            <status>
              <visible>true</visible>
              <size>max</size>
            </status>
          </coplet>
        </coplets>
      </column>
      <column position="2">
        <width>50%</width>
        <coplets>
          <coplet id="banknews" number="2" position="1"/>
        </coplets>
      </column>
      <column position="3">
        <width>22%</width>
        <coplets/>
      </column>
    </content>
  </portal-profile>
  <personal-profile>
    <greeting>Herzlich willkommen</greeting>
    <messages>
      <coplet_not_available>
        The coplet is currently not available.
      </coplet_not_available>
    </messages>
  </personal-profile>
</global-delta>
The User Status Profile

The user status profile contains often changing information like the configuration of configurable coplets, the last login time etc. The user status profile is optional, but if it is not accessible, customizable coplets are not possible.

For each customizable coplet which is in the portal view of the user the status profile contains an XML block with the coplet specific configuration for this coplet. 

<status-profile>
  <customization>
    <!-- Custom information for each customizable coplet -->
    <coplet id="popmail" number="3">
      <host>mail</host>
      <password>gsgdgsg</password>
      <mailcount>4</mailcount>
      <user>walter</user>
    </coplet>
  </customization>
</status-profile>
Configuring the portal

The configuration of the portal is actually a authentication application configuration. Please refer to the authentication documentation for more information about authentication handler and application configuration.

Inside your authentication handler configuration you define for each portal an application configuration for the portal like the example portal called "sunBank" below: 

    <application name="sunBank">
  <configuration name="portal">
    <!-- This is the portal configuration -->
    <portal-uri>finance-portal</portal-uri>
    <profile-cache>true</profile-cache>
    <process-coplets-parallel>false</process-coplets-parallel>
    <default-coplet-timeout>10000</default-coplet-timeout>
    <profile>
      <!-- The resource for loading the layout profile -->
      <layout-base uri="cocoon://financeresource-layoutprofile"/>
      <!-- The resource for loading the base coplets profile -->
      <coplet-base uri="cocoon://financeresource-copletprofile"/>
      <!-- The optional resource for saving the base coplets profile -->
      <coplet-base-save uri="cocoon://financeresource-savecopletprofile"/>
      <!-- The optional type resource -->
      <type-base uri="cocoon://financeresource-types"/>
      <!-- The optional type resource for the admin configuration -->
      <admin-type-base uri="cocoon://financeresource-admintypes"/>
      <!-- The resources for loading/saving the deltas -->
      <global-delta-load uri="cocoon://financeresource-globalprofile"/>
      <global-delta-save uri="cocoon://financeresource-saveglobalprofile"/>
      <role-delta-load uri="cocoon://financeresource-roleprofile"/>
      <role-delta-save uri="cocoon://financeresource-saveroleprofile"/>
      <user-delta-load uri="cocoon://financeresource-userprofile"/>
      <user-delta-save uri="cocoon://financeresource-saveuserprofile"/>
      <!-- Optional resources for loading/saving the status profile
                     which is required for persistent, customizable coplets -->
      <user-status-load uri="cocoon://financeresource-loadstatusprofile"/>
      <user-status-save uri="cocoon://financeresource-savestatusprofile"/>
      <!-- optional type resources -->
      <global-type-delta uri="..."/>
      <role-type-delta uri="..."/>
      <user-type-delta uri="..."/>
    </profile>
    <!-- Redirect to this resource, if the user is not authenticated
                 to view that coplet -->
    <auth-redirect>finance-portal</auth-redirect>
  </configuration>
</application>
Global Portal Configuration

One mandatory configuration value for the portal is the portal-uri. It must point to a pipeline which produces the portal view for a user (see next section for more information about the pipelines).

Profile Caching

The portal contains an intelligent profile caching mechanism which detects automatically changes to profiles and determines upon this information which profile must be rebuild.

Without profile caching a profile is build each time a user logs in. With profile caching the profile is only build if there is no cached profile or if something has changed in the profiles for this user. Only the user status profile is not cached at all as it is often changing.

By specifying the profile-cache tag in the the portal configuration with the value true the profile caching is turned on. If the tag is not available no profile caching is performed.

If profile caching is turned on, the profiles should not be changed by hand as the cache does not detect such changes. All changes to the profiles must be done using the portal tools. However if you change a profile or part of a profile by hand, make sure that you clean the cache afterwords. Cleaning the cache can be done either by the provided the portal tools or by deleting all files inside the cache directory.

Global coplet configuration

Usually the portal view is generated step by step, e.g. the coplets are build one after the other. The portal can be configured to get the coplets content parallel to decrease the response time for the portal view. By specifying the process-coplets-parallel tag with the value true, the coplets are processed parallel.

If the content of a coplet is not available, e.g. if the contentresides on an external HTTP server, the processing of this coplet can take a "very long" time, e.g. until a timeout occures. The portal monitors the coplets and can stop the processing of a coplet after a distinct period of time. This period can be specified by the tag "default-coplet-timeout" in milliseconds. If the content of the coplet is not available after the time has expired, the coplet is declared as "not available". The default timeout is 10 minutes.

For a fine-tuning of coplet timeouts, each coplet can get its own timeout (see the sections below).

Profile Resources

Each part of the profile has a corresponding resource which is invoked for loading or saving the profile part, e.g. one resource for loading the global profile delta and a separate one for saving it. The loading resources must deliver the xml described in the previous chapters.

All resources get the parameter "application" with the name of the corresponding application and "handler" with the name of the authentication handler. The list below shows the additional parameters for the other resources.

  • coplet-base: "profile" with value "coplet-base"
  • coplet-base-save: "profile" with value "coplet-base"
  • layout-base: "profile" with value "layout-base"
  • type-base: "profile" with value "type-base"
  • admin-type-base: "profile" with value "admin-type-base"
  • global-delta-load: "profile" with value "global-delta"
  • global-type-delta: "profile" with value "global-type-delta"
  • global-delta-save: "profile" with value "global-delta"
  • role-delta-load: "profile" with value "role-delta", "role" with name of the role
  • role-delta-save: "profile" with value "role-delta", "role" with name of the role
  • role-type-delta: "profile" with value "role-type-delta", "role" with role name
  • user-delta-load: "profile" with value "user-delta", "role" with role name, "ID" with user ID
  • user-delta-save: "profile" with value "user-delta", "role" with role name, "ID" with user ID
  • user-type-delta: "profile" with value "user-type-delta", "role" with role name, "ID" with user ID
  • user-status-load: "profile" with value "user-status", "role" with role name, "ID" with the user ID
  • user-status-save: "profile" with value "user-status", "role" with role name, "ID" with the user ID
The Pipelines

So far the chapters only described configuring the portal and writing resources. This chapter closes the gap and explains the steps for showing the portal.

For defining the pipelines in the sitemap, the portal declares two generators (the "portal" generator and the "portal-conf" generator) and one action ("portal-auth").

Displaying the portal view

Displaying the portal view is a very simple step: defining a pipeline with the "portal" as the generator, the auth-protect action for defining the application and an stylesheet for creating the presentation: 

<map:match pattern="sunbank-portal">
  <map:act type="auth-protect">
    <!-- for getting the portal configuration -->
    <map:parameter name="handler" value="portalhandler"/>
    <map:parameter name="application" value="sunBank"/>
    <map:generate type="portal"/>
    <!-- generate the portal view -->
    <map:transform src="sunbank/styles/portalHTML.xsl"/>
    <!-- presentation in HTML -->
    <map:serialize/>
  </map:act>
</map:match>
The Generated Portal View

The XML generated by the "portal" generator is not exactly the same as for the user profile. The portal optimizes and reorganizes the profile. All fields (or nodes) which are changeable have the attributes "formdescription", "formpath" and "formtype". "formdescription" is a user readable description of the field, "formpath" is the name of the form parameter which can be used to set the value and "formtype" indicates the type of the field. The belonging type can be found in the types section of the profile. 

<!-- The portal indicates that the following is the portal view -->
<portal>
  <!-- The configuration of the portal -->
  <configuration>
    <!-- This is the uri which should be invoked for rebuilding the portal view
             and for changing the view. The parameter portalprofile is always
             present and indicates the current profile. -->
    <uri>finance-portlets?portalprofile=uprofile:sunBank:user_admin_cocoon</uri>
    <!-- This is the uniquie portal profile ID -->
    <profile>uprofile:sunBank:user_admin_cocoon</profile>
    <media>html</media>
    <!-- The current media: html or wap -->
  </configuration>
  <!-- Now the needed part of the layout profile: -->
  <layout>
    <portal>
      <background>
        <color formdescription="Hintergrundfarbe" formpath="portalconf.0.0" formtype="backgroundcolor">#aab9bf</color>
      </background>
      <font>
        <type>Arial, Helvetica, sans-serif</type>
        <size>2</size>
        <color formdescription="Schriftfarbe" formpath="portalconf.1.0" formtype="textcolor">black</color>
      </font>
    </portal>
    <coplets>
      <title>
        <background>
          <color>#46627A</color>
        </background>
        <font>
          <type>Arial</type>
          <size>2</size>
          <color>#ffffff</color>
        </font>
      </title>
      <content>
        <background>
          <color>#000000</color>
        </background>
        <font>
          <type>Arial</type>
          <size>2</size>
          <color>#ffffff</color>
        </font>
      </content>
    </coplets>
  </layout>
  <!-- This is the portal view: -->
  <header>
    <coplet id="personalize" position="1" number="1">
      <resource uri="financecoplet-personalize.xml"/>
      <configuration>
        <mandatory>true</mandatory>
        <sizable>true</sizable>
        <active>true</active>
      </configuration>
      <title>Personalisieren</title>
      <status>
        <visible>true</visible>
        <size>max</size>
      </status>
      <content>..the coplet content...</content>
    </coplet>
  </header>
  <columns number="3">
    <column position="1" width="28%">
      <coplet id="administration" position="1" number="1">
        <resource uri="financecoplet-administration.xml"/>
        <configuration>
          <mandatory>false</mandatory>
          <sizable>true</sizable>
          <active>true</active>
        </configuration>
        <title>Portal Administration</title>
        <status>
          <visible formdescription="Sichtbar" formpath="portalconf.4.0" formtype="BOOLEAN">true</visible>
          <size formdescription="Groesse" formpath="portalconf.5.0" formtype="copletsize">max</size>
        </status>
        <content>..the coplet content...</content>
      </coplet>
                        ....
                 </column>
    <column position="2" width="50%">
            ...
            </column>
    <column position="3" width="22%">
            ...
                 </column>
  </columns>
  <!-- The personal information -->
  <personal-profile>
    <greeting>Hi there!</greeting>
    <messages>
      <coplet_not_available>The coplet is currently not available.</coplet_not_available>
    </messages>
  </personal-profile>
</portal>
Administration of the portal view

Displaying the administration page of the portal is as simple as displaying the portal. The difference lies in changing the generator to the "portal-conf" generator: 

<map:match pattern="sunbank-conf">
  <map:act type="auth-protect">
    <map:parameter name="handler" value="portalhandler"/>
    <map:parameter name="application" value="sunBank"/>
    <map:generate type="portal-conf"/>
    <map:transform src="sunbank/styles/portalconfHTML.xsl"/>
    <map:serialize/>
  </map:act>
</map:match>

Make sure to protect the portal configuration generator as the administrator can change all profiles, clear the cache etc. It should only be available for real portal administrators.

The Generated Administration View

The XML generated by the "portal-conf" generator is not exactly the same as the user profile. The portal addes some information to the profile. All fields (or nodes) which are changeable have the attributes "formdescription", "formpath" and "formtype". "formdescription" is a user readable description of the field, "formpath" is the name of the form parameter which can be used to set the value and "formtype" indicates the type of the field. The belonging type can be found in the types section of the profile. 

<!-- The portalconf node indicates that the following is the portal administration view -->
<portalconf>
  <!-- The configuration of the portal -->
  <configuration>
    <!-- This is the uri which should be invoked for rebuilding the portal view
             and for changing the view. The parameter portalprofile is always
             present and indicates the current profile. -->
    <uri>finance-portlets?portalprofile=uprofile:sunBank:user_admin_cocoon</uri>
    <!-- This is the uniquie portal profile ID -->
    <profile>uprofile:sunBank:user_admin_cocoon</profile>
    <media>html</media>
    <!-- The current media: html or wap -->
  </configuration>
  <!-- The layout profile, see chapter about the layout profile -->
  <layout-profile>
    <portal>
      <layouts>
        <layout>
          <background>
            <color formdescription="Hintergrundfarbe" formpath="portalconf.0.0" formtype="backgroundcolor">#aab9bf</color>
          </background>
          <font>
            <type>Arial, Helvetica, sans-serif</type>
            <size>2</size>
            <color formdescription="Schriftfarbe" formpath="portalconf.1.0" formtype="textcolor">black</color>
          </font>
        </layout>
      </layouts>
      <header>
        <exists>true</exists>
      </header>
      <columns>
        <number formdescription="Anzahl" formpath="portalconf.2.0" formtype="columnnumber">3</number>
      </columns>
      <footer>
        <exists>false</exists>
      </footer>
    </portal>
    <coplets>
      <layouts>
        <layout>
          <title>
            <background>
              <color>#46627A</color>
            </background>
            <font>
              <type>Arial</type>
              <size>2</size>
              <color>#ffffff</color>
            </font>
          </title>
          <content>
            <font>
              <type>Arial</type>
              <size>2</size>
              <color>#000000</color>
            </font>
            <background>
              <color>#ffffff</color>
            </background>
          </content>
        </layout>
      </layouts>
    </coplets>
  </layout-profile>
  <!-- The coplets profile, see chapter about the coplets profile -->
  <coplets-profile>
    <coplets>
      <coplet id="banknews">
        <resource uri="onlinecoplet-banking.xml"/>
        <configuration>
          <mandatory>false</mandatory>
          <sizable>true</sizable>
          <active>true</active>
        </configuration>
        <title>Banking News</title>
        <status>
          <visible>true</visible>
          <size>max</size>
        </status>
      </coplet>
             ...
            </coplets>
  </coplets-profile>
  <!-- The type profile, see the chapter about the type profile -->
  <typedefs>
         ...
     </typedefs>
  <!-- And now the portal view, see chapter about the portal profile -->
  <portal-profile>
    <content>
      <header>
        <coplet id="personalize" position="1" number="1">
          <status>
            <visible>true</visible>
            <size>max</size>
          </status>
        </coplet>
      </header>
      <column position="1">
        <width formdescription="Breite" formpath="portalconf.3.0" formtype="CARDINAL">28%</width>
        <coplets>
          <coplet id="administration" position="1" number="2">
            <status>
              <visible formdescription="Sichtbar" formpath="portalconf.4.0" formtype="BOOLEAN">true</visible>
              <size formdescription="Groesse" formpath="portalconf.5.0" formtype="copletsize">max</size>
            </status>
          </coplet>
                               ...
                        </coplets>
      </column>
      <column position="2">
                   ...
                    </column>
      <column position="3">
                   ...
                    </column>
    </content>
  </portal-profile>
  <!-- The personal profile, see the corresponding chapter -->
  <personal-profile>
    <greeting>Hi there!</greeting>
    <messages>
      <coplet_not_available>The coplet is currently not available.</coplet_not_available>
    </messages>
  </personal-profile>
</portalconf>
Changing the Profile

The profile can be changed using a HTTP request. The invoked resources is the uri defined in the "configuration" section of the portal view. It contains already the needed parameter "portalprofile" with the given value. This parameter tells the portal which profile it should change.

Each field which is changeable has the parameters "formdescription", "formtype" and "formpath". The "formdescription" is a user-readable text for this field. The "formtype" is the type of the field. It is a type name which has a corresponding entry in the type profile. The type profile contains all possible values for this particular type. The "formpath" contains the name of the field to change. So changing an field is submitting a form value with the name of "formpath" and one of the values denoted by the "formtype".

In addition to this the portal recognizes the special parameter "portalcmd". It can control the appearance of the coplets. The value of the parameter is one of the following followed by '_', the coplet id attribute, another '_' and the coplet number attribute. For example minimizing a coplet is done by passing "portalcmd=minimize_1_3" to the request. The commands are as follows:

  • "maximize" : Maximize the coplet.
  • "minimize" : Minimize the coplet.
  • "close" or "hide" : Close the coplet, it will not be displayed in the portal view, but is still configured.
  • "open" or "show" : A configured coplet will be included in the portal view again.
  • "delete" : Remove the coplet from the profile.
  • "move" : Move the coplet to the column which is append to value separated by '_'. So "portalcmd=move_1_3_2" would move the coplet into the 2nd column.
  • "new" : Add a new coplet to the profile. Only the attribute id of the coplet is passed. Instead of the number attribute the column number is appended. If instead "header" or "footer" is passed instead of the column number, the coplet is moved into that special area.
  • "update" : Change from the customization view of the coplet to the coplet content view.

The profile can be save persistent by sending the parameter "portalcmd" with the value "save"in addition to the "portalprofile" parameter.

Defining coplets

Defining a pipeline for a coplet is also very straightforward. Together with your "real" pipeline for defining the content and doing the presentation, the "auth-protect" action is needed. This action defines the application and portal, the coplet (pipeline) belongs to: 

<map:match pattern="licence-coplet">
  <!-- Get the application configuration -->
  <map:act type="auth-protect">
    <map:parameter name="handler" value="portalhandler"/>
    <map:parameter name="application" value="sunBank"/>
    <!-- secure the coplet: -->
    <map:act type="portal-auth">
      <map:parameter name="coplet" value="licencing"/>
    </map:act>
    <!-- The resource containg the licencing information: -->
    <map:generate src="cocoon/licencing.xml"/>
    <!-- present it in HTML -->
    <map:transform src="sunbank/styles/HTML.xsl"/>
    <!-- Serialize it to XML for including in the portal view: -->
    <map:serialize/>
  </map:act>
</map:match>

In addition you can secure the pipeline of the coplet. So only users who can select this coplet in their profile can invoke the pipeline. This extra protection is performed by the "portal-auth" action: 

<map:match pattern="licence-coplet">
  <!-- Get the application configuration -->
  <map:act type="auth-protect">
    <map:parameter name="handler" value="portalhandler"/>
    <map:parameter name="application" value="sunBank"/>
    <!-- secure the coplet: -->
    <map:act type="portal-auth">
      <map:parameter name="coplet" value="licencing"/>
    </map:act>
    <!-- The resource containg the licencing information: -->
    <map:generate src="cocoon/licencing.xml"/>
    <!-- present it in HTML -->
    <map:transform src="sunbank/styles/HTML.xsl"/>
    <!-- Serialize it to XML for including in the portal view: -->
    <map:serialize/>
  </map:act>
</map:match>

In this example the coplet is protected by the use of the parameter tag inside the "portal-auth" action. Only if the user is allowed to view/configure the coplet with the ID "licencing", he can invoke this resource. If this security command is left out, everyone is able to get the resource by simply invoking it directly from the browser. However, if the coplet is protected it is not necessary that a user has choosen that coplet for his current portal view to invoke the resource. In addition it is possible to specify the parameter without a specific coplet name. This protects the resource as a coplet: Only users which are logged in to the portal can view the resource.

Getting Profile Information within a coplet

Each coplet has access to nearly all information of the profile, including layout information and configuration. The coplet can retrieve this information using a special session context called portal. With the familiar commands of the session transformer (getxml etc.) the information can be included in the current xml stream of a coplet.

The content of the context looks like the following: 

<layout>
  <portal>
    <background>
      <color formdescription="Hintergrundfarbe" formpath="portalconf.0.0" formtype="backgroundcolor">#aab9bf</color>
    </background>
    <font>
      <type>Arial, Helvetica, sans-serif</type>
      <size>2</size>
      <color formdescription="Schriftfarbe" formpath="portalconf.1.0" formtype="textcolor">black</color>
    </font>
  </portal>
  <coplets>
    <title>
      <background>
        <color>#46627A</color>
      </background>
      <font>
        <type>Arial</type>
        <size>2</size>
        <color>#ffffff</color>
      </font>
    </title>
    <content>
      <background>
        <color>#000000</color>
      </background>
      <font>
        <type>Arial</type>
        <size>2</size>
        <color>#ffffff</color>
      </font>
    </content>
  </coplets>
</layout>
<configuration>
  <!-- This is the uri which should be invoked for rebuilding the portal view
             The parameter portalprofile is always
             present and indicates the current profile. -->
  <uri>finance-portlets?portalprofile=uprofile:sunBank:user_admin_cocoon</uri>
  <!-- This is the uniquie portal profile ID -->
  <profile>uprofile:sunBank:user_admin_cocoon</profile>
  <media>html</media>
  <!-- The current media: html or wap -->
</configuration>

Using this information the coplet can layout itself with the layout chosen by the user for the portal. For example a <session:getxml context="portal" path="/layout/coplets/content/background/color"/> is replaced by the session transformer with the color value for the background (here "#000000)".

Writing Customizable coplets

Writing a customizable coplet requires two task:

  1. Creating the resource for the customization of the coplet
  2. Creating a resource for the coplet content which uses the configuration

The resource for the customization is very similar to the "real" resource for the coplet. It is - in most cases - a pipeline which delivers xml and this xml is included in the portal view. Usually this xml contains a form for the user to define the configuration of the coplet.

The configuration of the coplet is available using the special portal session context. For a customizable coplet this context is augmented with the current configuration of the coplet: 

<layout>
    ...
</layout>
<configuration>
    ...
    <context>unique id for the coplet for external applications</context>
</configuration>
<coplet-data>
    ... the configuration ....
</coplet-data>

Using the Cocoon form handling it is very easy to write a customization view for a coplet. The following example dispalys a form for a mail coplet which requires the configuration for a mail host, a user name and a password. 

<page xmlns:session="http://apache.org/cocoon/session/1.0">
  <!-- Define a form -->
  <session:form name="popmail" method="POST">
    <session:action>
      <!-- The action is send to the pipeline redisplaying the portal -->
      <session:getxml context="portal" path="/configuration/uri"/>
    </session:action>
    <!-- Create the input fields for
             host, username and password -->
    <session:content>
      <session:inputxml context="portal" path="/coplet-data/host" name="Host" type="text"/>
      <session:inputxml context="portal" path="/coplet-data/user" name="User" type="text"/>
      <session:inputxml context="portal" path="/coplet-data/password" name="Password" type="password"/>
    </session:content>
    <!-- The submit button -->
    <input type="submit" value="Customize"/>
  </session:form>
</page>

The inputxml tags assure that the information provided by the user is automatically written into the portal context at the places provided.

Writing the resource for the coplet is as easy. The coplet can use the getxml command to retrieve to configuration from the portal context: 

<page xmlns:session="http://apache.org/cocoon/session/1.0">
  <!-- Get the configuration information out of the portal context -->
  <!-- and feed it into the getmail command -->
  <session:getmail>
    <session:user>
      <!-- Set the user -->
      <session:getxml path="/coplet-data/user" context="portal"/>
    </session:user>
    <session:password>
      <!-- Set the password -->
      <session:getxml path="/coplet-data/password" context="portal"/>
    </session:password>
    <session:host>
      <!-- Seet the host -->
      <session:getxml path="/coplet-data/host" context="portal"/>
    </session:host>
  </session:getmail>
</page>

Each time the coplet configuration changes the user status profile is automatically saved.

External Resources and Customizable coplets

External resources which are configured with the same authentication handler and application as the portal can retrieve configuration information from a coplet. If the resource is invoked with the request parameter portalcontext it has access to the same portal context as the coplet.

The value for the request parameter can be retrieved by the calling resource, e.g. the coplet, from the portal context using the path /configuration/context. The external resource must have the portal-auth action configured in its pipeline. The action checks for the request parameter and grants the resource access to the portal context of the coplet.

Copyright © 1999-2002 The Apache Software Foundation. All Rights Reserved.