Default Configuration

Upon installation of the binary distribution of Pluto 1.0.1, the portal driver is made available at http://localhost:8080/pluto/portal. The default installation is configured with a portal page which contains two instances of the testsuite portlet and an administration. portlet for installing custom portlets and viewing the repositories. This configuration is also the default for installations completed from the source distribution (or Subversion repository) and deployed using the Pluto deploy tool.

When the Pluto Portal is first installed, it is made available at the address http://localhost:8080/pluto/portal/.

This location can be customized, using standard Tomcat functionality. To modify the pluto part of the location, alter the path mapping in pluto's context configuration file pluto.xml

Under Tomcat 5.5, pluto.xml will be located in the ${TOMCAT_HOME}/conf/Catalina/ directory.

In order to modify the context Pluto is running under, modify the path attribute:

Before:

	<Context path="/pluto" docBase="pluto" crossContext="true">
	</Context>
				

After:

	<Context path="/newlocation" docBase="pluto" crossContext="true">
	</Context>
				

You might also need to modify host.name and portletcontainer.uniquename in ${TOMCAT_HOME}/webapps/pluto/WEB-INF/config/services/ConfigService.properties.

After this modification (and restarting Tomcat), the Pluto Portal will be available at the address http://servername/newlocation/portal/. Further information on customizing the context configuration is available for Tomcat 5.5.

To modify the portal part of the location, alter the url-pattern for the pluto servlet. This mapping can be found in the web.xml configuration file for the Pluto web application.

