[portal-commits] JBoss Portal SVN: r6788 - docs/trunk/referenceGuide/en/modules.

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>