Author: julien(a)jboss.com
Date: 2007-03-21 11:36:51 -0400 (Wed, 21 Mar 2007)
New Revision: 6788
Modified:
docs/trunk/referenceGuide/en/modules/contentIntegration.xml
Log:
started to write content integration doc
Modified: docs/trunk/referenceGuide/en/modules/contentIntegration.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/contentIntegration.xml 2007-03-21 12:10:57 UTC
(rev 6787)
+++ docs/trunk/referenceGuide/en/modules/contentIntegration.xml 2007-03-21 15:36:51 UTC
(rev 6788)
@@ -7,6 +7,132 @@
<email>julien @ jboss dot com</email>
</author>
</chapterinfo>
- <title>Content integration</title>
- <para>Blah.</para>
+ <title>Content Integration</title>
+ <para>Since JBoss Portal 2.6 it is possible to provide easy integration of
content within the portal. Up to the 2.4 version
+ content integration had to be done by configuring a portlet to show some content from
an URI and then place that
+ portlet on a page. The new content integration capabilities allows to directly
configure a page window with the content URI
+ removing the need to configure a portlet for that purpose. It is important here to
note that we do not advocate to
+ not use portlet preferences but rather we advocate the configuration of content to be
managed at the portal level.</para>
+ <sect1>
+ <title>Window content</title>
+ <para>The content of a window is defined by
+ <itemizedlist>
+ <listitem>The content URI which is the resource that the window is
pointing to. It is an arbitrary string that
+ the portal cannot interpret and is left up to the content provider to
interpret.</listitem>
+ <listitem>The window content type which defines how the portal
interpret the window content
+ <itemizedlist>
+ <listitem>The default content type is for portlets and has the
value <emphasis>portlet</emphasis>. For that
+ content type, the content URI is the portlet instance
id.</listitem>
+ <listitem>The CMS content type allows to integrate content from
the CMS at the page and it has the value
+ <emphasis>cms</emphasis>. For that content type, the
content URI is the CMS file path.</listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>The content parameters which is a set of additional key/value
string pairs holding state that is interpreted
+ by the content provider.</listitem>
+ </itemizedlist>
+ </para>
+ <para>At runtime when the portal needs to render a window it delegates the
production of markup to a content provider.
+ The portal comes with a preconfigured set of providers which handles the portlet
and the cms content types. The most
+ natural way to plug a content provider in the portal is to use a JSR 168 Portlet.
Based on a few carefully chosen conventions
+ it is possible to provide an efficient content integration with the benefit of
using standards and without requiring
+ the usage of a proprietary API.</para>
+ </sect1>
+ <sect1>
+ <title>Content customization</title>
+ <para>Content providers must be able to allow the user or administrator to
chose content from the external resource
+ it integrates in the portal in order to properly configure a portal window. A few
interactions between the portal, the content
+ provider and the portal user are necessary to achieve that goal. Here again it is
possible to provide content
+ customization using a JSR 168 Portlet. For that purpose a special portlet mode
called
+ <emphasis>edit_content</emphasis> has been introduced. It signals to
the portlet that it is editing the content portion
+ of the state of a portlet. The traditional edit mode is not used because the edit
mode is more targetted to configure how
+ the portlet show content to the end user rather than what content it
shows.</para>
+ </sect1>
+ <sect1>
+ <title>Content Driven Portlet</title>
+ <para>Portlet components are used to integrate content in the portal. It
relies on a few conventions which allow
+ the portal and the portlet to communicate between each other.
+ </para>
+ <sect2>
+ <title>Displaying content</title>
+ <para>At runtime the portal will call the portlet with the view mode when
it displays content. It will send to the
+ portlet the information about the content to display using the render
parameters. Therefore the portlet has
+ just to read the render parameters and use them to properly display the content
in the portlet. The render parameters
+ values are the key/value pairs that forms the content properties and the
resource URI is found under the <emphasis>uri</emphasis>
+ parameter name.</para>
+ </sect2>
+ <sect2>
+ <title>Configuring content</title>
+ <para>As explained before, the portal will call the portlet using the
<emphasis>edit_content</emphasis> mode.
+ In that mode the portlet and the portal will communicate using either action or
render parameters. We have two use cases
+ which are:
+ <itemizedlist>
+ <listitem>The portal needs to configure a new content item. In that
use case the portal will not send special
+ render parameters to the portlet and the initial set of render parameters
will be empty. The portlet can
+ then use render parameters in order to provide navigation in the content
repository. For example the portlet
+ can navigate the CMS tree and store the current CMS path in the render
parameters. Whenever the portlet has decided
+ to tell the portal that content has been selected by the user it needs to
use an action URL with a special set of
+ parameters:
+ <itemizedlist>
+
<listitem><emphasis>content.action.select</emphasis> equals to any
value</listitem>
+ <listitem><emphasis>content.uri</emphasis> equals
to the content URI</listitem>
+ <listitem><emphasis>content.param.</emphasis> used
as prefix to configure content parameters</listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>The second use case arises when the portal needs to edit
existing content. In such situation
+ everything works as explained before except that the initial set of render
parameters of the portlet
+ will be prepopulated with the content uri URI and
parameters.</listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+ <sect2>
+ <title>Example</title>
+ <para></para>
+ <programlisting><![CDATA[
+
+public class FileContentPortlet extends GenericPortlet
+{
+
+ public static final PortletMode EDIT_CONTENT_MODE = new
PortletMode("edit_content");
+
+ /**
+ * Additional dispatch for the edit content mode.
+ */
+ protected void doDispatch(RenderRequest req, RenderResponse resp) throws
PortletException, PortletSecurityException, IOException
+ {
+ if (EDIT_CONTENT.equals(req.getPortletMode()))
+ {
+ doEditContent(req, resp);
+ }
+ else
+ {
+ super.doDispatch(req, resp);
+ }
+ }
+
+ protected void doEditContent(RenderRequest req, RenderResponse resp) throws
PortletException, PortletSecurityException, IOException
+ {
+ // Get the uri value either provided by the portal or by ourself
+ String uri = req.getParameter("content.uri");
+ File root = null;
+ if (uri == null)
+ {
+ root = "/";
+ }
+ else
+ {
+ root = new File(uri).getParentFile().getCanonicalPath();
+ }
+
+ // Get the children of the selected file
+ File fic = new File(uri);
+ File[] children = fic.listFiles();
+
+ }
+
+
+}
+
+]]></programlisting>
+ </sect2>
+ </sect1>
</chapter>
Show replies by date