Author: mmcallis
Date: 2008-02-08 01:09:19 -0500 (Fri, 08 Feb 2008)
New Revision: 9862
Modified:
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/tutorials.xml
Log:
revising 5.2.1.4. Application Descriptors
changing itemizedlists to variablelists
Modified: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/tutorials.xml
===================================================================
---
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/tutorials.xml 2008-02-08
05:23:36 UTC (rev 9861)
+++
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/tutorials.xml 2008-02-08
06:09:19 UTC (rev 9862)
@@ -148,8 +148,7 @@
<sect3>
<title>Package Structure</title>
<para>
- Like other Java EE applications, portlets are packaged in WAR files. A
typical portlet WAR file can also
- include servlets, resource bundles, images, HTML, JSPs, and other static
or dynamic files. The following is an example of the directory structure of the
HelloWorldPortlet portlet:
+ Like other Java EE applications, portlets are packaged in WAR files. A
typical portlet WAR file can include servlets, resource bundles, images, HTML, JSPs, and
other static or dynamic files. The following is an example of the directory structure of
the HelloWorldPortlet portlet:
</para>
<para>
<mediaobject>
@@ -160,7 +159,7 @@
</para>
</sect3>
<sect3>
- <title>Portlet Class</title>
+ <title>Portlet Classes</title>
<para>
The following is the
<filename>HelloWorldPortlet/src/main/org/jboss/portlet/hello/HelloWorldPortlet.java</filename>
java source file, which comes bundled with the <ulink
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_6/bundles...;:
@@ -254,18 +253,22 @@
<sect3 id="first_portlet_descriptors">
<title>Application Descriptors</title>
<para>
- JBoss Portal requires certain descriptors be included in your portlet WAR,
for different reasons. Some of
- these descriptors are defined by the Portlet Specification, some are
specific to JBoss Portal.
+ JBoss Portal requires certain descriptors to be included in a portlet WAR
file. Some of
+ these descriptors are defined by the JSR-168 Portlet Specification, and others
are specific to JBoss Portal. The following is an example of the directory structure of
the HelloWorldPortlet portlet:
+ </para>
+ <para>
<mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/tutorials/first_portlet/package.gif"
valign="middle"/>
</imageobject>
</mediaobject>
- Now let's explain what each of these does:
- <itemizedlist>
- <listitem>
- <para><literal>portlet.xml</literal>
-<programlisting><![CDATA[<?xml version="1.0"
encoding="UTF-8"?>
+ </para>
+ <para>
+ The following is an example of the
<filename>HelloWorldPortlet/WEB-INF/portlet.xml</filename> file. Note: in
order to create the <filename>WEB-INF</filename> and
<filename>META-INF</filename> directories, extract the
<filename>helloworldportlet.war</filename> file:
+ </para>
+ <para>
+<screen><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
<portlet-app
xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1...
@@ -282,57 +285,64 @@
<title>HelloWorld Portlet</title>
</portlet-info>
</portlet>
-</portlet-app>]]></programlisting>
- This file must adhere to its definition in the Portlet
Specification. You may define more than
- one portlet application in this file.
- <itemizedlist>
- <listitem>
- <para>
-
<programlisting><![CDATA[<portlet-name>HelloWorldPortlet</portlet-name>]]></programlisting>
- Define your portlet name. It does not have to be the
Class name.
- </para>
- </listitem>
- <listitem>
- <para>
-
<programlisting><![CDATA[<portlet-class>org.jboss.portlet.hello.HelloWorldPortlet</portlet-class>]]></programlisting>
- The Fully Qualified Name (FQN) of your portlet class
must be declared here.
- </para>
- </listitem>
- <listitem>
- <para>
- <programlisting><![CDATA[<supports>
- <mime-type>text/html</mime-type>
- <portlet-mode>VIEW</portlet-mode>
-</supports>]]></programlisting>
- The <literal>supports</literal> element
allows you to declare all the markup types your
- portlet supports in the
<literal>render</literal> method. This is accomplish via the
- <literal>mime-type</literal> element, which
is <emphasis>required</emphasis> for every
- portlet. Of course, the declared MIME types must match
the capability of the portlet.
-
- It also allows you to pair
- which modes and window states are supported for each
markup type. In out case, as all
- portlets must support the VIEW portlet mode, we
didn't have to declare it. We did need
- to declare that our portlet supports the
<literal>text/html</literal> markup type.
- Hence, we are letting the portal know that it will be
outputting text/html and
- only support a VIEW mode.
- </para>
- </listitem>
- <listitem>
- <para>
- <programlisting><![CDATA[<portlet-info>
- <title>HelloWorld Portlet</title>
-</portlet-info>
-]]></programlisting>
- The portlet's title will be displayed as the header
in the portlet window, when
- rendered, unless it is overridden programmatically.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para><literal>portlet-instances.xml</literal>
-<programlisting><![CDATA[<?xml version="1.0"
standalone="yes"?>
+</portlet-app>]]>
+</screen>
+ </para>
+ <para>
+ This file must adhere to its definition in the JSR-168 Portlet Specification. You may
define more than one portlet application in this file.
+ </para>
+ <para>
+ <variablelist>
+ <varlistentry><term><screen><![CDATA[
+<portlet-name>HelloWorldPortlet</portlet-name>]]></screen></term>
+<listitem>
+ <para>
+ Define the portlet name. It does not have to be the Class name.
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<portlet-class>org.jboss.portlet.hello.HelloWorldPortlet</portlet-class>]]></screen></term>
+<listitem>
+ <para>
+ The Fully Qualified Name (FQN) of your portlet class must be declared here.
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<supports>
+ <mime-type>text/html</mime-type>
+ <portlet-mode>VIEW</portlet-mode>
+</supports>]]></screen></term>
+<listitem>
+ <para>
+ The <literal><supports></literal> element allows you to
declare all the markup types your
+ portlet supports in the <literal>render</literal> method. This is
accomplished via the
+ <literal><mime-type></literal> element, which is required for
every portlet. The declared MIME types must match the capability of the portlet.
+ </para>
+ <para>
+ As well, it allows you to pair which modes and window states are supported for each
markup type. All portlets must support the VIEW portlet mode, so this does not have to be
decared. Define which markup type your porlet supports, which in this examepl is
<literal>text/html</literal>. This section tells the portal that it will only
output text and HTML, and that it only supports the VIEW mode.
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<portlet-info>
+ <title>HelloWorld Portlet</title>
+</portlet-info>]]></screen></term>
+<listitem>
+ <para>
+ When rendered, the portlet's title will be displayed as the header in the portlet
window, unless it is overridden programmatically. In this example, the title would be
<computeroutput>HelloWorld Portlet</computeroutput>.
+ </para>
+</listitem>
+</varlistentry>
+</variablelist>
+</para>
+<para>
+ The following is an example of the
<filename>HelloWorldPortlet/WEB-INF/portlet-instances.xml</filename> file:
+</para>
+<para>
+<screen><![CDATA[
+<?xml version="1.0" standalone="yes"?>
<!DOCTYPE deployments PUBLIC
"-//JBoss Portal//DTD Portlet Instances 2.6//EN"
"http://www.jboss.org/portal/dtd/portlet-instances_2_6.dtd">
@@ -343,17 +353,21 @@
<portlet-ref>HelloWorldPortlet</portlet-ref>
</instance>
</deployment>
-</deployments>]]></programlisting>
- This is a JBoss Portal specific descriptor that allows you to
create instances of portlets. The
- <literal>portlet-ref</literal> value must match the
<literal>portlet-name</literal> value
- given in the packaged <literal>portlet.xml</literal>.
The <literal>instance-id</literal>
- value can be named anything, but it must match
<literal>instance-ref</literal> values given
- in <literal>*-object.xml</literal> files as we shall
below.
- </para>
- </listitem>
- <listitem>
- <para><literal>helloworld-object.xml</literal>
-<programlisting><![CDATA[<?xml version="1.0"
encoding="UTF-8"?>
+</deployments>]]>
+</screen>
+</para>
+<para>
+ This is a JBoss Portal specific descriptor that allows you to create instances of
portlets. The
+ <literal><portlet-ref></literal> value must match the
<literal><portlet-name></literal> value
+ given in the <filename>HelloWorldPortlet/WEB-INF/portlet.xml</filename>
file. The <literal><instance-id></literal>
+ value can be named anything, but it must match the
<literal>instance-ref</literal> values given
+ in <literal>*-object.xml</literal> files as we shall below.
+</para>
+<para>
+ The following is an example <filename>helloworld-object.xml</filename>
file:
+</para>
+<para>
+<screen><![CDATA[<?xml version="1.0"
encoding="UTF-8"?>
<!DOCTYPE deployments PUBLIC
"-//JBoss Portal//DTD Portal Object 2.6//EN"
"http://www.jboss.org/portal/dtd/portal-object_2_6.dtd">
@@ -368,14 +382,18 @@
<height>1</height>
</window>
</deployment>
-</deployments>]]></programlisting>
+</deployments>]]>
+</screen>
+</para>
+<para>
+<literal>*-object.xml</literal> files are JBoss Portal specific descriptors
and allow users to
+define the structure of their portal instances as well as create/configure their windows
and
+pages. In our example, we create a portlet window, specify that it will display the
markup
+generated by the <literal>HelloWorldPortletInstance</literal> portlet
instance, assign it to the
+<literal>default.default</literal> page, and specify where it should appear
on that page.
+</para>
+<para>
- <literal>*-object.xml</literal> files are JBoss
Portal specific descriptors and allow users to
- define the structure of their portal instances as well as
create/configure their windows and
- pages. In our example, we create a portlet window, specify that
it will display the markup
- generated by the
<literal>HelloWorldPortletInstance</literal> portlet instance, assign it to
the
- <literal>default.default</literal> page, and specify
where it should appear on that page.
-
<itemizedlist>
<listitem>
<para>
@@ -418,9 +436,7 @@
</listitem>
</itemizedlist>
</para>
- </listitem>
- </itemizedlist>
- </para>
+
<para>
To illustrate the relationship between the descriptors, we have provided
this simple diagram
<mediaobject>
@@ -455,6 +471,8 @@
</window>
</deployment>
</deployments>]]></programlisting>
+</para>
+<para>
This declaration is equivalent to the previous example. We specify that
the content being displayed by
the <literal>HelloWorldPortletWindow</literal> is a
<literal>portlet</literal> content. The content URI
@@ -462,7 +480,7 @@
It is possible to declare windows with a
<literal>cms</literal> content type and use directly the path to
the file in the CMS to make the window show the content of the associated
file. That behavior is
pluggable and it is possible to plug virtually any kind of content.
- </para>
+ </para>
</sect3>
<sect3 id="first_portlet_build">
<title>Building your portlet</title>