Before:

    <servlet-mapping>
       <servlet-name>pluto</servlet-name>
       <url-pattern>/portal/*</url-pattern>
    </servlet-mapping>
				

After:

    <servlet-mapping>
       <servlet-name>pluto</servlet-name>
       <url-pattern>/app/*</url-pattern>
    </servlet-mapping>
				

You will also need to modify servlet.insecure in ${TOMCAT_HOME}/webapps/pluto/WEB-INF/config/services/ConfigService.properties.

After these modifications (and restarting Tomcat), the Pluto Portal will be available at the address http://servername/newlocation/app/ (assuming that the previous modification was also applied).

Registering Portlets for use

In order to use a Portlet in the Pluto Portal it needs to be registered. The Pluto Portal keeps page registrations in a file named portletentityregistry.xml in the directory ${TOMCAT_HOME}/webapps/pluto/data.

By default, this file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<portlet-entity-registry>
    <application id="3">
        <definition-id>testsuite</definition-id>
        <portlet id="1">
            <definition-id>testsuite.TestPortlet1</definition-id>
            <preferences>
                <pref-name>TestName4</pref-name>
                <pref-value>TestValue4</pref-value>
                <read-only>true</read-only>
            </preferences>
        </portlet>
    </application>
    <application id="4">
        <definition-id>testsuite</definition-id>
        <portlet id="1">
            <definition-id>testsuite.TestPortlet2</definition-id>
            <preferences>
                <pref-name>TestName4</pref-name>
                <pref-value>TestValue4</pref-value>
                <read-only>true</read-only>
            </preferences>
        </portlet>
    </application>
</portlet-entity-registry>
				

Each <application> tag defines one application (corresponding to one web-app on the portal container), which can contain multiple <portlet> tags. The "id" attribute in this tag identifies the application, and it does not need to be numeric.

The <definition-id> tag within the <application> refers to the name of the web-app that contains the portlets in this application.

Each <portlet> tag defines one portlet. The "id" attribute in this tag identifies the portlet. Note that the application id concatenated with the portlet id will be mapped to the "value" attribute in the <proprety> tag in pageregistry.xml (which is explained later).

Each <preferences> tag within the <portlet> tag defines name/value pairs for the PorletPreferences.

In the example above two Portlet applications are made available to the portal with the ids of "3" and "4". Both happen to point to the same webapp (<definition-id>testsuite</definition-id>). Both applications define a single Portlet each. Application id 3 uses the Portlet TestPortlet1 (<definition-id>testsuite.TestPortlet1</definition-id>), while Application id 4 uses the Portlet TestPortlet2 (<definition-id>testsuite.TestPortlet2</definition-id>). Note that prefixing the name of the Portlet with the name of web application (testsuite.TestPortlet1) is required.

Since Pluto 1.0.1-rc2, another configuration file, portletcontexts.txt, has been included in the Pluto portal. The Portlet Contexts file ($PLUTO_HOME/WEB-INF/data/portletcontexts.txt) lists the webapp contexts for each portlet application that runs in Pluto. Each portlet app has a line in this file corresponding to a path and starting with a slash ('/'). In Tomcat, this path is the value of the 'path' attribute of the 'Context' element in a context XML descriptor in $TOMCAT_HOME/conf/Catalina/localhost (or another 'conf' subdirectory).

The Portlets themselves are defined in the portlet.xml configuration file within the testsuite web application. In that file there are two Portlets defined, TestPortlet1 and TestPortlet2, both of which point to the same portlet class (org.apache.pluto.portalImpl.portlet.TestPortlet). See the javax.portlet specification (JSR-168) for futher details on using the portlet.xml file.

Defining the Portal Layout

Once the Portlets available have been defined the Portal layout needs to be defined. In the Pluto Portal the file pageregistry.xml in the directory ${TOMCAT_HOME}/webapps/pluto/data defines this layout.

When Pluto is first installed, pageregistry.xml looks like this:

<?xml version="1.0"?>
<portal>
    <fragment name="navigation" class="org.apache.pluto.portalImpl.aggregation.navigation.TabNavigation">
    </fragment>

    <fragment name="test" type="page">
        <navigation>
            <title>Test</title>
            <description>...</description>
        </navigation>

        <fragment name="row" type="row">
            <fragment name="col1" type="column">

                <fragment name="p1" type="portlet">
                    <property name="portlet" value="3.1"/>
                </fragment>
                <fragment name="p2" type="portlet">
                    <property name="portlet" value="4.1"/>
                </fragment>

            </fragment>
        </fragment>
    </fragment>
</portal>
			

This configuration results in the Portal being displayed (from the url http://servername/pluto/portal/test/) as Figure 1 shows.

Working from the top of pageregistry.xml down, the first important section we come to is:

<fragment name="navigation" class="org.apache.pluto.portalImpl.aggregation.navigation.TabNavigation">
</fragment>
				

This section tells the Portal to add a navigation menu to the user interface. Each fragment of type page will be displayed in the navigation menu, provided the fragment has a <navigation> sub-element. Removing the <fragment name="navigation" ...></fragment> section will result in no navigation menu being displayed.

The next section is:

    <fragment name="test" type="page">
        <navigation>
            <title>Test</title>
            <description>...</description>
        </navigation>
		...
		...
    </fragment>
				

This section defines a Portal "page", which is simply a container for one or more Portlets. The name attribute must be unique within the pageregistry.xml file (if this constraint is not met an error message Fragment with this name <duplicated name> already exists in the pageregistry.xml. will be written to your log and your Pluto web application will fail to load).

The navigation subsection is used by the navigation menu (discussed previously). The <title>...</title> defines the label that will be shown in the navigation menu. The <description>...</description>element is not used.

Inside the <fragment type="page" .... ></fragment> elements we find

    <fragment name="row" type="row">
        <fragment name="col1" type="column">

            <fragment name="p1" type="portlet">
                <property name="portlet" value="3.1"/>
            </fragment>
            <fragment name="p2" type="portlet">
                <property name="portlet" value="4.1"/>
            </fragment>

        </fragment>
    </fragment>
				

This defines the layout of the Portal "page". In this case two Portlets will be laid out in two columns, nested inside a single row.

The configuration below will give the page a layout of two rows, with a Portlet in each. Note that the names of all fragments need to be unique.

	<fragment name="row1" type="row">
	    <fragment name="col1" type="column">
	        <fragment name="p1" type="portlet">
	            <property name="portlet" value="3.1"/>
	        </fragment>
	    </fragment>
	</fragment>
	<fragment name="row2" type="row">
	    <fragment name="col2" type="column">
	        <fragment name="p2" type="portlet">
	            <property name="portlet" value="4.1"/>
	        </fragment>
	    </fragment>
	</fragment>
				

The section

    <fragment name="p1" type="portlet">
        <property name="portlet" value="3.1"/>
    </fragment>
    			

defines which portlet to display. <property name="portlet" value="3.1"/> tells the Portal to lookup the Portlet "3.1" and display it in this location. The value "3.1" means refers to the ids given in portletentityregistry.xml (discussed previously). In this case, it mean application id "3", portlet id "1".

JSP Templates

It is possible to customize the JSP templates Pluto uses. This is beyond the scope of this document, but a brief outline follows to get you started.

By default, Pluto uses JSP templates from the directory ${TOMCAT_HOME}/webapps/pluto/WEB-INF/aggregation directory. This can be overridden by adding a line like

aggregation.base.dir=/WEB-INF/templates/
				

The following JSP files are used by the Portal:

• Banner.jsp - The blue title bar which says "Pluto - Reference Implementation". Only called from RootFragment.jsp
• ColumnFragment.jsp - Called for each column fragment.
• Head.jsp - The HTML header. Only called from RootFragment.jsp
• PageFragment.jsp - Called for each Portal page displayed.
• PortletFragmentFooter.jsp - The footer of each Portlet.
• PortletFragmentHeader.jsp - The header of each Portlet.
• RootFragment.jsp - Defines the layout of the Portal. This is the file to modify if you need to modify the width of the navigation bar, for instance.
• RowFragment.jsp - Called for each row fragment.
• TabNavigation.jsp - Displays the navigation menu.

Most customization of the Portal can be done in RootFragment.jsp, PortletFragmentHeader.jsp and PortletFragmentFooter.jsp.

Internationalization

The Pluto portal supports non latin-1 character-sets in its output. To enable this, uncomment the section

	 <init-param>
	     <param-name>charset</param-name>
	     <param-value>utf-8</param-value>
	 </init-param>
				

Further Information

Further information can be found in the FAQ, on the Mailing Lists and on the Wiki