jford 2004/04/08 14:53:58
Added: tutorial/xdocs/12 index.xml paramstylearchitecture.xml
Log:
Converted Chapter 12 tutorial to xdoc format
Revision Changes Path
1.1 jakarta-jetspeed/tutorial/xdocs/12/index.xml
Index: index.xml
===================================================================
<?xml version="1.0"?>
<!--
Copyright 2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<document>
<properties>
<author email="[EMAIL PROTECTED]">David Sean Taylor</author>
<title>Parameter Styles</title>
</properties>
<body>
<section name="Parameter Styles">
<p>
Parameter styles are custom widgets which allow you to present portlet parameter
using something other than the default input text box control. These widgets can be as
simple as text area control or as complex as a pop up calendar control.
In this tutorial, you will learn how to:
</p>
<p>
<ul>
<li>1. Write a simple parameter style</li>
<li>2. Modify the stock quote portlet from the VelocityPortlet tutorial to use
parameter styles</li>
</ul>
</p>
<p>Let's get started. From the JPortal distribution root directory, type:</p>
<source>
ant tutorial-12
</source>
<p>
Recommend bringing up these files in your editor:
</p>
<p>
<ul>
<li>1. webapp/WEB-INF/conf/t12-portlets.xreg</li>
<li>2. webapp/WEB-INF/conf/templates/vm/parameters/html/InputWithHelp.vm </li>
<li>3. webapp/WEB-INF/conf/templates/vm/portlets/html/tutorial-stock-quote.vm </li>
<li>4.
webapp/src/java/com/bluesunrise/jportal/modules/actions/portlets/TutorialStockQuoteAction.java</li>
</ul>
</p>
<p>
since we will refer to them in Tutorial 12.
</p>
</section>
</body>
</document>
1.1 jakarta-jetspeed/tutorial/xdocs/12/paramstylearchitecture.xml
Index: paramstylearchitecture.xml
===================================================================
<?xml version="1.0"?>
<!--
Copyright 2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<document>
<properties>
<author email="[EMAIL PROTECTED]">David Sean Taylor</author>
<title>Parameter Styles Architecture</title>
</properties>
<body>
<section name="Parameter Styles Architecture">
<p>
Parameter styles have been implemented using the Turbine <a
href="http://jakarta.apache.org/turbine/turbine-2/fsd.html";>module</a> mechanism. For
those of you not familiar with Turbine, <a
href="http://jakarta.apache.org/turbine/turbine-2/fsd.html";>modules</a> are webapp
resources (screens, actions, layouts, navigations, etc) which may be loaded
dynamically based on a predefined module search path.
</p>
<p>
A Portlet parameter is defined in a registry entry as having a custom presentation
style by setting its type attribute to <b>"style"</b> and then adding additional
portlet parameters to define the style name and any style options. The additional
parameters are linked to a parameter via the parameter name.
</p>
<p>
<b>Popup Calendar Date Style</b>
</p>
<p>
In the example below, we have a widget named <b>"date"</b> whose style is
<b>"PopupCalendar"</b>, and the style format string is <b>"mm/dd/yyyy"</b>.
</p>
<p>
<source>
<![CDATA[
<parameter name="date" value="" type="style" hidden="false">
<meta-info>
<title>Date</title>
<description>Date with popup calendar. Format pattern: mm/dd/yyyy
</description>
</meta-info>
</parameter>
<parameter name="date.style" value="PopupCalendar" hidden="true"/>
<parameter name="date.style.format" value="mm/dd/yyyy" hidden="true"/>
]]>
</source>
</p>
<p>
<b>Velocity Parameter Style</b>
</p>
<p>
In the example below, we have a widget named <b>"password"</b> whose style is
<b>"VelocityParameterPresentationStyle"</b>.
This is a very flexible parameter style, which allows you to reuse a velocity
template to format the presentation of your widget.
Velocity Parameter Style templates should be placed in the Jetspeed deployment under
<b>/WEB-INF/templates/vm/parameters/html</b> (for HTML portlets). Similarly, WML
portlets would be found under <b>/WEB-INF/templates/vm/parameters/wml</b>.
The resolution of portlet templates is based on several configuration files and a
resolution algorithm.
See the section on <a
href="http://www.bluesunrise.com/jetspeed-docs/JetspeedTutorial.htm#_7.4_Template_Resolution";>Template
Resolution</a> for more details.
</p>
<p>
<source>
<![CDATA[
<parameter name="password" value="secret" type="style" hidden="false"/>
<parameter name="password.style"
value="VelocityParameterPresentationStyle" hidden="true"/>
<parameter name="password.style.template" value="Password.vm"
hidden="true"/>
]]>
</source>
Velocity Parameter Style
</p>
<p>
<b>JSP Parameter Style</b>
</p>
<p>
In the example below, we have a widget named <b>"password"</b> whose style is
<b>"JSPParameterPresentationStyle"</b>.
This is a very flexible parameter style, which allows you to reuse a JSP template to
format the presentation of your widget.
JSP Parameter Style templates should be placed in the Jetspeed deployment under
<b>/WEB-INF/templates/jsp/parameters/html</b> (for HTML portlets).
Similarly, WML portlets would be found under
<b>/WEB-INF/templates/jsp/parameters/wml</b>.
The resolution of portlet templates is based on several configuration files and a
resolution algorithm.
See the section on <a
href="http://www.bluesunrise.com/jetspeed-docs/JetspeedTutorial.htm#_7.4_Template_Resolution";>Template
Resolution</a> for more details.
</p>
<p>
<source>
<![CDATA[
<parameter name="password" value="secret" type="style" hidden="false"/>
<parameter name="password.style" value="JspParameterPresentationStyle"
hidden="true"/>
<parameter name="password.style.template" value="Password.jsp" hidden="true"/>
]]>
</source>
JSP Parameter Style
</p>
<p>
<source>
<![CDATA[
## InputWithHelp.vm
#set ($src = $parms.get("src")) ## Retrieve the "src" parameter from the $parms map
<input type="text" name="$name" value="$value" size="30" disabled>
<img src="$src" alt="Info" #foreach($event in $events.keySet())
$event="$events.get($event)"#end>
]]>
</source>
</p>
<p>
<source>
<![CDATA[
<parameter name="about" value="About Bluesunrise Stock Quote Web Service"
type="style" hidden="false"/>
<parameter name="about.style" value="VelocityParameterPresentationStyle"
hidden="true"/>
<parameter name="about.style.template" value="InputWithHelp.vm" hidden="true"/>
<parameter name="about.style.src" value="images/info.gif" hidden="true"/>
<parameter name="about.style.javascript.onclick" value="alert('For additional info
on the stock quote web service contact [EMAIL PROTECTED]')" hidden="true"/>
]]>
</source>
</p>
<p>
<source>
<![CDATA[
package com.bluesunrise.jportal.modules.actions.portlets;
// Turbine stuff
import org.apache.turbine.util.Log;
import org.apache.turbine.util.RunData;
import org.apache.turbine.services.TurbineServices;
// Velocity Stuff
import org.apache.velocity.context.Context;
// Jetspeed stuff
import org.apache.jetspeed.portal.portlets.VelocityPortlet;
import org.apache.jetspeed.webservices.finance.stockmarket.StockQuoteService;
import org.apache.jetspeed.webservices.finance.stockmarket.StockQuote;
import org.apache.jetspeed.util.PortletConfigState;
import org.apache.jetspeed.util.StringUtils;
/**
* This action sets up the template context for retrieving stock quotes.
*
*/
public class TutorialStockQuoteAction extends VelocityPortletAction
{
private static final String SYMBOLS = "symbols";
private static final String COLUMNS = "columns";
private static final String SORT = "sort";
private static final String QUOTES = "quotes";
private static final String[] ALL_COLUMNS = {"Symbol","Price","Change","Volume"};
private static final String SELECTED_COLUMNS = "selected-columns";1
/**
* Build the normal state content for this portlet.
*
* @param portlet The velocity-based portlet that is being built.
* @param context The velocity context for this request.
* @param rundata The turbine rundata context for this request.
*/
protected void buildNormalContext(VelocityPortlet portlet, Context context, RunData
rundata)
{
try
{
// Get reference to stock quote web service
StockQuoteService service = (StockQuoteService)
TurbineServices.getInstance().
getService(StockQuoteService.SERVICE_NAME);
// Retrieve portlet parameters
String symbols = PortletConfigState.getParameter(portlet, rundata, SYMBOLS,
"IBM,MSFT,ORCL,SUNW");
String columns = PortletConfigState.getParameter(portlet, rundata, COLUMNS,
StringUtils.arrayToString(ALL_COLUMNS, ","));2
String[] selectedColumnsArray = StringUtils.stringToArray(columns, ",");3
String sort = PortletConfigState.getParameter(portlet, rundata, SYMBOLS,
"Symbol");4
// Request stock quote(s) from the stock quote web service
String[] symbolArray = StringUtils.stringToArray(symbols, ",");
StockQuote[] quotes = service.fullQuotes(symbolArray);
// Place appropriate objects in Velocity context
context.put(QUOTES, quotes);
context.put(SELECTED_COLUMNS, selectedColumnsArray);5
context.put(COLUMNS, columns);6
}
catch (Exception e)
{
Log.error(e);
}
}
]]>
</source>
</p>
<p>
So far the changes are related to stock quote column selection:
</p>
<p>
<ul>
<li>1. The SELECTED_COLUMN will be placed in the Velocity context as list of
selected column headings.</li>
<li>2. The columns variable will hold user customized value of columns selected for
display. Please note the usage of PortletConfigState.getParameter() method to retrieve
the value of COLUMNS from user's PSML.</li>
<li>3. Here we convert columns which is in a comma-delimited format to a string
array selectedColumnsArray.</li>
<li>4. For the sake of example, we can also retrieve a custom sort setting. We will
not be implementing the actual sort though.</li>
<li>5. The selectedColumnsArray is placed in the Velocity context so the template
can use it as headings.</li>
<li>6. The columns is placed in the Velocity context so the template can determine
which stock quote fields to dsiplay.</li>
</ul>
</p>
<p>
Next, here's a modified Velocity template tutorial-stock-quote.vm used to display
the stock quotes:
</p>
<p>
<source>
<![CDATA[
## tutorial-stock-quote.vm
<table>
<tr>
<td>
<table border="true" cellspacing="1" cellpadding="3">
<tr>
#foreach ($column in $selected-columns)
#headerCell ($column)
#end
</tr>
#foreach ($quote in $quotes)
<tr>
#if ($columns.indexOf("Symbol") >= 0) #entryCell ($quote.Symbol)
#end
#if ($columns.indexOf("Price") >= 0) #entryCell ($quote.Price)
#end
#if ($columns.indexOf("Change") >= 0) #entryCell ($quote.Change)
#end
#if ($columns.indexOf("Volume") >= 0) #entryCell ($quote.Volume)
#end
</tr>
#end
</table>
</td>
</tr>
</table>
]]>
</source>
</p>
<p>
<source>
<![CDATA[
<portlet-entry name="TutorialStockQuote" hidden="false" type="ref" parent="Velocity"
application="false">
<meta-info>
<title>Tutorial Stock Portfolio with parameter styles</title>
<description>Tutorial Stock Portfolio Portlet with parameter
styles</description>
</meta-info>
<parameter name="template" value="tutorial-stock-quote2" hidden="true"/>
<parameter name="action" value="portlets.TutorialStockQuoteAction2"
hidden="true"/>
<parameter name="sort" value="Symbol" type="style" hidden="true">
<meta-info>
<title>Sort</title>
<description>Sort is not implemented</description>
</meta-info>
</parameter>
<parameter name="sort.style" value="ListBox" hidden="true"/>
<parameter name="sort.style.items" value="Symbol,Price,Change,Volume"
hidden="true"/>
<parameter name="columns" value="Symbols,Price,Change,Volume" type="style"
hidden="false">
<meta-info>
<title>Columns</title>
<description>Columns to display</description>
</meta-info>
</parameter>
<parameter name="columns.style.items" value="Symbol,Price,Change,Volume"
hidden="true"/>
<parameter name="columns.style.layout" value="$eastwest" hidden="true"/>
<parameter name="columns.style" value="CheckBoxGroup" hidden="true"/>
<parameter name="symbols" value="MSFT,IBM,ORCL,SUNW" type="style" hidden="false">
<meta-info>
<title>Symbols</title>
<description>List of comma-separated stock symbols</description>
</meta-info>
</parameter>
<parameter name="symbols.style" value="TextArea" hidden="true"/>
<parameter name="About" value="About Stock Quote Web Service" type="style"
hidden="false"/>
<parameter name="About.style" value="VelocityParameterPresentationStyle"
hidden="true"/>
<parameter name="About.style.template" value="InputWithHelp.vm" hidden="true"/>
<parameter name="About.style.src" value="images/info.gif" hidden="true"/>
<parameter name="About.style.javascript:onclick" value="alert('For additional
contact [EMAIL PROTECTED]')" hidden="true"/>
<media-type ref="html"/>
<category group="Jetspeed">tutorial</category>
</portlet-entry>
]]>
</source>
</p>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
