Author: weaver
Date: Thu Dec 8 12:55:29 2005
New Revision: 355207
URL: http://svn.apache.org/viewcvs?rev=355207&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=355207&r1=355206&r2=355207&view=diff
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-decorators.xml (original)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-decorators.xml Thu Dec 8
12:55:29 2005
@@ -19,7 +19,7 @@
<title>Guide to Jetspeed Decoration</title>
<subtitle>Documentation for Designers working with Jetspeed
Decorations</subtitle>
<authors>
- <person name="Scott T Weaver" email="[EMAIL PROTECTED]"/>
+ <person name="Scott T Weaver" email="[EMAIL PROTECTED]"/>
<person name="David Sean Taylor" email="[EMAIL PROTECTED]"/>
</authors>
</properties>
@@ -34,164 +34,222 @@
<p>
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>
-
+ 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">
<p>
- All decorations are stored 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.
-</p>
+ All decorations are stored 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.
+</p>
</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>
+ <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
- 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.
- <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 name='Basic Layout 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
+ 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.
+ <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
functional 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>
+ <p>
+ The <strong>header.vm</strong> represnts the top portion of your
portal page. Below is a section
+ by section walkthrough of the basics required to write a functional
header
+ template.
<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>
-
+ <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>
+<source>
+<![CDATA[
+<html>
+ <head>
+ #defineLayoutObjects()
+]]></source>
+ The first two lines should be obvious, if they are not, this guide
from here
+ on out will not be much help to you ;-)
+
+ <h4>Our First Macro: #defineLayoutObjects()</h4>
+ <p>
+ Now the line containing <code>#defineLayoutObjects()</code> will
not be as obvious in its
+ purpose as the previous two. <code>#defineLayoutObjects()</code>
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
<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 <code>#defineLayoutObjects()</code>.
+ <code>#defineLayoutObjects()</code> 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
+ regarding <code>#defineLayoutObjects()</code>, 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:
+<source>
+<![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
+]]></source>
+
+ 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
+ <a
href="http://portals.apache.org/jetspeed-2/multiproject/jetspeed-api/apidocs/org/apache/jetspeed/om/page/ContentFragment.html";>org.apache.jetspeed.om.page.ContentFragment</a>.
+ 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 <code>$request</code>, now that looks familiar, this is
actually an instance of <code>javax.servlet.http.HttpServletRequest</code>
+ from which we are retreiving objects that were been placed into
Velocity by Jetspeed. The actual objects are:
+ <a
href="http://portals.apache.org/jetspeed-2/multiproject/jetspeed-api/apidocs/org/apache/jetspeed/portalsite/PortalSiteRequestContext.html";>org.apache.jetspeed.portalsite.PortalSiteRequestContext</a>
+ and
+ <a
href="http://portals.apache.org/jetspeed-2/multiproject/jetspeed-api/apidocs/org/apache/jetspeed/decroation/Theme.html";>org.apache.jetspeed.decoration.Theme</a>
+ respectively. We will put all of these objects to good use in
just a little while.
+ </p>
+ <h4>Feed Your HEAD: How to Properly Code Your Head Tag.</h4>
+ <p>
+ This section provides you with all the information to prperly
code the
+ <HEAD> of your Layout decroation. So, straight to the
code.
+ <source>
+<![CDATA[
+<html>
+ <head>
+ #defineLayoutObjects()
+
+ <base href="#BaseHref()">
+ <meta http-equiv="Content-type" content="#ContentType()" />
+ <meta http-equiv="Content-style-type" content="text/css" />
+ #includeJavaScriptForHead()
+ #IncludeStylesheets()
+ <title>#PageTitle()</title>
+ <meta name="description" content="#PageDescription()" />
+]]></source>
+ </p>
+
+ </p>
+ <h5>The <base> Tag</h5>
+ <p>
+ First off we have <code><![CDATA[ <base
href="#BaseHref()">]]></code> which allows
+ us to define the base path for resolution of web resources, for
an in depth discussion
+ of the <code><![CDATA[ <base>]]></code> see: <a
href="http://www.w3schools.com/tags/tag_base.asp";>W3C Schools Reference</a>.
+ 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
+ for the <code>#BaseHref()</code> 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:
+<source>
+HttpServletRequest request;
+StingBuffer baseHref = new StringBuffer(request.getScheme())
+ .append("://").append(request.getServerName())
+ .append(":").append(request.getServerPort())
+ .append(request.getContextPath()).append("/");
+return baseHref.toString();
+</source>
+ The actual Velocity macro code is a bit more terse ;)
+<source>
+${request.scheme}://${request.serverName}:${request.serverPort}${request.contextPath}/
+</source>
+ </p>
+ <h5>Meta Tag: <![CDATA[<meta http-equiv="Content-type"
content="#ContentType()" />]]></h5>
+ <p>
+ Will return text/html plus the proper encoding, such as UTF.
+ </p>
+ <h5>#includeJavaScriptForHead()</h5>
+ <p>
+ At the time of the writing of this guide there is really very little
javascript
+ required to for the base Jetspeed 2 server to run. However this may
change in
+ near future as we try to employ the use of AJAX in things such as
configuration
+ and administration.
+ </p>
</subsection>
</section>
<!--
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
