Thursday, March 16, 2006

Jetspeed 2 Notes: Getting Started

-------------------------------------
Jetspeed 2 Notes
-------------------------------------

* I'm doing this on my MacBook, by the way.

* Grabbed the "Derby" version of Jetspeed 2 to avoid installing a database. The installation was clean, just used notes from

http://portals.apache.org/jetspeed-2/getting-started-installer.html.


* I note the Jetspeed2 pages are a little confusing, so it is not completely clear how to do a quick start. The link above is the one to use.

* Noted that I did need to set JAVA_HOME for Tomcat to work, so I did. /usr/bin/java is a link that points to /System/Library/Frameworks/JavaVM.framework/Commands/java. Looking around a bit, I see that there is also /System/Library/Frameworks/JavaVM.framework/Home. This is the one. Edit ~/.bashrc and add "export JAVA_HOME=System/Library/Frameworks/JavaVM.framework/Home". Source it and you should be set.

* Fired up the tomcat server, used "tail -f catalina.out" to get some feel for when things were up and running, and then pointed browser at http://localhost:8080/jetspeed/portal. Success.

* Logged in as admin/admin of course. Was immediately faced with having to reset my password.
Could not do anything until I reset, and could not use the same default value. Damn security. In case you are wondering, my admin password is now "admin2".

-------------------------------------
Adding a portlet the hard way.
-------------------------------------

* OK, now I want to deploy a portlet. I'm going to try the IFrame portlet (of course) from the OGCE2 release. This will be interesting, since I will have to a) figure out the web.xml and b) figure out how to get Jetspeed to recognize it.

* So far, so bad. I made the IFrame portlet. Then took a took at the guidelines here:
http://portals.apache.org/jetspeed-2/guides/guide-simple-portlet.html. So I made sure I used the simplest web.xml possible and remade the war. My web.xml is below.


<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>
<display-name>IFrame Portlet</display-name>
<description>
IFrame portlet
</description>
</web-app>



The jetspeed deployment process will convert this as necessary.

* Make the war with "cd /path/to/iframe-portlet/; jar -cf iframe-portlet.war".

* I then copied the war into webapps/jetspeed/WEB-INF/deploy. Jetspeed magic took over for a while (I followed along in catalina.out). Then pointed browser at http://localhost:8080/jetspeed/portal/iframe-portlet.psml. Of course things didn't work, but the first failure was a little obscure.

* Looking again at the Jetspeed porltet guide, I realized I needed to make a PSML file. So I made one. This is very BAD since it is easy to make mistakes with the PSML creation. Anyway, I made one called iframe-portlet.psml. It looks like this:

<page>
<defaults
skin="orange"
layout-decorator="tigris"
portlet-decorator="tigris"
/>
<title>The Glorious IFrame Portlet</title>
<metadata name="title" xml:lang="en">Junk</metadata>
<fragment id="iframe" type="layout" name="jetspeed-layouts::VelocityOneColumn">
<fragment id="iframe-1" type="portlet" name="iframe::IFramePortlet">
<property layout="TwoColumns" name="row" value="0" />
<property layout="TwoColumns" name="column" value="1" />
</fragment>
</fragment>

<security-constraints>
<security-constraints-ref>public-view</security-constraints-ref>
</security-constraints>
</page>


I placed this under ~/ApacheJetspeed2.0/webapps/jetspeed/WEB-INF/pages/. I then pointed the browser to http://localhost:8080/jetspeed/portal/iframe-portlet.psml. I of course got an error.

Title Error: Cannot pass a null PortletDefinition to a PortletEntity.
Failed to retrieve Portlet Definition for iframe::IFramePortletFailed to retrieve Portlet Definition for iframe::IFramePortletjava.lang.IllegalArgumentException: Cannot pass a null PortletDefinition to a PortletEntity.Failed to retrieve Portlet Definition for iframe::IFramePortletFailed to retrieve Portlet Definition for iframe::IFramePortlet

* Success! It looks a little crappy, but I found that the error was in my fragment name. Change this:

<fragment id="iframe-1" type="portlet" name="iframe::IFramePortlet">

to this:

<fragment id="iframe-1" type="portlet" name="iframe-portlet::IFramePortlet">


The name attribute should have the value "${portlet.war.name}::${portlet.name}. The first part (${portlet.war.name}) is the name of the portlet war file, minus the .war. So I had iframe-portlet.war, so I have to use iframe-portlet. The second part comes from the value of the <portlet-name/> tag in the portlet.xml file.

I hope all of this is obvious.... See http://portals.apache.org/jetspeed-2/multiproject/jetspeed-deploy-tools/.

* You can also add things to default-page.psml or one of the other PSML files if you prefer.

-----------------------------------------------
Adding portlets to a layout.
-----------------------------------------------
* OK, you can always edit PSML stuff by hand, but obviously this is no good for people don't have write permission to the jetspeed directories.

* One way to do this is as follows:
1. Log in
2. In the upper right corner, click the edit ("pencil") icon. If unsure, there is a tooltip popup
over the icon.
3. You should now see three icons in the upper right: View, Help, and Add a Portlet. This is
the + ("plus") icon.
4. Click add a portlet. You should get a popup window.
5. Search for your portlet by name or by keyword (note keywords are in the portlet.xml).
6. Add it.

* Try something like "RSS" and use keyword searching.

* Note also you can do a similar thing to add tabs to the top menu. Enter edit mode first. You should
see a mysterious "Add Page" button next to a text field. Hmm. So type in a name and you will get a new tab across the top.

* Click the tab you just created. It will be filled completely with the lefthand navigator window, which I found confusing at first. Enter Edit mode by clicking the pencil icon in the upper right and then add a portlet as before.

* The main problem with this approach is that you have to know or guess at the available portlets. Hopefully there is a way to do this differently.

* You may also wonder at this point if there is a way to remove these tabs that you are creating. There is a way. Log in as the administrator and click the Portal Site Manager. You will need to click "Jetspeed Administrative Portlets" on the lefthand side. Under the tree view, find the user account that includes all the new tabs that you added. Click the tab to cause it to appear in the right hand column. Click delete.

No comments: