Author: chris.laprun(a)jboss.com Date: 2008-03-03 20:21:10 -0500 (Mon, 03 Mar 2008) New Revision: 10186 Modified: modules/portlet/trunk/docs/user-guide/en/modules/simpleportal.xml Log: - Improved documentation with better tags where appropriate Modified: modules/portlet/trunk/docs/user-guide/en/modules/simpleportal.xml =================================================================== --- modules/portlet/trunk/docs/user-guide/en/modules/simpleportal.xml 2008-03-03 22:32:07 UTC (rev 10185) +++ modules/portlet/trunk/docs/user-guide/en/modules/simpleportal.xml 2008-03-04 01:21:10 UTC (rev 10186) @@ -15,71 +15,98 @@ <title>Simple Portal</title> <sect1> <title>Motivation</title> - <para>The JBoss Portlet Container product has developed a portal called <emphasis>Simple Portal</emphasis>. The - goal of the simple portal is to provide an easy to use portal for small sized sites that do require only - aggregation of portlets in portal pages. In particular the following features are not addressed by the - simple portal product</para> + <para>A spin-off of the JBoss Portlet Container product is a portal called<emphasis>Simple Portal</emphasis>. As + its name implies, Simple Portal provides an easy to use portal for small-sized sites that only require + aggregation of portlets in portal pages, without the extra features of a full-fledged portal. In particular the + following features are not addressed by Simple Portal: + </para> + <informaltable frame='none'> + <tgroup cols='2'> + <tbody> + <row> + <entry>Security</entry> + <entry> + Simple Portal relies on the servlet container authentication and does not provide any kind of + security enforcement + </entry> + </row> + <row> + <entry>Dynamic page creation</entry> + <entry>Simple Portal relies on JSP pages to create portal pages</entry> + </row> + <row> + <entry>Identity integration</entry> + <entry>Integration with identity systems is not provided, in particular access to the user's identity + and profile + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para>On the other hand, Simple Portal is much simpler than a traditionnal portal server because it just consist + in a few modules that only handles the basic protal concerns: the aggregation of portlet components in a web + page. + </para> + <para>The targeted use for Simple Portal are therefore restricted to:</para> <itemizedlist> - <listitem>Security: the simple portal relies on the servlet container authentication and does not provide - any kind of security enforcement.</listitem> - <listitem>Dynamic page creation: the simple portal relies on JSP pages to create portal pages.</listitem> - <listitem>Identity integration: integration with identity system is not provided, in particular - access to the user's identity and profile.</listitem> - </itemizedlist> - <para>On the other hand the simple portal is much simpler than a traditionnal portal server because it just - consist in a few modules that handles the basic concerns of portal which is the aggregation of portlet components - in a web page.</para> - <para>Therefore the goals of this product are restricted to</para> - <itemizedlist> <listitem>Portlet development</listitem> <listitem>Static portals build on top of the JSR286 specification</listitem> </itemizedlist> </sect1> <sect1> <title>Development</title> - - <para></para> - <sect2> <title>Portlet deployment</title> - <para>The simple portal integrates with a few web containers in order to provide handling of portlet - deployment and runtime. This feature is provided by a component of the JBoss Portal project called - the <emphasis>Web SPI</emphasis> which provides a Service Provider Interface that the JBoss Portal - products can rely on. In particular the JBoss Portlet Container uses the Web SPI in order to be - aware of the deployment life cycle of war files that contains portlet components. The SPI defines - two levels of integrations.</para> - <para>The SPI implementation level 1 works with any web container and relies on the fact that the portlet - developer needs to insert a specific servlet in the <filename>web.xml</filename> file of its portlet application.</para> - <para>The SPI implementation level 2 is based on more advanced integration with specific web containers - and provides a transparent integration which means that any portlet application can be deployed without - requiring any proprietary modification of the war file, keeping your application vendor agnostic. A few - containers are supported:</para> + <para>Simple Portal integrates with a few web containers in order to provide handling of portlet deployment and + runtime. This feature leverages JBoss Portal's Web Service Provider Interface (SPI). In particular, JBoss + Portlet Container uses the Web SPI in order to transparently react to the life cycle of WAR files that + contains portlet components as they are deployed or undeployed on the target servlet container. The SPI + defines two levels of integrations. + </para> + <para>SPI implementation level 1 works with any web container but relies on portlet developers to insert a + specific servlet in the + <filename>web.xml</filename> + descriptor of their portlet applications. + </para> + <para>SPI implementation level 2 is based on more advanced integration with specific web containers and + provides transparent deployment of portlet applications without requiring any proprietary modification of + the war file, keeping your application vendor agnostic. A few containers are supported: + </para> <itemizedlist> <listitem>Tomcat 6.0.x</listitem> <listitem>JBoss Application Server 4.2.x</listitem> </itemizedlist> </sect2> <sect2> - <title>The portal tag library</title> - <para>The simple portal relies on the JSP technology to build pages for several good reasons:</para> + <title>Simple Portal tag library</title> + <para>Simple Portal relies on the JSP technology to build pages for several good reasons:</para> <itemizedlist> - <listitem>JSP is a good enough technology for building simple portal pages. Obviously this does not mean that - a portlet applications is required to use JSP, as usual portlet applications are developed using your - favorite web framework.</listitem> - <listitem>Every java web developer knows JSPs.</listitem> - <listitem>It is easy and straightforward to create a portal JSP page and there is no need for advanced - tooling.</listitem> - <listitem>A lot of various frameworks are compatible with JSP and it is possible to leverage them. - For instance if you are familliar with Sitemesh for skinning an application then you can mix it with the - portal tag library.</listitem> + <listitem>JSPs provide an adequate technology for building portal pages. This does not mean that portlet + applications are required to use JSP, just that Simple Portal uses JSPs to organize portlets as pages. + Portlets themselves are independent of the technology used for pages and can be developed using whichever + technology or web framework you prefer/require. + </listitem> + <listitem>Java web developers are familiar with JSP technology.</listitem> + <listitem>JSP makes it is easy and straightforward to create portal pages without requiring advanced tooling + and, in most instances, can leverage IDEs support for JSPs. + </listitem> + <listitem>Several web frameworks are compatible with JSP and it is possible to leverage them. For example, + it is possible to use Sitemesh for application skinning and still leverage Simple Portal's JSP tag + library. + </listitem> </itemizedlist> - <para>If you need a more advanced page creation system then you should rather consider to use a more advanced - portal product such as JBoss Portal which will answer your needs.</para> + <page>If you need more advanced page creation capabilities, you should consider using a more advanced portal + product such as JBoss Portal. + </page> <sect3> <title>Page creation</title> - <para>Any JSP page can contain portlets, the only requirement to make this possible is to have - the page located in the simple portal war file and to use the portal tag library.</para> - <programlisting><![CDATA[ + <para>Any JSP page can contain portlets, the only requirement to make this possible is to have the page + located in Simple Portal's WAR file and to use the portal tag library. + </para> + <para>Let's look at a minimal portal page using the portal tag library:</para> + <example> + <title>Minimal portal page</title> + <programlisting><![CDATA[ <%@ page contentType="text/html;charset=UTF-8" language="java" %> <%@ taglib uri="/WEB-INF/portal.tld" prefix="portal" %> <?xml version="1.0" encoding="UTF-8"?> @@ -98,154 +125,342 @@ </portal:page> </body> </html>]]></programlisting> - <para>The example shows a portal page that is very minimal. Among the HTML markup and the mandatory JSP - instructions you can find the different elements that will tell the simple portal how to integrate portlets - in the page.</para> + </example> + <para>The portal tag library declaration enables the JSP compiler to know about the existence of the simple - portal. It is declared by the JSP declaration <emphasis>&lt;%@ taglib uri="/WEB-INF/portal.tld" prefix="portal" %&gt;</emphasis> - and it binds the portal tag library to the <literal>portal</literal> namespace.</para> - <para>The first tag that uses the <literal>portal</literal> namespace is the <literal>page</literal> tag which - defines a logical scope which have several impacts on the page.</para> + portal. It is declared by the JSP declaration + <code>&lt;%@ taglib uri="/WEB-INF/portal.tld" prefix="portal" %&gt;</code> + and it binds the portal tag library to the + <sgmltag class="namespace">portal</sgmltag> + namespace. + </para> + <para>The interesting part of the markup is the + <sgmltag class="element">portal:page</sgmltag> + element and its children. The + <sgmltag class="element">page</sgmltag> + tag defines a logical scope that is used by Simple Portal to generate markup: + </para> <itemizedlist> <listitem>It defines a container for a set of portlets.</listitem> - <listitem>When a portlet is maximized it defines the zone in the page that will be replaced by the maxmized - portlet markup.</listitem> + <listitem>It defines the page area that will be replaced entirely by a maximized portlet markup (when the + maximized window state is requested). + </listitem> <listitem>It defines a scope for the coordination features.</listitem> </itemizedlist> - <para>One page can be specified per JSP page but in the future we should offer the capability to have - several pages in a single JSP page. + <para>Currently, only one portal page can be specified per JSP file but this should be extended to several + portal pages per JSP file in future versions of JBoss Portlet Container. </para> - <para>Inside the portal page tag is declared a reference to a portlet using the <literal>portlet</literal> - tag. The mandatory attributes for this tag are <literal>name</literal> and <literal>applicationName</literal> that - are used to locate the deployed portlet. The <literal>applicationName</literal> refers to the name of the war - file containing your portlet without the extension <filename>.war</filename> and the <literal>name</literal> - attribute is the portlet name declared in the <filename>portlet.xml</filename> file of the application. Likewise - the page tag the portlet tag does not produce any markup, it is just a declaration to a portlet to instruct - the simple portal where it can find the portlet and how it is going to use it.</para> - <para>Finally the <literal>portletmarkup</literal> tag is the first tag to produce markup. It simply inserts - the markup created by the referenced portlet when the page is rendered.</para> + <para>Access to portlet information within a portal page is done by defining a reference to the portlet + using the + <sgmltag class="element">portlet</sgmltag> + tag. The mandatory attributes for this tag are + <sgmltag class="attribute">name</sgmltag> + and + <sgmltag class="attribute">applicationName</sgmltag> + that are used to locate the deployed portlet. The + <sgmltag class="attribute">applicationName</sgmltag> + refers to the name of the WAR file containing your portlet application without the extension + <filename>.war</filename> + and the + <sgmltag class="element">name</sgmltag> + attribute refers to the portlet name as declared by the + <sgmltag class="element">portlet-name</sgmltag> + element in the + <filename>portlet.xml</filename> + file of your portlet application WAR file. Similarly to the + <sgmltag class="element">page</sgmltag> + tag, the + <sgmltag class="element">portlet</sgmltag> + tag does not produce any markup but rather makes your portlet available to Simple Portal. + </para> + <para>The portlet markup is output using the + <sgmltag class="element">portletmarkup</sgmltag> + tag. This tag is replaced by the referenced portlet markup (without any decoration) when the page is + rendered. + </para> </sect3> <sect3> <title>Portlet title</title> - <para>We have seen in the previous example how to place a portlet in a JSP page but for the sake of simplicity - we have not yet explained how to create a complete portlet representation. The tag <literal>portlettitle</literal> - is used to insert the portlet title that the portlet produced during the render phase.</para> - <programlisting><![CDATA[ + <para>The previous example only output the portlet markup. Let's examine how to output a complete portlet + representation. The + <sgmltag class="title">portlettitle</sgmltag> + tag is used to insert the render phase generated title of the portlet referenced by the enclosing + <sgmltag class="element">portlet</sgmltag> + element: + </para> + <example> + <title>Portlet title</title> + <programlisting><![CDATA[ <portal:portlet name="JSPPortlet" applicationName="samples-jsp-portlet"> ... <portal:portlettitle/> ... </portal:portlet>]]></programlisting> + </example> + </sect3> <sect3> <title>Portlet urls</title> - <para>The capability to create urls for a portlet is very powerful and can be used to create controls - such as a button that will maximize the portlet or change its mode to another mode. The <literal>portleturl</literal> - creates such urls and insert them in the page.</para> - <programlisting><![CDATA[ + <para>It is also possible to output URLs targeting a given portlet. This can be used to create controls to + change the mode or window state of the portlet. The + <sgmltag class="element">portleturl</sgmltag> + tag outputs such URLs and insert them in the page. + </para> + <example> + <title>Portlet URL</title> + <programlisting><![CDATA[ <portal:portlet name="JSPPortlet" applicationName="samples-jsp-portlet"> ... <portal:portleturl windowState="maximized" mode="edit"/> ... </portal:portlet>]]></programlisting> - <para>The portlet url tag has two optional attributes. The <literal>windowState</literal> attribute allows - to change the window state in the url and the <literal>mode</literal> attribute controls the mode in - the url.</para> + </example> + + <para>The + <sgmltag class="element">portleturl</sgmltag> + tag has two optional attributes. The + <sgmltag class="attribute">windowState</sgmltag> + attribute allows to change the window state of the associated portlet while the + <sgmltag class="attribute">mode</sgmltag> + attribute controls the portlet mode. + </para> </sect3> <sect3> <title>Page headers</title> - <para>The Portlet 2 specification allows portlet to participate to the headers of the page. If you want - to allow the portlets on the page to add header to your page then you need to insert a <literal>headers</literal> - tag in the head section of the page, as shown in the following example.</para> - <programlisting><![CDATA[ + <para>The Portlet 2 specification allows portlet to participate to the headers of the page. If you want to + allow portlets on the page to add header information to your page then you need to insert a + <sgmltag class="element">headers</sgmltag> + tag in the + <sgmltag class="element">head</sgmltag> + section of the page, as shown in the following example: + </para> + <example> + <title>Adding portlets header contribution</title> + <programlisting><![CDATA[ <head> <portal:headers/> ... </head> ]]></programlisting> - <para>This instruct the simple portal to insert the header contributed by the portlet present on the page - at the place you specified.</para> + </example> + + <para>This instructs Simple Portal to insert header information contributed by portlets present on the page + at the specified spot. + </para> </sect3> <sect3> <title>Portlet events</title> <para>Portlet events provides a powerful way to decouple portlets. After the process action phase, an - optional event phase is executed by the portal and it can involve several portlet containers that will - produce and consume events. You can read the portlet specification if you want to learn more about it.</para> - <para>The page defines the scope of the coordination, which means that when an event - is produced by a portlet on a page, the simple portal will locate the portlets on the same page that - can consume this event. The matching is done using the the even qualified name.</para> + optional event phase is executed by the portal to process any events generated and produced by portlets. + We recommend that you read the portlet specification to learn more about portlet events. + </para> + <para>Coordination of portlets via events is scoped by pages. When an event is produced by a portlet on a + page, Simple Portal will locate all portlets on that very same page that can consume the produced event. + Produced events and consumer portlets are matched using the event's qualified name as specified in + <filename>portlet.xml</filename>. + </para> </sect3> <sect3> <title>Public render parameters</title> <para>Public render parameters allows several portlets on the same page to share render parameters. - Likewise the portlet event feature, the page is the natural scope for sharing render parameters. The simple - portal tag library allows to define initial values for such parameters allowing the developper to make - different pages to be initialized with different values for the same parameter. </para> - <programlisting><![CDATA[ + Similarly to how portlet events are handled by Simple Portal, pages are natural scopes for shared render + parameters. Simple Portal's tag library provides for the definition of initial values for such parameters + allowing developpers to configure different pages initialized with different values of the same + parameter. This is accomplished via the + <sgmltag class="element">pageparam</sgmltag> + tag. + </para> + <example> + <title>Defining a shared render parameter</title> + <programlisting><![CDATA[ <portal:page> <portal:pageparam namespaceURI="urn:jboss:portal:simple:google" localName="zipcode" value="80201"/> ... </portal:page> ]]></programlisting> - <para>In the example the page parameter <literal>zipcode</literal> having the namespace - <literal>urn:jboss:portal:simple:google</literal> will be initialized with the value - <literal>80201</literal> the first time the page is rendered. The value can change - if a portlet updates it during an interaction triggered by the end user. However it is possible - to make this parameter unmodifiable by adding a <literal>frozen</literal> attributes with - the value <literal>true</literal>, in that particular case the page parameter value will never change - when a portlet tries to update it.</para> + </example> + + <para>In the above example, we specify that the shared render parameter (or page parameter) identified by + the attribute pair + <sgmltag class="attribute">localName</sgmltag> + ( + <literal>zipcode</literal> + in the example) and + <sgmltag class="attribute">namespaceURI</sgmltag> + ( + <literal>urn:jboss:portal:simple:google</literal> + in the example) will be initialized with the value + <literal>80201</literal> + the first time the page is rendered. This value can change if any portlet supporting this shared + parameter updates it during an interaction triggered by the end user. However it is possible to make this + parameter unmodifiable (i.e. the parameter value will not change even if a portlet tries to update it) by + setting the optional + <sgmltag class="attribute">frozen</sgmltag> + attribute to the + <literal>true</literal> + value. + </para> </sect3> <sect3> <title>Error handling</title> - <para>Error handling happens at two places, the first is during page rendering and the second place - can be triggered by a portlet url. The simple portal categorizes errors into - several kinds and associate them with a string constant that can be used to programmatically - handle the error. + <para>Errors can be handled either during page rendering or when a portlet is interacted with. Simple Portal + categorizes errors and associates each error type with a category name (string) that can be used to for + programatic handling. The error categories are as follows: </para> - <itemizedlist> - <listitem><literal>not_found</literal> used when the portlet cannot be located</listitem> - <listitem><literal>portlet_error</literal> used when the portlet throws an exception</listitem> - <listitem><literal>internal_error</literal> used when the portlet throws an exception but that - is recognized as an internal error</listitem> - <listitem><literal>unavailable</literal> used when the portlet is located but is not in service</listitem> - </itemizedlist> + <table frame='all' id='error_categories'> + <title>Error Categories</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <thead> + <row> + <entry>Category name</entry> + <entry>Use case</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <literal>not_found</literal> + </entry> + <entry>The portlet that triggered the error cannot be located</entry> + </row> + <row> + <entry> + <literal>portlet_error</literal> + </entry> + <entry>The portlet triggered an exception</entry> + </row> + <row> + <entry> + <literal>internal_error</literal> + </entry> + <entry>The portlet triggered an unexpected exception recognized as an internal error</entry> + </row> + <row> + <entry> + <literal>unavailable</literal> + </entry> + <entry>The portlet is located but has been put out of service</entry> + </row> + </tbody> + </tgroup> + </table> <sect4> <title>Error handling during render</title> - <para>On a portlet failure during the render phase, it is possible to instruct the simple portal - to use an alternative page in a very similar fashion that JSP defines error pages. The only difference - is that it is not a JSP error page.</para> - <para>During the execution of the error JSP page, several request attributes are set by the portal - that will allow you to customize the markup.</para> - <itemizedlist> - <listitem><literal>org.jboss.portal.portlet.portal.error.status</literal> is a string that is the type of - the error and the value is among the error categorization explained earler.</listitem> - <listitem><literal>org.jboss.portal.portlet.portal.error.cause</literal> is an optional throwable object - that is the cause of the error. For instance it could be a portlet exception.</listitem> - <listitem><literal>org.jboss.portal.portlet.portal.error.message</literal> is a string that is the error message</listitem> - <listitem><literal>org.jboss.portal.portlet.portal.error.portlet_name</literal> is the name of the portlet - that produced the error.</listitem> - <listitem><literal>org.jboss.portal.portlet.portal.error.application_name</literal> is the name of the application - that contained the portlet that produced the error.</listitem> - <listitem><literal>org.jboss.portal.portlet.portal.error.window_id</literal> is the id of the window that produced - the error, it is useful when several portlet window with the same portlets are on the same page.</listitem> - </itemizedlist> - <para>Error page declaration is done on the portlet tag using the <literal>errorPage</literal> attribute. The value - of that attribute is the path of the error page relative to the root of the war file. Note that it could be a - or a plan file.</para> - <programlisting><![CDATA[ + <para>Simple Portal can display the content of an alternative page if, for some reason, a portlet fails + during the render phase. This is similar to JSP error pages. + </para> + <para>Several request attributes are set by Simple Portal so that the markup of the error page can be + customized appropriately. The following table sums up these request attributes and their meaning. + </para> + <table frame='all'> + <title>Request Attributes for Error Pages</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <thead> + <row> + <entry>Attribute name</entry> + <entry>Meaning</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <parameter>org.jboss.portal.portlet.portal.error.status</parameter> + </entry> + <entry>A + <className>String</className> + containing the error category as detailed in + <xref linkend='error_categories'/> + </entry> + </row> + <row> + <entry> + <parameter>org.jboss.portal.portlet.portal.error.cause</parameter> + </entry> + <entry>A (possibly<literal>null</literal>) + <className>Throwable</className> + representing the cause of the error, for example, a portlet exception + </entry> + </row> + <row> + <entry> + <parameter>org.jboss.portal.portlet.portal.error.message</parameter> + </entry> + <entry>A + <className>String</className> + containing the error message, if any + </entry> + </row> + <row> + <entry> + <parameter>org.jboss.portal.portlet.portal.error.portlet_name</parameter> + </entry> + <entry>A + <className>String</className> + containing the name of the portlet that generated the error, as defined on the associated + <sgmltag class='element'>portlet</sgmltag> + tag + </entry> + </row> + <row> + <entry> + <parameter>org.jboss.portal.portlet.portal.error.application_name</parameter> + </entry> + <entry>A + <className>String</className> + containing the name of the portlet application that generated the error, as defined on the + associated + <sgmltag class='element'>portlet</sgmltag> + tag + </entry> + </row> + <row> + <entry> + <parameter>org.jboss.portal.portlet.portal.error.window_id</parameter> + </entry> + <entry>A + <className>String</className> + containing the identifier of the window associated with the portlet that generated the + error, especially useful when several portlet windows reference the same portlet + </entry> + </row> + </tbody> + </tgroup> + </table> + <para>The + <sgmltag class="attribute">errorPage</sgmltag> + attribute of the + <sgmltag class="element">portlet</sgmltag> + tag is used to specify which error page to use for this specific portlet. The value of the attribute + should be the path to the error page relative to the root of the WAR file for that portlet. Note that + it could be a JSP or a plain file. + </para> + <example> + <title>Defining an error page</title> + <programlisting><![CDATA[ <portal:portlet name="JSPPortlet" applicationName="samples-jsp-portlet" errorPage="/WEB-INF/jsp/error.jsp"> ... </portal:portlet> ]]></programlisting> + </example> + </sect4> <sect4> <title>Error handling during action</title> - <para>On a failure during an interaction triggered by a portlet, the simple portal will throw a servlet - exception with a message value among the error categorization explained earlier.</para> - <para>By default there is a servlet filter that catches the messages and translates them into HTTP errors. - This filter is called <literal>ErrorHandlingFilter</literal> and is declared in the <filename>web.xml</filename> - file of the simple portal war. If you want to handle error differently you should replace it.</para> - <programlisting><![CDATA[ + <para>If a a failure occurs during an interaction with a portlet, Simple Portal will throw a servlet + exception with a message set to one of the category names as specified in + <xref linkend="error_categories"/> + </para> + <para>The default error handling strategy is handled by a servlet filter that catches error messages and + translates them into HTTP errors. This filter is called + <className>ErrorHandlingFilter</className> + and is declared in the + <filename>web.xml</filename> + file of Simple Portal WAR file. This allows developers to change the error handling behavior if + desired. + </para> + <example> + <title>Error handling servlet filter definition</title> + <programlisting><![CDATA[ <web-app> ... <filter-mapping> @@ -254,20 +469,29 @@ </filter-mapping> ... </web-app>]]></programlisting> + </example> + </sect4> </sect3> </sect2> <sect2> <title>Extended tag library</title> - <para>This chapter talks about an extension of the simple portal tag library that allows the display of portlets - pretty much as they are in classic portals. The extension is built on top the simple portal tag library - and uses a feature of JSP 2.0 which is the tag library extension written using JSP. There is a good article - to read about it <ulink url="http://www.onjava.com/pub/a/onjava/2004/05/12/jsp2part4.html&qu... + <para>So far, we have examined the basic building blocks provided by Simple Portal's tag library. We will now + examine an extension provided to allow the display of portlets pretty much as they are rendered in classic + portals, that is with decorations. This extension is built on top of Simple Portal's tag library and uses + the JSP 2.0 tag library extension feature. A pretty good overview of this feature can be found at<ulink + url="http://www.onjava.com/pub/a/onjava/2004/05/12/jsp2part4.html&qu... + http://www.onjava.com/pub/a/onjava/2004/05/12/jsp2part4.html</ulink>;. + </para> <sect3> <title>The extended portlet tag</title> - <para>The extended portlet is a JSP tag file located in the folder <filename>/WEB-INF/tags/portal</filename> - of the simple portal war file.</para> - <programlisting><![CDATA[ + <para>The extended portlet consists of a JSP tag file located in the folder + <filename>/WEB-INF/tags/portal</filename> + of Simple Portal's WAR file. + </para> + <example> + <title>Example use of the extended portlet tag</title> + <programlisting><![CDATA[ <%@ page contentType="text/html" %> <%@ page language="java" %> <%@ taglib prefix="xportal" tagdir="/WEB-INF/tags/portal" %> @@ -275,8 +499,11 @@ <xportal:portlet name="GoogleMap" applicationName="samples-google-portlet"/> ... ]]></programlisting> - <para>You can consider this extension pretty much like a JSP include except that it is more powerful. The - main interest is that this file can be edited and tweaked for your needs.</para> + </example> + + <para>You can consider this extension pretty much like a JSP include, just more powerful. More specifically, + the JSP tag file can be edited and tweaked to your needs. + </para> </sect3> </sect2> </sect1>