cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From da...@cocoon.zones.apache.org
Subject [DAISY] Created: Migration guide
Date Tue, 10 Apr 2007 14:52:35 GMT
A new document has been created.

http://cocoon.zones.apache.org/daisy/documentation/1351.html

Document ID: 1351
Branch: main
Language: default
Name: Migration guide
Document Type: Cocoon Document
Created: 4/10/07 2:52:16 PM
Creator (owner): Grzegorz Kossakowski
State: publish

Parts
=====

Content
-------
Mime type: text/xml
Size: 7302 bytes
Content:
<html>
<body>

<h1>Introduction</h1>

<p>Forms block has been recently adapted to use features that servlet services
framework provides. For in-depth details of adoption process take a look at
<a href="http://issues.apache.org/jira/browse/COCOON-1991">COCOON-1991</a>
issue.</p>

<p>Here you'll find description of migration process which should be easy and
straightforward. It is assumed that you already have proper block structure
created with archetype, see <a href="daisy:1159">Your first Cocoon application
using Maven 2</a>.</p>

<h2>Connecting servlets</h2>

<p>First of all, in order to get access to the resources that Forms block makes
available you need to create a connection to its servlet. Open
src/main/resources/META-INF/cocoon/spring/servlet-service.xml for edition and
put this configuration inside <tt>&lt;servlet:context&gt;</tt> tag:</p>

<pre>&lt;servlet:connections&gt;
  &lt;servlet:connections&gt;
    &lt;entry key="ajax" value-ref="org.apache.cocoon.ajax.impl.servlet"/&gt;
    &lt;entry key="forms" value-ref="org.apache.cocoon.forms.impl.servlet"/&gt;
  &lt;/servlet:connections&gt;
&lt;/servlet:connections&gt;

</pre>

<h2>Correcting links and paths</h2>

