You are viewing a plain text version of this content. The canonical link for it is here.
Posted to pluto-dev@portals.apache.org by nl...@apache.org on 2004/02/25 12:02:46 UTC
cvs commit: jakarta-pluto/xdocs Howto_use_the_Pluto_portal.xml
nlothian 2004/02/25 03:02:46
Added: xdocs Howto_use_the_Pluto_portal.xml
Log:
Documentation on how to use the Pluto Portlet. This was on the Todo list: http://nagoya.apache.org/bugzilla/show_bug.cgi?id=25282
Revision Changes Path
1.1 jakarta-pluto/xdocs/Howto_use_the_Pluto_portal.xml
Index: Howto_use_the_Pluto_portal.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="sthepper@apache.org">Nick Lothian</author>
<title>How to use the Pluto Portal</title>
</properties>
<body>
<section name="How to use the Pluto Portal">
<subsection name="Prerequisites">
<p>It is expected that the reader of this document should have an understanding of Java
Web Application development, as well as Java Portlet Development.</p>
</subsection>
</section>
<section name="Introduction to the Pluto Portal">
<subsection name="Limitations of the Pluto Portal">
<p>The Pluto Portal is only intended as a demonstration of how to use Pluto in a portal. In some places it lacks
the flexibility a true portal supplies, and it isn't designed for maximum performance.</p>
<p>To learn how to embed Pluto in your own portal, see the
"<a href="Howto_use_the_Pluto_container.html">Pluto in your portal</a>" document.</p>
</subsection>
</section>
<section name="Configuration of the Pluto Portal">
<subsection name="The Pluto Portal Context">
<p>When the Pluto Portal is first installed, it is made available at the address http://servername/pluto/portal/.</p>
<p>This location can be customized, using standard Tomcat functionality. To modify the <i>pluto</i> part of the
location, alter the path mapping in pluto's context configuration file <i>pluto.xml</i></p>
<p>Under Tomcat 4.1, pluto.xml will be created in the ${TOMCAT_HOME}/webapps/ directory. Under Tomcat 5, pluto.xml will be created
in the ${TOMCAT_HOME}/conf/Catalina/ directory. </p>
<p>In order to modify the context Pluto is running under, modify the <i>path</i> attribute:</p>
<p>
<b>Before:</b>
<source>
<Context path="/pluto" docBase="pluto" crossContext="true">
</Context>
</source>
</p>
<p><b>After:</b>
<source>
<Context path="/newlocation" docBase="pluto" crossContext="true">
</Context>
</source>
</p>
<p>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
<a href="http://jakarta.apache.org/tomcat/tomcat-4.1-doc/config/context.html">Tomcat 4.1</a>
and <a href="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/config/context.html">Tomcat 5</a>.
</p>
<p>To modify the <i>portal</i> part of the location, alter the <i>url-pattern</i> for the
<i>pluto</i> servlet. This mapping can be found in the <i>web.xml</i> configuration file
for the Pluto web application.</p>
<p>
<b>Before:</b>
<source>
<servlet-mapping>
<servlet-name>pluto</servlet-name>
<url-pattern>/portal/*</url-pattern>
</servlet-mapping>
</source>
</p>
<p>
<b>After:</b>
<source>
<servlet-mapping>
<servlet-name>pluto</servlet-name>
<url-pattern>/app/*</url-pattern>
</servlet-mapping>
</source>
</p>
<p>After this modification (and restarting Tomcat),
the Pluto Portal will be available at the address http://servername/newlocation/app/
(assuming that the previous modification was also applied).
</p>
</subsection>
<subsection name="Registering Portlets for use">
<p>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 <i>portletentityregistry.xml</i> in the directory
${TOMCAT_HOME}/webapps/pluto/data.</p>
<p>By default, this file looks like this:
<source>
<?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>
</source>
</p>
<p>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.</p>
<p>The <definition-id> tag within the <application> refers to the name of the
web-app that contains the portlets in this application.</p>
<p>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).</p>
<p>Each <preferences> tag within the <portlet> tag defines name/value pairs for
the PorletPreferences.</p>
<p>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 (<tt><definition-id>testsuite</definition-id></tt>).
Both applications define a single Portlet each. Application id 3 uses the Portlet <i>TestPortlet1</i>
(<tt><definition-id>testsuite.TestPortlet1</definition-id></tt>), while Application id 4 uses
the Portlet <i>TestPortlet2</i> (<tt><definition-id>testsuite.TestPortlet2</definition-id></tt>).
Note that prefixing the name of the Portlet with the name of web application (<i><b>testsuite</b>.TestPortlet1</i>)
is required.
</p>
<p>The Portlets themselves are defined in the portlet.xml configuration file within the
testsuite web application. In that file there are two Portlets defined,
<i>TestPortlet1</i> and <i>TestPortlet2</i>, both of which point to the same
portlet class (<tt>org.apache.pluto.portalImpl.portlet.TestPortlet</tt>).
See the javax.portlet specification (JSR-168) for futher details on using the portlet.xml file.
</p>
</subsection>
<subsection name="Defining the Portal Layout">
<p>Once the Portlets available have been defined the Portal layout needs to be defined. In the
Pluto Portal the file <i>pageregistry.xml</i> in the directory ${TOMCAT_HOME}/webapps/pluto/data defines this layout.</p>
<p>When Pluto is first installed, pageregistry.xml looks like this:
<source>
<?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>
</source>
</p>
<p>This configuration results in the Portal being displayed
(from the url http://servername/pluto/portal/test/) as Figure 1 shows.</p>
<div align="center">
<p>
<a href="images/defaultPortalLayout.gif"><img src="images/defaultPortalLayoutThumb.gif" alt="Default Portal Layout" border="0"/></a>
</p>
<p>
<i><b><font size="-1">Figure 1. Default Portal Layout. Click on the picture to enlarge it</font></b></i>
</p>
</div>
<p>Working from the top of pageregistry.xml down, the first important section we come to is:
<source>
<fragment name="navigation" class="org.apache.pluto.portalImpl.aggregation.navigation.TabNavigation">
</fragment>
</source>
</p>
<p>This section tells the Portal to add a navigation menu to the user interface. Each fragment of
type <i>page</i> will be displayed in the navigation menu, provided the fragment has a <navigation>
sub-element. Removing the <tt><fragment name="navigation" ...></fragment></tt> section
will result in no navigation menu being displayed.
</p>
<p>
The next section is:
<source>
<fragment name="test" type="page">
<navigation>
<title>Test</title>
<description>...</description>
</navigation>
...
...
</fragment>
</source>
</p>
<p>
This section defines a Portal "page", which is simply a container for one or more Portlets. The <i>name</i>
attribute must be unique within the pageregistry.xml file (if this constraint is not met an error
message <i>Fragment with this name <duplicated name> already exists in the pageregistry.xml.</i> will be written to your
log and your Pluto web application will fail to load).
</p>
<p>
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.
</p>
<p>Inside the <tt><fragment type="page" .... ></fragment></tt> elements we find
<source>
<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>
</source>
</p>
<p>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.
</p>
<p>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.
<source>
<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>
</source>
</p>
<p>The section
<source>
<fragment name="p1" type="portlet">
<property name="portlet" value="3.1"/>
</fragment>
</source>
</p>
<p>defines which portlet to display. <tt><property name="portlet" value="3.1"/></tt> 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 <i>portletentityregistry.xml</i> (discussed previously). In this case, it mean application id "3",
portlet id "1".
</p>
</subsection>
</section>
<section name="Advanced Customization">
<subsection name="JSP Templates">
<p>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.</p>
<p>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
<source>
aggregation.base.dir=/WEB-INF/templates/
</source>
to the file ${TOMCAT_HOME}/webapps/pluto/WEB-INF/config/services/ConfigService.properties.
</p>
<p>The following JSP files are used by the Portal:
<ul>
<li>Banner.jsp - The blue title bar which says "Pluto - Reference Implementation". Only called from RootFragment.jsp</li>
<li>ColumnFragment.jsp - Called for each column fragment.</li>
<li>Head.jsp - The HTML header. Only called from RootFragment.jsp</li>
<li>PageFragment.jsp - Called for each Portal page displayed.</li>
<li>PortletFragmentFooter.jsp - The footer of each Portlet.</li>
<li>PortletFragmentHeader.jsp - The header of each Portlet.</li>
<li>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.</li>
<li>RowFragment.jsp - Called for each row fragment.</li>
<li>TabNavigation.jsp - Displays the navigation menu.</li>
</ul>
</p>
<p>
Most customization of the Portal can be done in RootFragment.jsp,
PortletFragmentHeader.jsp and PortletFragmentFooter.jsp.
</p>
</subsection>
<subsection name="Further information">
<p>
Further information can be found in the <a href="faq.html">FAQ</a>, on the <a href="mail-lists.html">Mailing Lists</a>
and on the <a href="wiki.html">Wiki</a>
</p>
</subsection>
</section>
</body>
</document>