Author: julien(a)jboss.com Date: 2008-03-03 06:43:50 -0500 (Mon, 03 Mar 2008) New Revision: 10180 Modified: modules/portlet/trunk/docs/user-guide/en/modules/simpleportal.xml modules/portlet/trunk/pom.xml modules/portlet/trunk/portal/src/main/resources/simple-portal-war/WEB-INF/tags/portal/portlet.tag Log: more work on the 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 10:26:54 UTC (rev 10179) +++ modules/portlet/trunk/docs/user-guide/en/modules/simpleportal.xml 2008-03-03 11:43:50 UTC (rev 10180) @@ -6,6 +6,11 @@ <surname>Viet</surname> <email&gt;julien(a)jboss.org&lt;/email&gt; </author> + <author> + <firstname>Chris</firstname> + <surname>Laprun</surname> + <email&gt;chris.laprun(a)jboss.com&lt;/email&gt; + </author> </chapterinfo> <title>Simple Portal</title> <sect1> @@ -44,7 +49,7 @@ 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 <file>web.xml</file> file of its portlet application.</para> + 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 @@ -55,35 +60,94 @@ </itemizedlist> </sect2> <sect2> - <title>Page creation</title> + <title>The portal tag library</title> <para>The simple portal relies on the JSP technology to build pages for several good reasons:</para> <itemizedlist> - <listitem>JSPs are good enough technology for building portal pages. If you think about what - a portal page is, you'll realize that JSP is sufficient. Obviously this does not mean that + <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 JSP.</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> </itemizedlist> - <page>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 fullfill your needs.</page> + <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> + <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[ +todo +]]></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> + <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. + <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 + 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> + 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> + </sect3> + <sect3> + <title>Page headers</title> + <para>todo</para> + </sect3> + <sect3> + <title>Portlet title</title> + <para>todo</para> + </sect3> + <sect3> + <title>Portlet controls</title> + <para>todo</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> + </sect3> + <sect3> + <title>Public render parameters</title> + <para>todo</para> + </sect3> </sect2> <sect2> - <title>Portlet coordination</title> + <title>Extended tag library</title> + <para>todo</para> </sect2> </sect1> <sect1> - <title>Debugging</title> + <title>Portlet debugging</title> </sect1> <sect1> <title>Administration</title> </sect1> <sect1> - <title>Extension</title> + <title>Extensions</title> <para>Talk about mixing JSP with templating framework or other taglib</para> </sect1> </chapter> Modified: modules/portlet/trunk/pom.xml =================================================================== --- modules/portlet/trunk/pom.xml 2008-03-03 10:26:54 UTC (rev 10179) +++ modules/portlet/trunk/pom.xml 2008-03-03 11:43:50 UTC (rev 10180) @@ -40,6 +40,7 @@ <module>test</module> <module>portal</module> <module>samples</module> + <module>docs</module> </modules> <activation> <activeByDefault>true</activeByDefault> Modified: modules/portlet/trunk/portal/src/main/resources/simple-portal-war/WEB-INF/tags/portal/portlet.tag =================================================================== --- modules/portlet/trunk/portal/src/main/resources/simple-portal-war/WEB-INF/tags/portal/portlet.tag 2008-03-03 10:26:54 UTC (rev 10179) +++ modules/portlet/trunk/portal/src/main/resources/simple-portal-war/WEB-INF/tags/portal/portlet.tag 2008-03-03 11:43:50 UTC (rev 10180) @@ -12,7 +12,7 @@ <div class="header full-width"> <div class="header-layer full-width"> <div class="title two-third-width float-left"><h2><portal:portlettitle/></h2></div> - <div class="controls third-width float-right"> + <div class="controls third-width float-right"> < <span class="mode-button"> <a href="<portal:portleturl windowState='maximized'/>"><img src="${pageContext.request.contextPath}/images/icon-maximize.gif" alt=""/></a>