<p>You will need to perform massive find-and-replace operation multiple times.
Previously, all external (available to the browser) resources were loaded with
special <tt>_cocoon/**</tt> matcher and internal resources (like XSL files) were
loaded with <tt>resource://</tt> scheme. Both are now considered as bad
practice.<br/>
Special, global matcher cannot be easily provided in real blocks environment
because it does not support concepts like block's polymorphism and makes Cocoon
more monolithic. Loading resources of other block with <tt>resource:</tt> is
also discouraged because resources location within block <strong>is not part of
any block's contract</strong>. Only resources that are available with servlet:
scheme are part of block's contract and should not change without significant
reasoning.</p>

<p>Now you will see list of couple old and new paths/links. Performing normal
find-and-replace operation on your block that you are migrating should be
enough. Here is the list:</p>

<pre>resource://org/apache/cocoon/forms/flow/javascript/Form.js
servlet:forms:/system/flow/javascript/Form.js

resource://org/apache/cocoon/forms/generation/jx-macros.xml
servlet:forms:/resource/internal/generation/jx-macros.xml

resource://org/apache/cocoon/forms/system/i18n
servlet:forms:/resource/internal/i18n

resource://org/apache/cocoon/forms/resources/forms-page-styling.xsl
servlet:forms:/resource/internal/xsl/forms-page-styling.xsl

resource://org/apache/cocoon/forms/resources/forms-advanced-field-styling.xsl
servlet:forms:/resource/internal/xsl/forms-advanced-field-styling.xsl
</pre>

<h2>forms-samples-styling.xsl</h2>

<p>If you use forms-samples-styling.xsl for transforming your Forms into HTML
code you will have to update it to newer version. Important change (apart from
modified paths mentioned above) is that you should replace this fragment:</p>

<pre>&lt;!-- Location of the resources directory, where JS libs and icons are stored
--&gt;
&lt;xsl:param name="resources-uri"&gt;resources&lt;/xsl:param&gt;
</pre>

<p>with this one:</p>

<pre>&lt;!-- Location of the resources directories, where JS libs and icons are
stored --&gt;
&lt;xsl:param name="dojo-resources"/&gt;
&lt;xsl:param name="forms-resources"/&gt;
</pre>

<h2>Sitemap adjustments</h2>

<p>Obviously, you have to adjust your sitemap too to pass new parameters:</p>

<pre>&lt;map:transform src="resources/forms-samples-styling.xsl"&gt;
  &lt;map:parameter name="resources-uri" value="{request:contextPath}/_cocoon/resources"/&gt;
&lt;/map:transform&gt;
</pre>

<p>should be replaced with:</p>

<pre>&lt;map:transform src="resources/forms-samples-styling.xsl"&gt;
  &lt;map:parameter name="dojo-resources" value="servlet:ajax:/resources/dojo"/&gt;
  &lt;map:parameter name="forms-resources" value="servlet:forms:/resources/forms"/&gt;
&lt;/map:transform&gt;
</pre>

<p>Of course you may have little bit different configuration. Above fragments
are mentioned for explanatory purpose.</p>

<p>Links with in <tt>servlet:</tt> scheme cannot be included in HTML code
sent
to the browser thus you need to perform link rewriting step just before
serialization. In order to do that, you will need to add
<tt>servletLinkRewriting</tt> transformer as shown in this example:</p>

<pre>     &lt;map:match pattern="*-display-pipeline.jx"&gt;
       &lt;map:generate type="jx" src="forms/{1}_template.xml" label="content1"&gt;
         &lt;map:parameter name="locale" value="{flow-attribute:locale}"/&gt;
       &lt;/map:generate&gt;
       &lt;map:transform type="browser-update"/&gt;&lt;!-- AJAX-style form update
--&gt;
       &lt;map:transform type="i18n"&gt;
         &lt;map:parameter name="locale" value="{flow-attribute:locale}"/&gt;
       &lt;/map:transform&gt;
       &lt;map:call resource="simple-page2html"&gt;
         &lt;map:parameter name="file" value="forms/{1}_template.xml"/&gt;
       &lt;/map:call&gt;
       &lt;map:transform src="resources/forms-samples-styling.xsl"&gt;
         &lt;map:parameter name="dojo-resources" value="{servlet:ajax:/resources/dojo}"/&gt;
         &lt;map:parameter name="forms-resources" value="{servlet:forms:/resources/forms}"/&gt;
         &lt;map:parameter name="dojo-debug" value="true"/&gt;&lt;!-- set to true
to turn on dojo debugging in the Browser --&gt;
         &lt;map:parameter name="dojo-locale" value="{flow-attr:locale}"/&gt;
       &lt;/map:transform&gt;
       &lt;map:transform type="i18n"&gt;
         &lt;map:parameter name="locale" value="{flow-attribute:locale}"/&gt;
       &lt;/map:transform&gt;

       &lt;map:transform type="servletLinkRewriting"/&gt; &lt;!-- here is the
transformation step you will need to add --&gt;

       &lt;map:select type="ajax-request"&gt;
         &lt;map:when test="true"&gt;&lt;!-- sending a partial Browser Update
--&gt;
            &lt;map:select type="request-parameter"&gt;
              &lt;map:parameter name="parameter-name" value="dojo.transport"/&gt;
              &lt;map:when test="iframe"&gt;&lt;!-- sending BU via iFrameIO --&gt;
                &lt;map:transform src="resource://org/apache/cocoon/forms/resources/IframeTransport-bu-styling.xsl"/&gt;
                &lt;map:serialize type="xhtml"/&gt;&lt;!-- this is REALLY important
--&gt;
              &lt;/map:when&gt;
              &lt;map:otherwise&gt;&lt;!-- sending BU via XHR --&gt;
                &lt;map:serialize type="xml"/&gt;
              &lt;/map:otherwise&gt;
            &lt;/map:select&gt;
         &lt;/map:when&gt;
         &lt;map:otherwise&gt;&lt;!-- sending a complete page --&gt;
           &lt;map:serialize type="html"/&gt;
         &lt;/map:otherwise&gt;
       &lt;/map:select&gt;
     &lt;/map:match&gt;
</pre>

<p>You should add that transformer to all pipelines that transform Forms code
into HTML.</p>

<p>Also, this is last step of whole migration process. After performing all
steps you need to rebuild your block and clear browser cache to get everything
working as before refactoring and migration process.</p>

<h2>See also</h2>

<p>You may also be interested with <a href="daisy:1350">AJAX migration
guide</a>.</p>

</body>
</html>

Collections
===========
The document belongs to the following collections: cdocs-forms

Mime
View raw message