Migration guide

Introduction

Ajax block has been recently adapted to use features that servlet services framework provides. For in-depth details of adoption process take a look at COCOON-1991 issue.

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 Your first Cocoon application using Maven 2.

Connecting servlets

First of all, in order to get access to the resources that Ajax 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 <servlet:context> tag:

<servlet:connections>
  <entry key="ajax" value-ref="org.apache.cocoon.ajax.impl.servlet"/>
</servlet:connections>

Links adjustments

Now you can reference resources with special servlet: scheme. For example, if you have following link to dojo.js:

<script type="text/javascript" src="${cocoon.request.contextPath}/_cocoon/resources/dojo/dojo.js"/>

You will have to change it into following form:

<script type="text/javascript" src="servlet:ajax:/resource/external/dojo/dojo.js"/>

Basically, replacing ${cocoon.request.contextPath}/_cocoon/resources/ and similar constructs with servlet:ajax:/resource/external/ should do the trick.

Sitemap adjustments

Naturally, browsers do not understand servlet: scheme and all links containing it should be rewritten before sent any content is sent to the browser. For this purpose, special servletLinkRewriter has been created. You have to put it in your pipeline near html serializer to be sure that it catches all links that need rewriting. Let's take as example pipeline from cocoon-ajax-sample:

<map:match pattern="*.html">
   <map:generate type="jx" src="{1}.xml"/>
   <map:call resource="simple-page2html"/>
   <map:transform type="servletLinkRewriter"/> <!-- this is transformation step you need to add -->
   <map:serialize type="html"/>
</map:match>

Revisiting all your rendering pipelines and adding transformer is last step of migration.

At the end, rebuild your block, clear browser's cache and test the changes. All should work as before migration.

See also

You may also be insterested in Forms migration guide.