Decorators are defined as any static or semi-static markup surrounding a dynamically generated Fragment. Decorators are usually written with either Velocity or JSP templates. This guide will focus primarily on using the Velocity scripting language to build decoration. However, most of the standards and approaches described here can be applied to writing decroations in other scripting languages.
There are two different types of decorations that are used when building a page; Portlet and Layout (or page).
Portlet decorations are the "window dressings" of Jetspeed. They wrap each indivual portlet fragment's rendered content with HTML (XHTML, VXML, etc). Portlet decoration's are responsible for displaying the appropriate title and any buttons associated with changing window states or portlet modes.
Layout or Page decorations responsible for providind a "header" area and "footer" area for a single portal page which is represented by a .psml document (see: Documentation for Designers working with PSML for more information on psml). They also provide general style information for the page and portlets. However, portlet level style settings can be overidden at the portlet decoration level.
All decorations are stored in a directory directly off of the web applications
decorations. The two primary directories under the
layout for layout decorations and
for portlet decorations. Individual decoartions are housed in their own directories
underneath these two directories. The name of the directory you create for under either
portlet is how Jetspeed will locate your decoration. We
will go into further detail on how this works later on in this guide.
In it's most basic form a Layout Decroation only requires you to define four files:
/decorations/layout. The styles.css needs to be put into a subdirectory of your decoration names
The decorator.properties file holds basic information about your layout decoration. In all actuallity, this file can be blank, but we still require that it be present as it is used by other APIs to "discover" available decorations. With that being said, it is safe to assume that all the properties defined below are optional.
|base.css.class||This value is generally placed in the top most element tag of your header template. You will see how it is used when we go into development of a header template.||Defaults to the name of your decoration|
|stylesheet||Relative path to your decoration's stylesheet||css/styles.css|
|header||Relative path to your decoration's header template||header.vm|
|footer||Relative path to your decoration's footer template||footer.vm|
The header.vm represnts the top portion of your portal page. Below is a section
by section walkthrough of the basics required to write a functional header
NOTICE: It is assumed that the reader is proficient in both the use of HTML and CSS. A rudimentary knowledge of Velocity helps but is not required to develop a decoration.
<html> <head> #defineLayoutObjects()
Now the line containing
#defineLayoutObjects() will not be as obvious in its
purpose as the previous two.
#defineLayoutObjects() is what is known, in
Velocity vernacular, as a macro. A macro is a predefined snippet of Velocity
code that can be reused within any Velocity template. All of the global macros
we will be using (including this one) are defined within the
Later in this guide we will discuss supplying your own, custom macros for assisting
you in your decoration development, if you choose to. Now, back to the
#defineLayoutObjects() adds values to Velocity that will be accessible within header.vm,
footer.vm, other macros and all of your portlet decoration templates. We could easily stop here
#defineLayoutObjects(), however, I feel it can be helpful to have some
insights into the inner workings of Velocity for the uninitiated. With out further ado, the
#macro (defineLayoutObjects) #set($preferedLocale = $JS2RequestContext.locale) #set($rootFragment = $jetspeed.currentFragment) #set($site = $request.getAttribute("org.apache.jetspeed.portalsite.PortalSiteRequestContext")) #set($theme = $request.getAttribute("org.apache.jetspeed.theme")) #set($layoutDecoration = $theme.getDecoration($rootFragment)) #end
#set(), this is what is known as a directive in Velocity. A directive is built-in functionallity and not a macro.
#set()is pretty straight forward in that it takes the value on the right of the = and assigns it to the left. Cool, that seems fairly straight forward. But how does one work with these values and where the heck did
$JS2RequestContext.localecome from? I guess i should take a quick step back and describe how we work with objects in Velocity. All objects available to a Velocity template can be referenced via the
$someObjectnotation. Knowing that much invoking a method , let's getFoo(), can be done just like this
$someObject.getFoo(). Even cooler is the fact we can short-hand getter methods that don't take any arguments like this,
$someObject.foo. As for this
$JS2RequestContextthis is actually an instance of the
org.apache.jetspeed.RequestContextthat has been availble to Velocity by Jetspeed itself. So, by looking the javadoc for
$JS2RequestContext.localewill give us an instance of
java.util.Localethat represents the locale of the current user. Couldn't be much simpler than that could it?
#set($rootFragment = $jetspeed.currentFragment)another set() statement, this time creating an object called
$rootFragmentwhich is an instance of org.apache.jetspeed.om.page.ContentFragment. It is really not relevant to this guide to describe what
$jetspeed.currentFragmentis doing so I am going to skip that and move on.
#set($site = $request.getAttribute("org.apache.jetspeed.portalsite.PortalSiteRequestContext"))
#set($theme = $request.getAttribute("org.apache.jetspeed.theme"))
$request, now that looks familiar, this is actually an instance of
javax.servlet.http.HttpServletRequestfrom which we are retreiving objects that were been placed into Velocity by Jetspeed. The actual objects are: org.apache.jetspeed.portalsite.PortalSiteRequestContext and org.apache.jetspeed.decoration.Theme respectively. We will put all of these objects to good use in just a little while.
This section provides you with all the information to properly code the <HEAD> of your Layout decroation. So, straight to the code.
First off we have
<base href="#BaseHref()"> which allows
us to define the base path for resolution of web resources, for an in depth discussion
<base> see: W3C Schools Reference.
If you have spent any time playing with Jetspeed, you will have noticed it does all sorts
of crazy URL rewriting that will totally hose any attempts to consistently path you html
and styles sheets. By defining the BASE tag, this probelms will all but disappear. As
#BaseHref() macro, it simply generates a fully qualified path to your
web application's root. The actual code, interms of the servlet api is synonimous with this:
HttpServletRequest request; StingBuffer baseHref = new StringBuffer(request.getScheme()) .append("://").append(request.getServerName()) .append(":").append(request.getServerPort()) .append(request.getContextPath()).append("/"); return baseHref.toString();
Will return text/html plus the proper encoding, such as UTF.
The JSP decorators are only currently supported in the tigris decorator. The JSP decorators are not enabled by default. JSP decorators can be enabled by modifying (properly commented) settings in:
Note: you need to change the settings in *all* of the above properties files, and then restart jetspeed.
Also note: for the tcolumns template there isn't a JSP replacement (yet), but that isn't much used anyway AFAIK. Just to be sure: don't switch your page layout portlet(s) from columns to tcolumns, otherwise your page will be be broken.