portals-jetspeed-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From wea...@apache.org
Subject svn commit: r354882 - /portals/jetspeed-2/trunk/xdocs/guides/guide-decorators.xml
Date Wed, 07 Dec 2005 22:38:03 GMT
Author: weaver
Date: Wed Dec  7 14:37:59 2005
New Revision: 354882

URL: http://svn.apache.org/viewcvs?rev=354882&view=rev
Updated decroations guide (unfinnished)


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>
+	  <person name="Scott T Weaver" email="weaver@apache.org"/>
       <person name="David Sean Taylor" email="taylor@apache.org"/>
@@ -26,20 +27,172 @@
 <section name="Introduction to Decorators">
 Decorators are defined as any static or semi-static markup surrounding a dynamically generated
-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:
-  <li>One or more templates</li>
-  <li>A template descriptor</li>
-  <li>Images</li>
-  <li>A Stylesheet (CSS)</li>
-  <li>Macros</li>  
+Decorators are usually written with either Velocity or JSP templates.  This guide will focus
+on using the Velocity scripting language to build decoration.  However, most of the standards
+approaches described here can be applied to writing decroations in other scripting languages.
-    <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
+	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>
+<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 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
+		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&apos; 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,
+		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,
+		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
+		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 name='Packaging'>
 Layouts are packaged in a JAR file. Supported decorators: 
@@ -87,7 +240,7 @@
 character language and country codes.

To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org

View raw message