9:34 a.m.
Author: julien(a)jboss.com
Date: 2008-03-03 10:34:52 -0500 (Mon, 03 Mar 2008)
New Revision: 10181
Added:
modules/portlet/trunk/portal/src/main/java/org/jboss/portal/portlet/portal/Constants.java
Removed:
modules/portlet/trunk/portal/src/main/java/org/jboss/portal/portlet/portal/jsp/taglib/Constants.java
Modified:
modules/portlet/trunk/docs/user-guide/en/modules/simpleportal.xml
Log:
more documentation
Modified: modules/portlet/trunk/docs/user-guide/en/modules/simpleportal.xml
===================================================================
--- modules/portlet/trunk/docs/user-guide/en/modules/simpleportal.xml 2008-03-03 11:43:50
UTC (rev 10180)
+++ modules/portlet/trunk/docs/user-guide/en/modules/simpleportal.xml 2008-03-03 15:34:52
UTC (rev 10181)
@@ -80,8 +80,24 @@
<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[
-todo
-]]></programlisting>
+<%@ page contentType="text/html;charset=UTF-8" language="java"
%>
+<%@ taglib uri="/WEB-INF/portal.tld" prefix="portal" %>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html
+PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
lang="en">
+ <head>
+ <title>Simple portal page</title>
+ </head>
+ <body>
+ <portal:page>
+ <portal:portlet name="JSPPortlet"
applicationName="samples-jsp-portlet">
+ <portal:portletmarkup/>
+ </portal:portlet>
+ </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>
@@ -89,14 +105,14 @@
portal. It is declared by the JSP declaration <emphasis><%@
taglib uri="/WEB-INF/portal.tld" prefix="portal"
%></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.
- <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 a scope for the coordination
features.</listitem>
- </itemizedlist>
- One page can be specified per JSP page but in the future we will likely have
the feature to have
+ defines a logical scope which have several impacts on the page.</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 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>
<para>Inside the portal page tag is declared a reference to a portlet
using the <literal>portlet</literal>
@@ -110,16 +126,45 @@
the markup created by the referenced portlet when the page is
rendered.</para>
</sect3>
<sect3>
- <title>Page headers</title>
- <para>todo</para>
+ <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[
+<portal:portlet name="JSPPortlet"
applicationName="samples-jsp-portlet">
+ ...
+ <portal:portlettitle/>
+ ...
+</portal:portlet>]]></programlisting>
</sect3>
<sect3>
- <title>Portlet title</title>
- <para>todo</para>
+ <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[
+<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 allow
+ to change the window state in the url and the
<literal>mode</literal> attribute controls the mode in
+ the url.</para>
</sect3>
<sect3>
- <title>Portlet controls</title>
- <para>todo</para>
+ <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[
+<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>
</sect3>
<sect3>
<title>Portlet events</title>
@@ -132,8 +177,76 @@
</sect3>
<sect3>
<title>Public render parameters</title>
- <para>todo</para>
+ <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[
+<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>
</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>
+ <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>
+ <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[
+<portal:portlet name="JSPPortlet"
applicationName="samples-jsp-portlet"
errorPage="/WEB-INF/jsp/error.jsp">
+ ...
+</portal:portlet>
+]]></programlisting>
+ </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>
+ </sect4>
+ </sect3>
</sect2>
<sect2>
<title>Extended tag library</title>
Copied:
modules/portlet/trunk/portal/src/main/java/org/jboss/portal/portlet/portal/Constants.java
(from rev 10175,
modules/portlet/trunk/portal/src/main/java/org/jboss/portal/portlet/portal/jsp/taglib/Constants.java)
===================================================================
---
modules/portlet/trunk/portal/src/main/java/org/jboss/portal/portlet/portal/Constants.java
(rev 0)
+++
modules/portlet/trunk/portal/src/main/java/org/jboss/portal/portlet/portal/Constants.java 2008-03-03
15:34:52 UTC (rev 10181)
@@ -0,0 +1,65 @@
+/******************************************************************************
+ * JBoss, a division of Red Hat *
+ * Copyright 2008, Red Hat Middleware, LLC, and individual *
+ * contributors as indicated by the @authors tag. See the *
+ * copyright.txt in the distribution for a full listing of *
+ * individual contributors. *
+ * *
+ * This is free software; you can redistribute it and/or modify it *
+ * under the terms of the GNU Lesser General Public License as *
+ * published by the Free Software Foundation; either version 2.1 of *
+ * the License, or (at your option) any later version. *
+ * *
+ * This software is distributed in the hope that it will be useful, *
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of *
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
+ * Lesser General Public License for more details. *
+ * *
+ * You should have received a copy of the GNU Lesser General Public *
+ * License along with this software; if not, write to the Free *
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA *
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org. *
+ ******************************************************************************/
+package org.jboss.portal.portlet.portal;
+
+/**
+ * @author <a href="mailto:julien@jboss.org">Julien Viet</a>
+ * @version $Revision: 630 $
+ */
+public final class Constants
+{
+
+ private Constants()
+ {
+ }
+
+ /** . */
+ public static final String ERROR_STATUS =
"org.jboss.portal.portlet.portal.error.status";
+
+ /** . */
+ public static final String ERROR_CAUSE =
"org.jboss.portal.portlet.portal.error.cause";
+
+ /** . */
+ public static final String ERROR_MESSAGE =
"org.jboss.portal.portlet.portal.error.message";
+
+ /** . */
+ public static final String ERROR_PORTLET_NAME =
"org.jboss.portal.portlet.portal.error.portlet_name";
+
+ /** . */
+ public static final String ERROR_APPLICATION_NAME =
"org.jboss.portal.portlet.portal.error.application_name";
+
+ /** . */
+ public static final String ERROR_WINDOW_ID =
"org.jboss.portal.portlet.portal.error.window_id";
+
+ /** . */
+ public static final String NOT_FOUND = "not_found";
+
+ /** . */
+ public static final String PORTLET_ERROR = "portlet_error";
+
+ /** . */
+ public static final String INTERNAL_ERROR = "internal_error";
+
+ /** . */
+ public static final String UNAVAILABLE = "unavailable";
+}
Deleted:
modules/portlet/trunk/portal/src/main/java/org/jboss/portal/portlet/portal/jsp/taglib/Constants.java
===================================================================
---
modules/portlet/trunk/portal/src/main/java/org/jboss/portal/portlet/portal/jsp/taglib/Constants.java 2008-03-03
11:43:50 UTC (rev 10180)
+++
modules/portlet/trunk/portal/src/main/java/org/jboss/portal/portlet/portal/jsp/taglib/Constants.java 2008-03-03
15:34:52 UTC (rev 10181)
@@ -1,65 +0,0 @@
-/******************************************************************************
- * JBoss, a division of Red Hat *
- * Copyright 2008, Red Hat Middleware, LLC, and individual *
- * contributors as indicated by the @authors tag. See the *
- * copyright.txt in the distribution for a full listing of *
- * individual contributors. *
- * *
- * This is free software; you can redistribute it and/or modify it *
- * under the terms of the GNU Lesser General Public License as *
- * published by the Free Software Foundation; either version 2.1 of *
- * the License, or (at your option) any later version. *
- * *
- * This software is distributed in the hope that it will be useful, *
- * but WITHOUT ANY WARRANTY; without even the implied warranty of *
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
- * Lesser General Public License for more details. *
- * *
- * You should have received a copy of the GNU Lesser General Public *
- * License along with this software; if not, write to the Free *
- * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA *
- * 02110-1301 USA, or see the FSF site: http://www.fsf.org. *
- ******************************************************************************/
-package org.jboss.portal.portlet.portal.jsp.taglib;
-
-/**
- * @author <a href="mailto:julien@jboss.org">Julien Viet</a>
- * @version $Revision: 630 $
- */
-final class Constants
-{
-
- private Constants()
- {
- }
-
- /** . */
- public static final String ERROR_STATUS =
"org.jboss.portal.portlet.portal.error.status";
-
- /** . */
- public static final String ERROR_CAUSE =
"org.jboss.portal.portlet.portal.error.cause";
-
- /** . */
- public static final String ERROR_MESSAGE =
"org.jboss.portal.portlet.portal.error.message";
-
- /** . */
- public static final String ERROR_PORTLET_NAME =
"org.jboss.portal.portlet.portal.error.portlet_name";
-
- /** . */
- public static final String ERROR_APPLICATION_NAME =
"org.jboss.portal.portlet.portal.error.application_name";
-
- /** . */
- public static final String ERROR_WINDOW_ID =
"org.jboss.portal.portlet.portal.error.window_id";
-
- /** . */
- public static final String NOT_FOUND = "not_found";
-
- /** . */
- public static final String PORTLET_ERROR = "portlet_error";
-
- /** . */
- public static final String INTERNAL_ERROR = "internal_error";
-
- /** . */
- public static final String UNAVAILABLE = "unavailable";
-}