| <?xml version="1.0" encoding="UTF-8"?> | |
| <!-- | |
| 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="nlothian.AT.apache.DOT.org">Nick Lothian</author> | |
| <author email="ddewolf.AT.apache.DOT.org">David DeWolf</author> | |
| <author email="cdoremus.AT.apache.DOT.org">Craig Doremus</author> | |
| <author email="zheng.AT.apache.DOT.org">ZHENG Zhong</author> | |
| <title>User Guide: Pluto Portal Driver</title> | |
| </properties> | |
| <body> | |
| <section name="User Guide: Pluto 1.0.1 Portal Driver"> | |
| <p> | |
| <ul> | |
| <li><A href="#Limitations">Limitations</A></li> | |
| <li><A href="#Configuration">Configuration</A></li> | |
| <li><A href="#Defining_the_Portal_Layout">Defining the Portal Layout</A></li> | |
| <li><A href="#Advanced_Customization">Advanced Customization</A></li> | |
| <li><A href="#Internationalization">Internationalization</A></li> | |
| <li><A href="#Further_Information">Further Information</A></li> | |
| </ul> | |
| </p> | |
| </section> | |
| <section name="Limitations"> | |
| <p> | |
| The Pluto Portal is intended to provide an example implementation of | |
| how to integrate Pluto into a portal. Additionally, it may be used for | |
| the development of compliant portlets. In some places it lacks the | |
| flexibility a true portal supplies. The portal is not designed for | |
| maximum performance, but rather simplicity. | |
| </p> | |
| <p> | |
| To learn how to embed Pluto in your own portal, see the | |
| "<a href="../developer/integrate.html">Integration Guide</a>" document.</p> | |
| </section> | |
| <section name="Configuration"> | |
| <subsection name="Default Configuration"> | |
| <p> | |
| Upon installation of the binary distribution of Pluto 1.0.1, the portal | |
| driver is made available at <code>http://localhost:8080/pluto/portal</code>. | |
| 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. | |
| </p> | |
| <p> | |
| <table> | |
| <caption><B>Default Configuration for Binary Distributions:</B></caption> | |
| <tr><th>Configuration</th> | |
| <th>Platform</th> | |
| <th>Value</th><th>Description</th></tr> | |
| <tr><td>Installation Directory</td> | |
| <td>All</td> | |
| <td><PLUTO_HOME></td> | |
| <td>The directory to which you unarchived the distribution</td></tr> | |
| <tr><td>Startup Scripts</td> | |
| <td>*nix</td> | |
| <td><PLUTO_HOME>/bin/startup.sh</td> | |
| <td>The script used to startup the portal driver</td></tr> | |
| <tr><td>Startup Scripts</td> | |
| <td>Windows</td> | |
| <td><PLUTO_HOME>/bin/startup.bat</td> | |
| <td>The script used to startup the portal driver</td></tr> | |
| <tr><td>Context Configuration</td> | |
| <td>All</td> | |
| <td><PLUTO_HOME>/conf/Catalina/localhost/pluto.xml</td> | |
| <td>The Tomcat Context Configuration file</td></tr> | |
| </table> | |
| </p> | |
| <p> | |
| <table> | |
| <caption><B>Default Configuration for Source Distributions:</B></caption> | |
| <tr><th>Configuration</th> | |
| <th>Platform</th> | |
| <th>Value</th><th>Description</th></tr> | |
| <tr><td>Installation Directory</td> | |
| <td>All</td> | |
| <td>${maven.tomcat.home}</td> | |
| <td>The tomcat installation directory to which pluto has been installed</td></tr> | |
| <tr><td>Startup Scipts</td> | |
| <td>*nix</td> | |
| <td>${maven.tomcat.home}/bin/startup.sh</td> | |
| <td>The script used to startup the portal driver</td></tr> | |
| <tr><td>Startup Scipts</td> | |
| <td>Windows</td> | |
| <td>${maven.tomcat.home}/bin/startup.bat</td> | |
| <td>The script used to startup the portal driver</td></tr> | |
| <tr><td>Context Configuration</td> | |
| <td>Tomcat 5.5</td> | |
| <td>${maven.tomcat.home}/conf/Catalina/localhost/pluto.xml</td> | |
| <td>The Tomcat Context Configuration file</td></tr> | |
| </table> | |
| </p> | |
| <p>When the Pluto Portal is first installed, it is made available at | |
| the address http://localhost:8080/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 5.5, pluto.xml will be located | |
| 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>You might also need to modify host.name and portletcontainer.uniquename in | |
| ${TOMCAT_HOME}/webapps/pluto/WEB-INF/config/services/ConfigService.properties. | |
| </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-5.5-doc/config/context.html">Tomcat 5.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>You will also need to modify servlet.insecure in ${TOMCAT_HOME}/webapps/pluto/WEB-INF/config/services/ConfigService.properties. | |
| </p> | |
| <p>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). | |
| </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> | |
| 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). | |
| </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/v101/default_portal_layout.jpg"> | |
| <img src="../../images/v101/default_portal_layout.jpg" | |
| alt="Default Portal Layout" width="500"/></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="Internationalization"> | |
| <p>The Pluto portal supports non latin-1 character-sets in its output. To enable this, uncomment the section | |
| <source> | |
| <init-param> | |
| <param-name>charset</param-name> | |
| <param-value>utf-8</param-value> | |
| </init-param> | |
| </source> | |
| from the "pluto" Servlet section in the file ${TOMCAT_HOME}/webapps/pluto/WEB-INF/web.xml.</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> | |