The features described in this section are mostly new to Jetspeed 1.4b2. This documentation is a living document that may reflect changes that will occur until the release is out.
The Jetspeed layout engine uses a configurable matching algorithm to determine the type of content format to return to the client. This matching is based on the following parameters:
Media types represent the different document formats supported by the portal and are defined in the central Registry.
These media types definition typically associatee a well known MIME type with one or more required capabilities that will be used to differentiate between user-agents.
For example, in this registry definition, the "html" media type represents the markup that can be sent to full-blown HTML 3.2 client, supporting features like tables and images while the "htmlite" can be used to service user agrents without any table capabilities and "htmltext" will service user-agents without any image support.
The client descriptions, which are also stored in the Registry, provide the portal engine with a simple definition of the client specific rendering capabilities.
A simple client entry will be typically composed of the following elements:
This user-agent pattern, defined by a regular expression, will be tested against incoming User-agent identification header to identify it.
This list details all the MIME types supported by this client, in descending order of preference
These optional capabilities help identify the actual client characteristics for the different supported MIME Types and select the corect media type. There's currently no formal capability defintions but they should match with those used in the Media types definition to have any effect.
Since clients user agent identification strings are matched against the different client definitions pattern, the order of the definitions in the registry is important as the most specific patterns must be listed first else the generic ones will prevent them from being used.
There are actually 2 matching algorithms used in cunjunction with the client detection capabilities.
The first one is used to determine, for a client user-agent, on ordered list of media types supported by this client.
For example, for a user agent string of "Lynx/3.2 (Windows; U; NT 5.0) [en]" and the above Media and Client definitions, the algorithm will output the following list of ordered media types:
This algorithm is implemented in the BaseCapabilityMap implementation of
the CapabilityMap interface.
The other algorithm is used to include this list of supported media types into the profile and template finding algorithms.
These algorithms will use this media list to iterate through all the media types before defaulting to a generic no media search. A typical search path would thus be:
This section details how to modify an out of the box Jetspeed installation to support 3 different sets of clients: Internet Explorer 4+ compatible, Netscape Navigator 4 compatible and W3C DOM compatible (Mozilla, Opera, etc...). This can be very useful if you plan to make heavy use of advanced CSS and DOM.
To achieve the above plan, we decide to use the default "html" media to represent be W3C compliant and we'll create 2 variants, one called "ie5" for Internet Explorer like browsers and the other "ns4" for Netscape 4. These different entries will be differentiated based on their DHTML and TABLE capabilities since Netscape 4 has a known deficiency in handling deeply nested table.
Before going further in customizing your site, make sure that the Client definition provided by Jetspeed will correctly match your target user agent with the intended media type. If run with DEBUG enabled, Jetspeed will write in your log file the user agent string recieved and how it has been matched.
Based on the above definitions and the defaule client.xreg registry, you should have the following results:
| browser | list of selected medias |
|---|---|
| Internet Explorer 5+ | ie5 html ns4 xml |
| Netscape Navigator 4.x | ns4 html ie5 |
| Mozilla 1.x | html ie5 ns4 xml |
| Lynx | html ie5 ns4 |
| Konqueror | ns4 html ie5 |
Note that Opera is not listed because it would change depending on the user-agent announced configured in Opera and Konqueror is mapped to ns4 because it has no explicit matching client definition in the registry. In order to properly map these browsers to "html" media as expected, we would need to update the default client.xreg to add at the beginning of the file :
You can now start creating browser specific templates by creating "ie5" and "ns4" directories where necessary and defining your templates there. The search mechanism settings will ensure that if no specific "ns4" or "ie5" resource is found, the default "html" one will be used so that you don't have to duplicate all your templates that don't use any browser specific features.
In this scenario, there's probably no need to consider setting up specific PSML resources for "ie5" or "ns4" but for some other usage scenarios it may be useful.
The capability API defined in package org.apache.jetspeed.capability is very
simple since it consists only of one CapabiltyMap interface and one
CapabilityMapFactory factory.
The default CapabilityMap implementation is a wrapper around a
Registry ClientEntry.
The CapabilityMap associated with a request can be retrieved from
the JetspeedRunData object with the getCapability() method
and can thus be used by default in all the Velocity templates if you wish to test for
a specific capability.
The first example presents how a portlet can programatically adjust its content based on the CapabilityMap:
The same effect can be achieved within a VelocityPortlet template by using the following sequence:
#end Hello $data.Capability.Agent #if $data.Capability.hasCapability("HTML_TABLE")