You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jetspeed-dev@portals.apache.org by we...@apache.org on 2005/12/07 23:38:03 UTC
svn commit: r354882 -
/portals/jetspeed-2/trunk/xdocs/guides/guide-decorators.xml
Author: weaver
Date: Wed Dec 7 14:37:59 2005
New Revision: 354882
URL: http://svn.apache.org/viewcvs?rev=354882&view=rev
Log:
Updated decroations guide (unfinnished)
Modified:
portals/jetspeed-2/trunk/xdocs/guides/guide-decorators.xml
Modified: portals/jetspeed-2/trunk/xdocs/guides/guide-decorators.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/xdocs/guides/guide-decorators.xml?rev=354882&r1=354881&r2=354882&view=diff
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-decorators.xml (original)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-decorators.xml Wed Dec 7 14:37:59 2005
@@ -19,6 +19,7 @@
<title>Guide to Jetspeed Decoration</title>
<subtitle>Documentation for Designers working with Jetspeed Decorations</subtitle>
<authors>
+ <person name="Scott T Weaver" email="weaver@apache.org"/>
<person name="David Sean Taylor" email="taylor@apache.org"/>
</authors>
</properties>
@@ -26,20 +27,172 @@
<section name="Introduction to Decorators">
<p>
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.
-Decorators define how a single portal page is aggregated. A layout is made up of:
-<ul>
- <li>One or more templates</li>
- <li>A template descriptor</li>
- <li>Images</li>
- <li>A Stylesheet (CSS)</li>
- <li>Macros</li>
-</ul>
+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.
</p>
<p>
- <img src='images/layouts/layouts-overview.png'/>
+ There are two different types of decorations that are used when building a page; Portlet and Layout (or page).
+ <p>
+ 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.
+ </p>
+ <p>
+ 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: <a href="guide-psml.html">Documentation for Designers working with PSML</a>
+ 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.
+ </p>
+
</p>
</section>
+<section name="Decoration File Structure">
+ All decorations are store in a directory directly off of the web applications
+ root called <code>decrorations</code>. The two primary directories under the
+ here are <code>layout</code> for layout decorations and <code>portlet</code>
+ for portlet decorations. Individual decoartions are housed in thier own directories
+ underneath these two directories. The name of the directory you create for under either
+ <code>layout</code> or <code>portlet</code> is how Jetspeed will locate your decoration. We
+ will go into further detail on how this works later on in this guide.
+</section>
+
+<section name="Anatomy of a Layout(Page) Decoration">
+ <subsection name='Four Files in a Nutshell'>
+ <p>
+ In it's most basic form a Layout Decroation only requires you to define
+ four files:
+ <ul>
+ <li>decorator.properties</li>
+ <li>styles.css</li>
+ <li>header.vm</li>
+ <li>footer.vm</li>
+ </ul>
+ Three of these files; decorator.properties, header.vm, and footer.vm go directly into
+ the directory you create under <code>/decorations/layout</code>. The styles.css needs
+ to be put into a subdirectory of your decoration names <code>css/</code>.
+ </p>
+ </subsection>
+
+ <subsection name='Basic Decoration Configuration: decorator.properties'>
+ <p>
+ The decorator.properties file holds basic information about your layout
+ decoration. In all actuallity, this file can be blank, but we still require
+ it is 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.
+ <table>
+ <tr>
+ <th>Property Name</th>
+ <th>Description</th>
+ <th>Default</th>
+ </tr>
+ <tr>
+ <td>base.css.class</td>
+ <td>
+ 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.
+ </td>
+ <td>Defaults to the name of your decoration</td>
+ </tr>
+ <tr>
+ <td>stylesheet</td>
+ <td>Relative path to your decoration's stylesheet</td>
+ <td>css/styles.css</td>
+ </tr>
+ <tr>
+ <td>header</td>
+ <td>Relative path to your decoration's header template</td>
+ <td>header.vm</td>
+ </tr>
+ <tr>
+ <td>footer</td>
+ <td>Relative path to your decoration's footer template</td>
+ <td>footer.vm</td>
+ </tr>
+ </table>
+ </p>
+ </subsection>
+ <subsection name='Top o' the Page to ya: header.vm'>
+ <p>
+ This represnts the top portion of your portal page. Below is a section
+ by section walkthrough of the basics required to write a funtional header
+ template.
+ <br/><br/>
+ <strong>NOTICE:</strong> 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.
+ </p>
+ <p>
+ <![CDATA[
+ <html>
+ <head>
+ #defineLayoutObjects()
+ ]]>
+ <br/>
+ The first two lines should be obvious, if they are not this guide, from here
+ on out will not be much help to you ;-)
+ <br/><br/>
+ Now the line containing <i>#defineLayoutObjects()</i> will not be as obvious in its
+ purpose as the previous two. <i>#defineLayoutObjects()</i> it was 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 <code>WEB-INF/jetspeed_macros.vm</code>.
+ 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 <i>#defineLayoutObjects()</i>.
+ <i>#defineLayoutObjects()</i> values within your header.vm that will be accessible within itself,
+ footer.vm, other macros and all of your portlet decoration templates. We could easily stop here
+ regarding <i>#defineLayoutObjects()</i>, 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
+ code:
+ <code>
+ <![CDATA[
+ #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
+ ]]>
+ </code>
+ <br/><br/>
+ Hmm. What is actually happening here. Okay first off we have, <code>#set()</code>, this is what is known as a
+ directive in Velocity. A directive is built-in functionallity and not a macro. <code>#set()</code>
+ 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 <code>$JS2RequestContext.locale</code> come 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 <code>$someObject</code> notation. Knowing that much invoking a method
+ , let's getFoo(), can be done just like this <code>$someObject.getFoo()</code>. Even cooler is the
+ fact we can short-hand getter methods that don't take any arguments like this,
+ <code>$someObject.foo</code>. As for this <code>$JS2RequestContext</code> this is actually
+ an instance of the <code>org.apache.jetspeed.RequestContext</code> that has been availble to Velocity
+ by Jetspeed itself. So, by looking the javadoc for <code>org.apache.jetspeed.RequestContext</code> we see
+ <code>$JS2RequestContext.locale</code> will give us an instance of <code>java.util.Locale</code> that reperesnts
+ the locale of the current user. Couldn't be much simpler than that could it?
+ <br/><br/>
+ Next up we have this line <code>#set($rootFragment = $jetspeed.currentFragment)</code> another set()
+ statement, this time creating an object called <code>$rootFragment</code> which is an instance of
+ <code>org.apache.jetspeed.page.om.page.ContentFragment</code>. It is really not relevant to this guide
+ to describe what <code>$jetspeed.currentFragment</code> is doing so I am going to skip that and move on.
+ <br/><br/>
+ <code>
+ #set($site = $request.getAttribute("org.apache.jetspeed.portalsite.PortalSiteRequestContext"))
+ <br/>
+ #set($theme = $request.getAttribute("org.apache.jetspeed.theme"))
+ </code>
+ <br/>
+ Ah $request, now that looks familiar, this is actually an instance of <code>javax.servlet.http.HttpServletRequest</code>
+ we are retreiving to objects that have been placed into Velocity by Jetspeed
+ <code>org.apache.jetspeed.portalsite.PortalSiteRequestContext</code> and
+ <code>org.apache.jetspeed.decoration.Theme</code> respectively.
+ </p>
+
+ </subsection>
+</section>
+<!--
<section name='Packaging'>
<p>
Layouts are packaged in a JAR file. Supported decorators:
@@ -87,7 +240,7 @@
character language and country codes.
</p>
</section>
-
+-->
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org