taylor 2004/04/09 03:33:12
Added: tutorial/xdocs/5 registry.xml helloworld.xml deploy.xml
index.xml page.xml hellouser.xml
tutorial/xdocs/images image005-3.jpg image005-2.jpg
image005-1.jpg
Log:
chapter 5 converted to xdocs
PR:
Obtained from:
Submitted by:
Reviewed by:
CVS: ----------------------------------------------------------------------
CVS: PR:
CVS: If this change addresses a PR in the problem report tracking
CVS: database, then enter the PR number(s) here.
CVS: Obtained from:
CVS: If this change has been taken from another system, such as NCSA,
CVS: then name the system in this line, otherwise delete it.
CVS: Submitted by:
CVS: If this code has been contributed to Apache by someone else; i.e.,
CVS: they sent us a patch or a new module, then include their name/email
CVS: address here. If this is your work then delete this line.
CVS: Reviewed by:
CVS: If we are doing pre-commit code reviews and someone else has
CVS: reviewed your changes, include their name(s) here.
CVS: If you have not had it reviewed then delete this line.
Revision Changes Path
1.1 jakarta-jetspeed/tutorial/xdocs/5/registry.xml
Index: registry.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>Adding A Portlet to the Registry</title>
</properties>
<body>
<section name="Adding A Portlet to the Registry">
<p>
In order for Jetspeed to know about your portlet class, two things must happen:
</p>
<p>
1. Put your class in the classpath. <br/>
2. Add a reference to your portlet to Jetspeed's Portlet Registry.
</p>
<p>
The <a href='http://portals.apache.org/jetspeed-1/registry.html'>Jetspeed Portlet
Registry</a>
contains the definitions of all portlets known to Jetspeed.
</p>
<p>
We've already completed both steps for you when you built and deployed the examples
for tutorial 5.
The example class files are copied to the Jetspeed web application's class
directory.
This is normally where classes specific to your web application are placed (under
/WEB-INF/classes).
</p>
<p>
Secondly, a <a
href='http://portals.apache.org/jetspeed-1/registry_xml.html'>registry fragment</a>
file was created and deployed. See the source:
</p>
<source>
tutorials/5/t5-portlets.xreg
</source>
<p>
Registry fragments contain portlet definitions.
Any file in the <b>/WEB-INF/conf</b> directory that has the <b>xreg</b> extension
is included in the Jetspeed Registry. Here is what a registry entry looks like for
our example:
</p>
<source>
<![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<registry>
<portlet-entry name="HelloWorld" hidden="false" type="instance"
application="false">
<meta-info>
<title>HelloWorld</title>
<description>Portlet How To Example 1 Hello World</description>
</meta-info>
<classname>com.bluesunrise.portal.portlets.HelloWorldPortlet</classname>
<media-type ref="html"/>
</portlet-entry>
</registry>
]]>
</source>
<p>
We won't cover all the registry syntax here, but its important to give it a name,
enter the class name correctly, and limit the <b>media-type</b> entry to only the
media types that you will support. In our example, we only support HTML.
</p>
</section>
</body>
</document>
1.1 jakarta-jetspeed/tutorial/xdocs/5/helloworld.xml
Index: helloworld.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>Hello World Portlet</title>
</properties>
<body>
<section name="Hello World Portlet">
<p>
To start with, the very first portlet is the simplest, the obligatory "Hello World",
it extends <a
href='http://portals.apache.org/jetspeed-1/apidocs/org/apache/jetspeed/portal/portlets/AbstractInstancePortlet.html'>AbstractInstancePortlet</a>.
All the code necessary is shown below:
</p>
<source>
<![CDATA[
package org.apache.jetspeed.tutorial.portal.portlets;
public class HelloWorldPortlet extends AbstractInstancePortlet
{
public ConcreteElement getContent (RunData runData)
{
return (new StringElement ("Hello World! #" + getID()));
}
}
}]]>
</source>
<p>
When you have compiled this portlet and configured it into the portlet registry,
the user can choose the portlet from the list of available portlets when customizing
their home page.
As you can see, the most important method to override is the <b>getContent()</b>
method,
which provides the content of your portlet to the response payload.
We will cover this method in detail in the section on the <b>Portlet interface</b>.
</p>
<p>
In future chapters we will discover better methods for generating your content,
using the set of MVC portlets provided with the Jetspeed distribution.
See tutorials 7 onwards for examples these abstractions where it is not
necessary to override the getContent method. For the purpose of learning the very
basics of portlet operations, tutorials 5 and 6 will demonstrate how the
getContent method works without any MVC abstraction.
</p>
</section>
</body>
</document>
1.1 jakarta-jetspeed/tutorial/xdocs/5/deploy.xml
Index: deploy.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>Deploy</title>
</properties>
<body>
<section name="Deploy">
<p>
To deploy the system type:
</p>
<source>
maven deploy
-- or --
maven hotdeploy
</source>
<p>
Use hotdeploy if you have already deployed the system once.
This simply saves some time in packaging the JPortal deployment.
Next point your browser at:
</p>
<p>
<a
href='http://localhost:8080/jportal/portal'>http://localhost:8080/jportal/portal</a>
</p>
<p>
You should see the new site menus for the anonymous user:
</p>
<p>
<img border='0' width='507' height='221' src="../images/image005-4.jpg"/>
</p>
</section>
</body>
</document>
1.1 jakarta-jetspeed/tutorial/xdocs/5/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>Portlet 101</title>
</properties>
<body>
<section name="Portlet 101">
<p>
Tutorial 5 guides you through the creation of a portlet,
starting with a simple examples and then introduces you to the fundamental
concepts of portlet development.. This section covers:
</p>
<p>
<ul>
<li>1. <a href='helloworld.html.html'>1. HelloWorld Portlet</a></li>
<li>2. <a href='registry.html'>2. Adding A Portlet to the Registry</a></li>
<li>3. <a href='page.html'>3. Adding A Portlet to a Page</a></li>
<li>4. <a href='hellouser.html'>4. HelloUser Portlet</a></li>
<li>5. <a href='deploy.html'>Deploy</a></li>
</ul>
</p>
<p>
Lets get started. From the JPortal /tutorial distribution root directory, type:
</p>
<hr/>
<code>
maven -Dtutorial=5 jetspeed:war
</code>
<hr/>
<p>
Recommend bringing up these configuration files in your editor:
</p>
<p>
<hr/>
<code>
<ul>
<li>1.
src/java/org/apache/jetspeed/tutorial/portal/portlets/HelloWorldPortlet.java</li>
<li>2.
src/java/org/apache/jetspeed/tutorial/portal/portlets/HelloUserPortlet.java</li>
<li>3. tutorials/5/anon/html/default.psml</li>
<li>4. tutorials/5/turbine/html/default.psml</li>
<li>5. tutorials/5/t5-portlets.xreg</li>
<li>6. tutorials/5/JetspeedResources.properties.merge</li>
</ul>
</code>
<hr/>
</p>
<p>
since we will reference them in tutorial 5.
</p>
</section>
</body>
</document>
1.1 jakarta-jetspeed/tutorial/xdocs/5/page.xml
Index: page.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>Adding A Portlet to a Page</title>
</properties>
<body>
<section name="Adding A Portlet to a Page">
<p>
After successfully deploying the examples to Jetspeed,
you can then customize your page.
The Anonymous User and the Turbine User already include the Hello World portlets.
Lets go ahead and add a second Hello World portlet and see what happens.
Start up Jetspeed, and logon with the username/password of
</p>
<source>
Username = turbine
Password = turbine
</source>
<p>
Click on the 'Pencil Icon' in the Title Bar (right below the menu).
This will start the Jetspeed Customizer.
</p>
<p>
<img border='0' width='149' height='95' src="../images/image005-1.jpg"/>
</p>
<p>
Click the "Basic Tutorials" menu option. From the Pane Customizer, click the "Add
Portlet" button.
</p>
<p>
You should see a screen like below. Select "HelloWorld" and then press the "Apply"
button.
</p>
<p>
<img border='0' width='553' height='377' src="../images/image005-2.jpg"/>
</p>
<p>
Then from the next screen, press "Save and Apply" and "Apply" again.
Finally, you should return to the newly customized screen and see the output of your
portlet:
</p>
<img border='0' width='250' height='215' src="../images/image005-3.jpg"/>
<p>
So what are those funny numbers after Hello World...<br/>
They are the portlet instance ids, which are automatically assigned to the portlet.
This id uniquely identifies your portlet instance in the entire portal site.
Portlet Instances, are instances of the your portlet on a PSML page.
The two different instances use the same Java class instance,
which saves memory, however they use different parameters and state,
which is important when you have two or more instances of the same portlet on a page.
</p>
</section>
</body>
</document>
1.1 jakarta-jetspeed/tutorial/xdocs/5/hellouser.xml
Index: hellouser.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>Hello User Portlet</title>
</properties>
<body>
<section name="Hello User Portlet">
<p>
The next step in your portlet example is to make the world more specific.
That is, instead of writing out a static string, the greeting is personalized
according to the user settings.
</p>
<source>
<![CDATA[
package org.apache.jetspeed.tutorial.portal.portlets;
public class HelloUserPortlet extends AbstractInstancePortlet
{
public ConcreteElement getContent(RunData runData)
{
StringBuffer text =new StringBuffer();
text.append("Hello ");
String name = runData.getUser().getFirstName();
if (name == null)
name ="Anonymous";
text.append (name);
text.append ("!");
return (new StringElement(text.toString()));
}
}
]]>
</source>
<p>
With this example, you will be using the classes inherited from another Apache
project:
<a href='http://jakarta.apache.org/turbine/'>Turbine</a>.
Turbine is a web application framework based on the Java Servlet API.
Jetspeed was written with Turbine as its framework, and also upon the Java Servlet
API.
Lets take a closer look at the interfaces supplied by Turbine:
<a
href='http://jakarta.apache.org/turbine/turbine-2.3/apidocs/org/apache/turbine/util/RunData.html'>RunData</a>
and <a
href='http://jakarta.apache.org/turbine/turbine-2.3/apidocs/org/apache/turbine/om/security/User.html'>User</a>.
</p>
<p>
The RunData interface provides you with access to the servlets request state and
other session context information.
Examples are security (access control), Turbine actions, cookies, servlet parameters
(parsed), and the current user,
to name a few. The current user is accessible via the getUser() or getJetspeedUser()
methods as shown in the example above.
</p>
<p>
With the User object, you can then access typical user information, and also store
temporary values for
your session (getTemp(), setTemp()). Heres as summary of the standard user
information provided:
</p>
<p>
<table>
<tr>
<th>
User Property/Methods
</th>
<th>
Description
</th>
</tr>
<tr>
<td>
AccessCounter
</td>
<td>
Keep track of how many times the user has accessed the portal
</td>
</tr>
<tr>
<td>
Confirmed
</td>
<td>
Returns the confirmation value used during automatic account sign up.
</td>
</tr>
<tr>
<td>
CreateDate
</td>
<td>
The creation date of this account.
</td>
</tr>
<tr>
<td>
Email
</td>
<td>
The email address of the user.
</td>
</tr>
<tr>
<td>
FirstName
</td>
<td>
The first name of the user.
</td>
</tr>
<tr>
<td>
LastAccessDate
</td>
<td>
The last access time stamp for the user.
</td>
</tr>
<tr>
<td>
LastLogin
</td>
<td>
The last login time stamp for the user.
</td>
</tr>
<tr>
<td>
LastName
</td>
<td>
The last name of the user.
</td>
</tr>
<tr>
<td>
Password
</td>
<td>
The password of the user.
</td>
</tr>
<tr>
<td>
Perm
</td>
<td>
Jetspeed stores a hash table of name/value pairs in a binary column in the database.
</td>
</tr>
<tr>
<td>
Temp
</td>
<td>
A temporary hash table of values for the user stored in the session.
These values go away after user logs off or after the session times out.
</td>
</tr>
<tr>
<td>
UserName
</td>
<td>
The user name (primary credential) of the user.
</td>
</tr>
<tr>
<td>
hasLoggedIn
</td>
<td>
Indicates if the user is currently logged on.
</td>
</tr>
<tr>
<td>
incrementAccessCounter
</td>
<td>
Increment the users access counter.
</td>
</tr>
<tr>
<td>
isConfirmed
</td>
<td>
Indicates if this user has yet been confirmed.
</td>
</tr>
<tr>
<td>
removeTemp
</td>
<td>
Remove a name/value pair from the temporary hash table.
</td>
</tr>
</table>
<table>
<tr>
<th>
Jetspeed User Property
</th>
<th>
Description
</th>
</tr>
<tr>
<td>
Disabled
</td>
<td>
An account can be disabled with this property
</td>
</tr>
<tr>
<td>
UserId
</td>
<td>
The user id
</td>
</tr>
<tr>
<td>
isNew
</td>
<td>
Boolean indicating if the user has been stored yet
</td>
</tr>
</table>
</p>
<p>
Remember that the set methods of the properties may not store the changes to the
database immediately.
There is a setting in the JetspeedResources.properties file that must be set to true
to automatically
save all modifications to the user on logout.
</p>
<source>
# automatically save user state on logout
automatic.logout.save = false
</source>
<p>
Otherwise, you will need to explicitly save the user with the User Management
service.
Here is an example of disabling the current user.
</p>
<source>
<![CDATA[
JetspeedUser user = user = rundata.getJetspeedUser();
user.setDisabled(true);
JetspeedUserManagement.saveUser(user);
]]>
</source>
<p>
Jetspeed actually extends the RunData interface as
<a
href='http://portals.apache.org/jetspeed-1/apidocs/org/apache/jetspeed/services/rundata/JetspeedRunData.html'>JetspeedRunData</a>.
You can safely cast RunData to JetspeedRunData from anywhere within Jetspeed.
The extended class gives you access to some important Jetspeed request
state such as the
<a
href='http://portals.apache.org/jetspeed-1/apidocs/org/apache/jetspeed/services/profiler/ProfilerService.html'>Profile</a>
and the
<a
href='http://portals.apache.org/jetspeed-1/apidocs/org/apache/jetspeed/capability/CapabilityMap.html'>Capability
Map</a>.
</p>
<p>
To summarize, you can always get the current user from the RunData.
RunData is used all over Jetspeed as a common mechanism for passing request
information.
</p>
</section>
</body>
</document>
1.1 jakarta-jetspeed/tutorial/xdocs/images/image005-3.jpg
<<Binary file>>
1.1 jakarta-jetspeed/tutorial/xdocs/images/image005-2.jpg
<<Binary file>>
1.1 jakarta-jetspeed/tutorial/xdocs/images/image005-1.jpg
<<Binary file>>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
