jford 2004/04/08 16:05:21
Added: tutorial/xdocs/9 index.xml registryconfig.xml
Log:
Start of conversion of the Chapter 9 tutorial to xdoc format
Revision Changes Path
1.1 jakarta-jetspeed/tutorial/xdocs/9/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>DatabaseBrowser Portlet</title>
</properties>
<body>
<section name="DatabaseBrowser Portlet">
<p>Tutorial 9 introduces the Database Browser Portlet. This section covers:</p>
<p>
<ul>
<li>1. Configuration in the Registry</li>
<li>2. Linking to Actions</li>
<li>3. Implementing the Action Events</li>
<li>4. Advanced Parameters</li>
<li>5. Deploy</li>
</ul>
</p>
<p>
Let's get started. From the JPortal distribution root directory, type:
</p>
<p>
<source>
ant tutorial-9
</source>
</p>
<p>
Recommend bringing up these files in your editor:
</p>
<p>
<code>
<ul>
<li>1. webapp/WEB-INF/conf/t9-portlets.xreg</li>
<li>2.
src/java/com/bluesunrise/jportal/modules/actions/portlets/TutorialCoffeesAction.java</li>
<li>3.
src/java/com/bluesunrise/jportal/modules/actions/portlets/CoffeesBrowserAction.java</li>
<li>4. webapp/WEB-INF/psml/user/anon/html/default.psml</li>
<li>5. webapp/WEB-INF/psml/user/turbine/html/default.psml</li>
<li>6. webapp/WEB-INF/templates/vm/portlet/html/coffees-form.vm</li>
<li>7. webapp/WEB-INF/templates/vm/portlet/html/coffees-browser.vm **</li>
</ul>
</code>
** not actually used in demo, but you could extend this later on
</p>
<p>
since we will reference them in tutorial 9. The examples are found under the
"Advanced Tutorials" menu selection.
</p>
</section>
</body>
</document>
1.1 jakarta-jetspeed/tutorial/xdocs/9/registryconfig.xml
Index: registryconfig.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>Configuration in the Registry</title>
</properties>
<body>
<section name="Configuration in the Registry">
<p>
The Database Browser Portlet uses an SQL statement and JDBC to create a database
browser form inside of a portlet.
The browser runs off the Torque connection pools and data sources configured in your
<b>Torque.properties</b> file.
The standard functionality of the browser doesn't require any coding.
The portlet is configured with parameters entered in the portlet registry.
The minimal parameters and attributes required are highlighted below:
</p>
<p>
<source>
<![CDATA[
<portlet-entry name="TutorialCoffeesBrowser" hidden="false" type="ref"
parent="DatabaseBrowserPortlet" application="false">
<meta-info>
<title>Coffees Browser</title>
<description>Browses Over the Coffees Table</description>
</meta-info>
<parameter name="sql" value="select * from coffees"
hidden="false"/>
<parameter name="windowSize" value="15" hidden="false"/>
...
</portlet-entry>
]]>
</source>
</p>
<p>
You must derive the <b>portlet-entry</b> from the <b>DatabaseBrowserPortlet</b>,
which is deployed with the Jetspeed distribution.
This gives you all the base functionality.
The <b>sql</b> parameter provides the query string.
In our example, the string is not hidden so it can be modified by the user.
The <b>windowSize</b> parameter controls how many rows to display in the portlet.
That is all you need. The portlet generates the rest for you:
</p>
<p>
<img border="0" width="553" height="232" src="../images/image054.jpg"/>
</p>
<p>
The database browser portlet is a standard <a href="../.html">Velocity Portlet</a>,
and it has an action, template, and customizer template associated with it.
This three parameters must be entered. You can select default values or implement
your own. In our example, we implement our own action but use the default template and
customizer template. You may want to override these to customize the layout of the
browser. The default templates can be used as the basis for writing your own
templates.
</p>
<p>
<source>
<![CDATA[
<parameter name="template" value=" database-browser-portlet"
hidden="true"/>
<parameter name="customizeTemplate"
value="database-browser-customize" hidden="true"/>
<parameter name="action" value="portlets.CoffeesBrowserAction"
hidden="true"/>
]]>
</source>
</p>
<p>
Our action class extends the default action class to provide the added
functionality of refreshing the browser content by passing a query parameter in the
URL string.
The base class handles everything else.
Here we are overriding the standard Velocity Portlet content generation method, <a
href="http://portals.apache.org/jetspeed-1/apidocs/org/apache/jetspeed/modules/actions/portlets/VelocityPortletAction.html";>buildNormalContext</a>:
</p>
<p>
<source>
<![CDATA[
protected void buildNormalContext( VelocityPortlet portlet,
Context context,
RunData rundata )
{
String refresh =
rundata.getParameters().getString(BROWSER_COMMAND);
if (refresh != null && refresh.equals(BROWSER_REFRESH))
{
this.clearDatabaseBrowserIterator(portlet,rundata);
}
super.buildNormalContext(portlet, context, rundata);
}
]]>
</source>
</p>
<p>
When we find the refresh command, the browser content is re-queried.
By default, the browser will not refresh its content unless explicitly invalidated.
</p>
<p>
Another useful method to overwrite is the <b>getQueryString()</b> method.
The tutorial example does not do so, but here is an example of how it could be done.
This method provides you with a way to generate the query string dynamically.
It is called whenever the browser is invalidated, and needs to re-query the database
in order to generate a new result set.
</p>
<p>
<source>
<![CDATA[
public String getQueryString(RunData rundata, Context context)
{
String sql = null;
try
{
sql = PortletConfigState.getConfigParameter(portlet,
Constants.SQL_QUERY, null);
SomeObject so = (SomeObject)
SessionHelper.getSessionAttribute(rundata,
Constants.SOME_OBJECT, null);
if(so == null)
{
throw new Exception("Failed to get Object from session");
}
List parameters = new ArrayList();
parameters.add(so.getName());
parameters.add(so.getCity());
super.setSQLParameters(parameters);
}
catch (Exception e)
{
Log.error(e);
}
return sql;
}
]]>
</source>
</p>
<p>
Your SQL string in the registry would then need to have JDBC parameters:
</p>
<p>
<source>
<![CDATA[
<parameter name="sql"
value="select name, city, state from people where name=? and city=?"
hidden="false"/>
]]>
</source>
</p>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
