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><servlet:context></tt> tag:</p> <pre><servlet:connections> <servlet:connections> <entry key="ajax" value-ref="org.apache.cocoon.ajax.impl.servlet"/> <entry key="forms" value-ref="org.apache.cocoon.forms.impl.servlet"/> </servlet:connections> </servlet:connections> </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><!-- Location of the resources directory, where JS libs and icons are stored --> <xsl:param name="resources-uri">resources</xsl:param> </pre> <p>with this one:</p> <pre><!-- Location of the resources directories, where JS libs and icons are stored --> <xsl:param name="dojo-resources"/> <xsl:param name="forms-resources"/> </pre> <h2>Sitemap adjustments</h2> <p>Obviously, you have to adjust your sitemap too to pass new parameters:</p> <pre><map:transform src="resources/forms-samples-styling.xsl"> <map:parameter name="resources-uri" value="{request:contextPath}/_cocoon/resources"/> </map:transform> </pre> <p>should be replaced with:</p> <pre><map:transform src="resources/forms-samples-styling.xsl"> <map:parameter name="dojo-resources" value="servlet:ajax:/resources/dojo"/> <map:parameter name="forms-resources" value="servlet:forms:/resources/forms"/> </map:transform> </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> <map:match pattern="*-display-pipeline.jx"> <map:generate type="jx" src="forms/{1}_template.xml" label="content1"> <map:parameter name="locale" value="{flow-attribute:locale}"/> </map:generate> <map:transform type="browser-update"/><!-- AJAX-style form update --> <map:transform type="i18n"> <map:parameter name="locale" value="{flow-attribute:locale}"/> </map:transform> <map:call resource="simple-page2html"> <map:parameter name="file" value="forms/{1}_template.xml"/> </map:call> <map:transform src="resources/forms-samples-styling.xsl"> <map:parameter name="dojo-resources" value="{servlet:ajax:/resources/dojo}"/> <map:parameter name="forms-resources" value="{servlet:forms:/resources/forms}"/> <map:parameter name="dojo-debug" value="true"/><!-- set to true to turn on dojo debugging in the Browser --> <map:parameter name="dojo-locale" value="{flow-attr:locale}"/> </map:transform> <map:transform type="i18n"> <map:parameter name="locale" value="{flow-attribute:locale}"/> </map:transform> <map:transform type="servletLinkRewriting"/> <!-- here is the transformation step you will need to add --> <map:select type="ajax-request"> <map:when test="true"><!-- sending a partial Browser Update --> <map:select type="request-parameter"> <map:parameter name="parameter-name" value="dojo.transport"/> <map:when test="iframe"><!-- sending BU via iFrameIO --> <map:transform src="resource://org/apache/cocoon/forms/resources/IframeTransport-bu-styling.xsl"/> <map:serialize type="xhtml"/><!-- this is REALLY important --> </map:when> <map:otherwise><!-- sending BU via XHR --> <map:serialize type="xml"/> </map:otherwise> </map:select> </map:when> <map:otherwise><!-- sending a complete page --> <map:serialize type="html"/> </map:otherwise> </map:select> </map:match> </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
