Portlet チュートリアル

During development of the examples, we will often deploy our portlets into a Jetspeed web application – a portlet container. This is accomplished with the several ant targets provided with the tutorial:

ant tutorial-n

Configure the distribution to match the given tutorial, where n is the number of the tutorial from this document.

ant war

Creates the war file which you can manually copy to your application server. This war file is a combination of the Jetspeed distribution with you’re the example code. The war file combines the Jetspeed container with the example portlets and their configuration. The war file is written to jportal/dist/jportal.war.

ant deploy

Dependent on the war target. After building the war file, it automatically deploys the war file into the application server of your choice. For this tutorial, Jakarta Catalina is required. NOTE: you should shutdown Catalina before invoking this target.

ant hotdeploy

A quicker version of deploy. Only deploys classes and configuration files that are newer than the files in the deployed web application. Requires that deploy target is ran once, since it will not expand the entire application to the web application directory. This target is used most often in the everyday development routine.

Jetspeed 2.0 will support the Java Standard Portlet API, which defines a standard deployment descriptor and portlet archive for deploying portlets to portlet containers. Version 1.x of Jetspeed does not support the standard, thus a custom deployment procedure is necessary.

サンプルのビルド

The tutorial requires Ant (http://ant.apache.org/)

You will need Antto build all the examples. Please download and install Ant before continuing.

Here are the available target commands:

all Clean build and dist, then compile

clean Delete old build and dist directories

compile Compile Java sources

deploy Deploy application to servlet container

dist Create binary distribution

hotdeploy Hot Deploy application to portlet container

javadoc Create Javadoc API documentation

om Generate Object Model sources

war Create merged war

tutorial-0 Resets the web application.

tutorial-n Configure the distribution for the nth tutorial examples.

tutorial-all Configurations the distribution to include all tutorials.

Depending on where Jetspeed and Tomcat are installed, you may need to edit a few of the properties in the build.properties. The first set of properties are for developing with the source code. The second set are for developing without the source code, using a WAR file that was downloaded, in this example, to a directory /apache/Jetspeed-1.4b3-release-war/Jetspeed-1.4b3.

# typical settings with source

jetspeed_home=/apache/jakarta-jetspeed

catalina_home=/apache/catalina

portlet_app_name=jportal

company=com.bluesunrise.jportal

jetspeed_jar=/bin/jetspeed-1.4b3-dev.jar

jetspeed_war=/bin/jetspeed.war

jetspeed_lib=/lib

jetspeed_conf=/webapp/WEB-INF/conf/

# typical settings without source

# jetspeed_home=/apache/jetspeed-1.4b3-release-war/jetspeed-1.4b3

# catalina_home=/apache/catalina

# portlet_app_name=jportal

# company=com.bluesunrise.jportal

# jetspeed_jar=/WEB-INF/lib/jetspeed-1.4b3-dev.jar

# jetspeed_war=/jetspeed.war

# jetspeed_lib=/WEB-INF/lib

# jetspeed_conf=/WEB-INF/conf/

To build the examples for a specific tutorial example, type:

ant tutorial-n (where n = the number of the tutorial)

ant deploy (first time, and then)

ant hotdeploy

These commands build and deploy the examples to your Catalina distribution as a web application. NOTE: this process will also work with Tomcat.

The tutorials must be run in order. If you want to deploy tutorial-5, you must first run tutorial-1 thru tutorial-4.

If you’d like to skip ahead and see the result of all the tutorials, then run:

ant tutorial-all

ant deploy

That’s it. You are now ready to start up the JPortal web application. Start up Catalina and point a browser at:

http://localhost:8080/jportal/portal

You will see the Home Page for JPortal. To see JPortal customized for a user, logon to the system as:

Username = turbine

Password = turbine

NOTE: you should shutdown Catalina before invoking the deploy target.

ポータルサイトの計画

No matter what portal or web development tool you're using, you should always first spend some time on the specification of your portal. You should not even start looking at the technology before answering questions like:

How many users?
Is there already an existing authentication database for these users, do I want to use it?
How many languages?
How many media types do I want to support?
How many and which segments/target groups do I have to serve
What content do I want to publish?
How can I get access to this content (disk, db, syndication, etc...)?
Who is going to update the site content and with what editorial process?
What applications do I need to connect to?
Are they already using a single authentication db?
How do I bridge to these apps (servlet, http, SOAP, CORBA, etc...)?
For each user target group, what application/content do they need to access?
Can they personalize their portal view?
What access rights should they have?
What will be your portal navigation?
Do you plan to set up different thematic portal views or a single integrated workspace?

Once you have written down your answers on these points, you should

have a much better view on:

- What kind of software tools and features you'll need.

- What kind of skills you'll require.

- An estimate of the amount of work required to setup your portal.

- What budget you'll need to complete your portal transition.

- Where to start

Setting up and running a portal is typically a lot of work, mainly

in terms of technical integration, process engineering and project

management. Open source software does not magically cancel these, just ensure that your budget can be spent of these items rather than

being split between software licenses and integration.

Jumping directly from a static website to a portal-driven system

without any defined specification and expected benefits is a recipe

for frustration, lost time, lost money and a very slow website...

Jetspeed Portlet API

The Jetspeed Portal API is a set of interfaces describing how a portlet interacts with a portlet container. There is a soon to be released Java Standard Portlet API. Jetspeed 2.0 will support that standard.

Every portlet has to implement the Portlet interface

org.apache.jetspeed.portal.Portlet

either directly, or by extending a class that in turn implements the Portlet interface. Review the Portlet interface at the link above. This tutorial will cover how to implement most methods on the interface.

It is usually recommended to extend one of the higher level foundation portlet classes, such as the CustomizerVelocity portlet or DatabaseBrowserPortlet portlet.

The AbstractPortlet and AbstractInstancePortlet classes provide an abstract portlet implementation of the Portlet interface with the most common functionality, leaving only a few methods to be implemented by you.

チュートリアルの再スタート

If you’d like to clean up the JPortal Tutorial examples and reset to a default Jetspeed deployment, type:

ant clean

ant deploy

This ant target removes all classes and configuration files from the deployment, leaving you with a web application that is exactly the same as the Jetspeed web application. No changes are made to the Jetspeed distribution. When you point your browser at http://localhost:8080/jportal/portal, you will see the default Jetspeed portal.

This target is useful if you want to restart the tutorials from the beginning.

チュートリアル１ – ポータルウェブデザインの仕立て上げ

Tutorial 1 shows you how to tailor the web design of the JPortal portal. This is accomplished by overriding and merging the Jetspeed portal configuration property files.

In this tutorial, we will:

Change the Portal Logo
Modify the Top Navigation
Remove the Left Navigation
Replace the Bottom Navigation
Change the Web Page Title
Change the Skin, CSS
How Property Merging Works in the Tutorial
Deploy

Let’s get started. From the JPortal distribution root directory, type:

ant tutorial-1

Recommend bringing up these configuration files in your editor:

webapp/WEB-INF/conf/JPortalJetspeed.properties
webapp/WEB-INF/conf/jportal-skins.xreg
webapp/WEB-INF/conf/templates/vm/navigations/html/bottom-jportal.vm
webapp/css/jportal.css

since we will reference them in tutorial 1.

1.1 ポータル・ロゴの変更

Looking at JPortalJetspeed.properties:

topnav.logo.file=images/jportal.gif

The topnav.logo.file property points to the new image that we want to display on the JPortal site. Note that all properties relating to files are specified relative to the web application root. The images directory can be found directly under the web application root.

You could also use a logo that exists on another server with the topnav.logo.url property. The topnav.logo.file and topnav.logo.url properties are mutually exclusive, you should one or the other.

Of course you don’t have to use any logo. You’re top navigation could be customized to use a completely different layout.

1.2 上位ナビゲーションの修正

Navigations are carried over from the Turbine-2 classic web application design. A website generally has a top and bottom navigation scheme. This is generally defined as the header and footer of the website. Jetspeed allows three navigations: top, bottom, and left. For JPortal, we override navigation properties in JPortalJetspeed.properties. Here are the top navigation settings:

# topnav.enable=true

# topnav.vm=top.vm

# topnav.logo.url=

# topnav.logo.file=images/jportal.gif

# topnav.user_login.enable=true

topnav.user_creation.enable=false

topnav.enable turns on or off the top navigation. Try turning it off. You won’t see the logo or login edit fields.

We’ve already described topnav.logo.file and topnav.logo.url in the previous section.

topnav.user_login.enable turns on or off the single-sign-on edit fields for entering a username and password.

topnav.user_creation.enable turns on or off the link to the Enter New User portlet. We will modify the default setting and set it to false.

topnav.vm is the most powerful setting. You can use your own JSP or Velocity template here to completely customize your top navigation.

1.3 左サイド・ナビの削除

Next we show how to remove the left navigation.

leftnav.enable=false

# leftnav.vm=left.vm

# leftnav.width=10%

leftnav.enable turns on or off the left navigation. The JPortal tutorial site doesn’t require a left navigation, so we turn it off.

leftnav.vm You can use your own JSP or Velocity template here to customize your left navigation.

lefnav.width specifies the percentage of the page width to be covered by the left navigation.

1.4 下位ナビゲーションの置き換え

Next we show how to replace the bottom navigation.

bottomnav.enable=true

bottomnav.vm=bottom-jportal.vm

bottomnav.enable turns on or off the bottom navigation.

bottomnav.vm You can use your own JSP or Velocity template here to completely customize your bottom navigation. That is exactly what we do here using a Velocity template tailored specifically for the JPortal tutorial.

<br/>

<hr/>

<tr>

<small>

JPortal Tutorial for Jetspeed - Version 1.4b3<br/>

</small>

</td>

#if ($config.getString("mail.support"))

<a href="mailto:$config.getString("mail.support")">Support and Additional Information</a>

</td>

#end

</a>

</td>

</tr>

</table>

1.5 ウェブページのタイトル変更

The web page title (in the browser title-bar) can have a text string prefix added:

portalpage.title_prefix=JPortal Tutorial:

1.6 スキンの変更及びカスケーディングスタイルシート

Skins are used to define color, font, and borders for various components in Jetspeed. The skin definitions is referenced in portal resources such as controls, controllers, portlets and templates to create a centralized design theme. Review the registry fragment called jportal-skins.xreg, where we define a new skin to match our really gaudy colour theme for the Jportal site.

<?xml version="1.0" encoding="UTF-8"?>

<skin-entry name="jportal-skin" hidden="false">

<property name="title-background-color" value="#ceff63"

hidden="false"/>

<property name="title-style-class" value="TitleStyleClass"

hidden="false"/>

<property name="highlight-text-color" value="#ffffff"

hidden="false"/>

<property name="highlight-background-color" value="#6331ff"

hidden="false"/>

</skin-entry>

</registry>

Then in the JPortalJetspeed.properties, the default skin for the portal site is defined:

services.PortalToolkit.default.skin=jportal-skin

The default skin is applied to the portal whenever a specific skin is not declared for a resource. The default skin facilitates quickly creating a site look and feel with minimal effort.

See the Jetspeed Skin documentation for all available skin parameters.

Skins are used in combination with Cascading Style Sheets. CSS is a simple mechanism for adding style (e.g. fonts, colors, spacing) to Web documents, defined as a standard by the World Wide Web Consortium (W3C).

In the JPortalJetspeed.properties, the portal site stylesheet is defined:

site.stylesheet=css/jportal.css

Looking at the cascading style sheet for the JPortal site, we see that the Jetspeed style sheet, default.css, is included into this style sheet with the import at-rule:

@import “default.css”;

A:link {

text-decoration : none;

color : #333366;

}

A:visited {

text-decoration : none;

color : #666699;

}

A:hover {

color : #CC3300;

}

A.index:link {

font-size : 11px;

color : #333366;

}

A.index:visited {

font-size : 11px;

color : #333366;

}

A.index:hover {

color : #CC3300;

}

We then go on to define several example styles overriding the settings in default.css. Styles declared in the style sheet can also be referenced in a skin, as we do in our skin registry:

<property name="title-style-class" value="TitleStyleClass"

hidden="false"/>

1.7 配備

ビルドには以下のコマンドを打ちます：

ant deploy (or hotdeploy)

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:

http://localhost:8080/jportal/portal

You should see the new web design for the JPortal site. The portlets inside are still the same as the default Jetspeed deployment.

チュートリアル２ – ローカライズ

When completing the last tutorial, you may have noticed the text right at the top of the screen “Welcome to Jetspeed”. The text comes from a Java localised resource file. This tutorial will show you how to create your own localised resources to easily support multiple languages without hard-coding messages in your Java source code.

In this tutorial, we will:

Edit the resource files and change the Welcome string in two languages
Review how Jetspeed finds PSML resources by language and country code
Localisation of PSML Resources
Deploy

Let’s get started. From the JPortal distribution root directory, type:

ant tutorial-2

Recommend bringing up these files in your editor:

webapp/WEB-INF/conf/JPortalTurbine.properties
src/java/com/bluesunrise/jportal/modules/localization/JportalLocalization_en.properties
src/java/com/bluesunrise/jportal/modules/localization/JportalLocalization_fr.properties
webapp/WEB-INF/templates/vm/navigations/html/bottom-jportal.vm
webapp/WEB-INF/conf/JPortalJetspeed.properties

since we will reference them in tutorial 2.

2.1 Javaリソースバンドル

It is recommended that you use resource bundles for all of strings that will be displayed to the end user. This is called ‘localising’ your application.

The tutorial comes with two sample resource files in English and French. Let’s look at the English version:

TOP_TITLE=Welcome to JPortal, the Jetspeed Tutorial

CONTACT_US=Contact Us

The first string, TOP_TITLE, replaces a resource string already defined in Jetspeed. The second string, CONTACT_US is a new string that is referenced in the bottom-jportal.vm file.

Referencing localised strings in Velocity templates is accomplished with the localisation global tool, with a rather odd name of $l10n. It stands for the word ’localisation’, where the 10 middle letters are cleverly (sic) represented by the number 10.

Any string in the resource bundle can be referenced as shown below:

<h2>$l10n.TOP_TITLE</h2>

</td>

In this tutorial, we will change the bottom navigation defined in the last tutorial, to use a localised string:

<a href="mailto:$config.getString("mail.support")">$l10n.CONTACT_US</a>

</td>

In the JPortalJetspeed.properties, setup your email support account:

mail.support=support@bluesunrise.com

2.2 モジュール／バンドル

Turbine has a concept called modules, which is a special class loader path. Multiple module class paths can be configured by simply adding a path to the root directory of your modules. Take a look at the JPortalTurbine.properties:

module.packages=com.bluesunrise.jportal.modules

Modules is made up of different kinds of modules: actions, layouts, screens, navigations, pages, and localisations. Jetspeed uses the module path to find the resource bundles.

Resource bundles and the default language are also specified in the JPortalTurbine.properties. Notice that the JPortal resource bundle is listed first, overriding the Jetspeed resource bundle.

locale.default.bundles=

com.bluesunrise.jportal.modules.localization.JPortalLocalization,

org.apache.jetspeed.modules.localization.JetspeedLocalization

locale.default.language=en

locale.default.country=US

2.3 PSMLリソースのローカライズ

PSML resources may also be optionally localised. PSML Resources are localized by placing them in sub-directories based on language and country code abbreviations. The language-code sub-directory contains one or more country-code subdirectories.

The language-code directory name is specified with an ISO-639 standard two-character language abbreviation. The country-code subdirectory is optional, and is specified with an IS0-3166 standard two-character country code abbreviation.

An example:

user

|-- david

|-- html

|-- fr // french language

|-- FR // France country-code

|-- BE // Belgium country-code

NOTE: The country codes must be in upper-case

For a given locale of fr_FR, the search order for the default accounting resource would be:

groups/accounting/html/fr/FR/default.psml

groups/accounting/html/fr/default.psml

groups/accounting/html/default.psml

groups/accounting/default.psml

The Jetspeed profiler looks at the "Content Language" HTML header for locale specific settings. If there are multiple settings, all settings will be searched until the first resource is found. (This is currently not supported)

For a complete list of ISO-639 standard language abbreviations, see:

http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt

For a complete list of ISO-3166 standard country code abbreviations, see:

http://userpage.chemie.fu-berlin.de/diverse/doc/ISO_3166.html

In the JPortalJetspeed.properties, you can enable or disable the usage of language and country codes during PSML resource resolution with the following settings. In the tutorial we choose to turn off both language and country code fallback.

# Consider the language as part of the fallback?

services.Profiler.fallback.language=false

# Consider the country code as part of the fallback?

services.Profiler.fallback.country=false

2.4 配備

To deploy the system type:

ant deploy (or hotdeploy)

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:

http://localhost:8080/jportal/portal

You should see the new localised title. The portlets inside are still the same as the default Jetspeed deployment.

チュートリアル３ – サイトマップ

The next step is for us to layout the portal site map. We do this using a specialized portal XML-derivative called PSML (Portlet Structure Mark-up Language).

When designing your portal, you should consider how users will navigate around your site. In our example portal, we will allow for anonymous users to access the site, and also for authenticated users to access areas of the site where they are authorized (more on Site Security in the next tutorial).

In this tutorial, we will:

Create the anonymous PSML resource with a Tab control
Learn about PSML navigational components
PSML References
Create an authenticated user’s PSML resource with a Menu control
Learn about PSML layout components for portlets
Customize Menus with the Customizer
Customizing Panes with the Customizer
Deploy

Let’s get started. From the JPortal distribution root directory, type:

ant tutorial-3

Recommend bringing up these files in your editor:

webapp/WEB-INF/psml/user/anon/html/default.psml
webapp/WEB-INF/psml/user/turbine/html/default.psml

since we will reference them in tutorial 3.

3.1 匿名ユーザ用のリソース

Anonymous users are users who have not been authenticated. The anonymous user interface is the default user interface displayed to users who have not yet signed on.

Some sites do not allow anonymous users to see anything on the site. Perhaps you only want to display a single portlet, or perhaps a portlet with static company information, a Signup portlet, and a Returning-User logon portlet. It all depends on your requirements.

The requirements for JPortal are very simple: it’s a tutorial. We want to show all the tutorial portlets to everyone. We also want to show off some of the portlets that come with Jetspeed out of the box. It would be confusing to put all the portlets on one page all at once, so let’s group together the portlets based on categories such as ‘Basic tutorials’, ‘Advanced tutorials’, ‘Jetspeed portlets’, and ‘Referenced portlets’. It would be nice to group these four categories into a manageable user interface components. Here are our four menu choices:

Basic Tutorials
Advanced Tutorials
Jetspeed Portlets
Referenced Portlets

3.2 ナビゲーション用のPSMLコンポーネント

Jetspeed provides layout components for defining the layout of a portal page. In this tutorial we will concentrate on components used to create navigational menus. Components are defined by editing the PSML file with a text editor, or using the Jetspeed Customizer, which makes portal layout much easier.

Before seeing how easy it is with the customizer, look at the PSML file for the anonymous user.

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

<title>Welcome Page</title>

</metainfo>

<title>Basic Tutorials</title>

</metainfo>

</portlets>

<title>Advanced Tutorials</title>

</metainfo>

</portlets>

<title>Jetspeed Portlets</title>

</metainfo>

</portlets>

<title>Referenced Portlets</title>

</metainfo>

</portlets>

There are several types of elements in the layout of a PSML file. Here are the common navigational components:

<portlets> defines a pane

<controller> defines the type of layout. Must be a card controller for menus

<control> defines the type of menu . Must be used with a card controller

For each menu option, we specify a pane. Panes hold collections of portlets. The portlets on a pane have their own layout. We will discuss that in the next section. A pane is specified like this:

<title>Basic Tutorials</title>

</metainfo>

</portlets>

The <title> tag is used as the menu option text.

Panes are a special kind of a controller. There is one important difference between a pane (PanedPortletController) and other controllers: the pane does not render all of its managed portlets at the same time. That is why it needs to be used with a menu control, allowing us to navigate to the appropriate pane while hiding the other panes.

Controls are decorators around a pane or portlet. In the case of a pane, it is always used in combination with a portlet controller. There are two types of controls for panes:

TabControl – puts menu options across the top of the page
MenuControl – puts menu options on the left-side of the page

Controls are sometimes used in combination with controllers. Controllers define the layout of a pane, such as the number of columns and rows. When defining menus, you must select the CardPortletController, which enables collections of portlets to occupy the same page, and is used in combination with the a TabControl or MenuControl to create menu components. These collections of portlets are called panes.

Each of the four menu options correspond to a pane. A pane is configured in PSML using the <portlets> tag. The <metainfo> tag defines the title of the pane which is displayed in the menu.

3.3 PSMLリファレンス

For this is example, 3 of the panes are empty. The fourth pane contains PSML References.

PSML References are used to include an entire PSML resource into another PSML resource. This is useful for defining groups of markup once, and then sharing that markup in one or more PSML resources. The reference path is called a PSML resource locator. In our example, we reference two shared group resources as the content of the fourth pane.

<title>Referenced Portlets</title>

</metainfo>

</portlets>

These two PSML resources are included with the Jetspeed distribution. In the first case, the locator specifies that it is a group resource, for the media type HTML, and the name of the resource page is default. Shared PSML resources are useful for defining common layout definitions that can be used by all users of the system.

3.4 認証されたユーザ用のリソース

When a user logs on, the portal displays content customized specific to the user.

Logon as username turbine, with the password = turbine. You will see basically the same panes as defined for the anonymous user. However, this time we use a menu that is displayed on the left-side of the page.

3.5 ポートレット用のレイアウトPSMLコンポーネント

We saw how menus and panes define the navigational layout of a site. Here we will look at how to layout portlets on a particular pane. A pane is the container for portlets. Inside this container we have the choice of laying out portlets in a number of designs. This is accomplished using portlet controllers. In Tutorial 3, we only define portlets in the third pane ”Jetspeed Portlets”.

There are a fair number of controllers available for portlets:

One Column – all portlets flow down a single column on the pane
Single Row – all portlets flow across the pane in a single row
Three Column - The portlets flow down 3 columns, given column width percentages:

25/50/25
33/33/33

Two Column – The portlets flow down 2 columns, given column width percentages:

50/50
25/75
75/25

Let’s look at the pane definition for the Turbine default resource. Here we define four portlets to occupy this pane using a TwoColumns controller:

<title>Jetspeed Portlets</title>

</metainfo>

</layout>

</entry>

</layout>

</entry>

</layout>

</entry>

</layout>

</entry>

</portlets>

Notice that you can specify the location of the portlet using the <layout> element and the column and row properties. This is a task that is normally better handled by the customizer:

</layout>

If its not already obvious, the <entry> element is used to reference a portlet. We will have a closer look at the entry tag in tutorial 5.

There are controls that can be applied to portlet entries as decorators. When applied to a portlet entry, controls define the window around the portlet. Here are some typical controls:

Boxed Title Control – draws a box around the portlet, adds a title bar and action icons.
Clear Portlet Control – draws no decorators
Simple Titled Control – adds a title bar and action icons, but no box

Finally there are default settings for controls, controllers and skins which are defined in the JPortalJetspeed.properties.