http://magnolia-railo-demo.joshuafrankamp.com/

If anyone is interested in logging in, let me know and I will give you some credentials to log in and poke around.

For some reason, this is performing crazy fast right now. On the order of 100 ms, across the country network lag included, on an extremely underpowered rackspace cloud machine (256 megs of ram, running mysql, php, httpd, ngnix and tomcat for this app).

Turn on your firebug or chrome inspector and compare it to your CMS…

I defy any other pure Railo/CFML CMS from topping that for a single uncached hit with three custom cf paragraphs…

If you missed part one you’ll need to have read it and done all steps to get anything out of this.

Step One: Wipe out your repositories folder

We’re starting over with content, so at this point I am assuming you dont have anything in your website tree that is not replaceable. If you have something you want to keep, export it first. This is /repositories in the webroot by default, and is the location that magnolia has stored its derby database. Delete it.

Step Two: Get the magnolia-railo-sample files

Export some sample files and configuration with subversion.

svn export https://www.joshuafrankamp.com/svn/incubator/magnolia-railo-sample/trunk/ tempWebroot

Step Three: Merge the sample files

Copy the contents of tempWebRoot into your webroot, this will overwrite the two files we wrote last time, and add many more.

Step Four: Start up your container

Bootstrapping of the app will occur. While it does, lets go over some of the files that I have prepared for you in this sample.

1. Adding a template renderer
   1. config.modules.templating.template-renderers.cfm.xml
   2. This is required to bind the cfm type to a backing class. We will use the JSP renderer, because it is a dispatch model that is native to Railo since it is a web app.
2. Creating a template definition node, and backing cfm
   1. config.modules.templating.templates.sampleTemplate.xml
   2. template.cfm with some assets/ that it needs to render properly
   3. This is a specific template instance, that in a normal magnolia application would represent one of many template choices. For this example, we will create a simple template.
3. Creating a cf include paragraph definition, dialog, and backing cfm
   1. config.modules.templating.paragraphs.cf.xml
   2. config.modules.templating.dialogs.cf.xml
   3. cfinclude.cfm
4. Creating an example content style “Whats New” paragraph, dialog, and backing cfm
   1. config.modules.templating.paragraphs.whatsNew.xml
   2. config.modules.templating.dialogs.whatsNew.xml
   3. whatsnew.cfm
5. Creating a page dialog, this will be an editor for page level properties
   1. config.modules.templating.dialogs.page-properties.xml
6. Example Page
   1. website.index.xml
   2. This page uses the sampleTemplate, and pulls in the example paragraph types in paragraph instances that show them off.  It also allows access to the page properties dialog.
7. Magnolia Tag Libraries
   1. cms-taglib.tld
   2. These are typically in the magnolia jars, but we need them out where CF can get ahold of them.

Step Five: Hit /index

Magnolia will render the node at the path /index. Since this node is configured in the magnolia administrator to use the simpleTemplate template, it will include the definition of that template to render the page. The templatePath for simpleTemplate is /template.cfm which is a traditional CFML file on disk. At this point the standard Railo request lifecycle will start, including Application.cf(c|m). Then the file will execute, with one signifigant difference. The magnolia context has been set up, and some request scope variables have already been set for easy access to magnolia state information about the page.

A few notes about parts of the example template.cfm

• The tag libraries give simple access to magnolia controls and data structures. These allow you to render magnolia chrome inline in CFML.Example:

  <cfimport taglib="/tags/cms" prefix="cmsmod" />
  <cfimport taglib="/META-INF/cms-taglib.tld" prefix="cms" />

• There are three ways to read information from the content repository. The tag library, request scope context objects, and instantiation of singleton magnolia api objects. They all get the information from the same underlying jcr, but with varying levels of complexity and power.Example:

  <cms:setNode var="page" />...
  <title>#page['title']#</title>

  This pulls the properties from the current content node into a Java Map (struct) whose keys and values give you access to the properties. You can also get at the same information through request['state'] which the reader could dump out and traverse to find all kinds of wonderful things in the api

• Paragraphs are at the heart of everything in Magnolia. They are the single reason for having templates, is the content you want to put on them. By default, Magnolia dispatches the requests for paragraphs to paragraph handlers which in turn for Java technologies, dispatch them as includes through the web app container. This is the point of failure for a technology like Railo, because each request in Railo assumes that it is the beginning and end of that request. It tries to read multi part data on the inbound request, it tries to set headers and response sizes on the outbound response. That is problematic for paragraphs and a big sticking point in the integration between Railo and Magnolia, and it is also not a problem anymore!
  Fortunately, Railo includes its own custom tag concept, and it is simple to implement around the problem. Replacing container includes with calls in a reimplementation of (contrary to its name, this is the tag responsible for including paragraphs, not templates). Look for <cmsmod: includeTemplate /> custom tag calls, in a different namespace. That is the custom implementation of the <cms:includeTemplate /> that would have required going outside the current Railo request.Example:

  <div id="center">
  	<cms:contentNodeIterator contentNodeCollectionName="main">
  		<cmsmod:includeTemplate />
  	</cms:contentNodeIterator>
  	<cms:newBar contentNodeCollectionName="main" paragraph="cf,whatsNew" contentnodename="mgnlNew"/>
  	<hr />
  </div>

Until now.

This will be the first in a series of magnolia-railo merged app tutorials. Part one will walk through the merging of the two web apps into one. Part two shows how to enable Railo templating and explore the interaction between Magnolia and Railo. Part three is about the dark side, potential problems and workarounds.

Before we dive in, I will address the question “why should these two technologies be merged?” It is simple really. Magnolia is a superior CMS to anything offered in the CFML world, and has amazing interoperability with other technologies. Railo on the other hand, blows the pants off any of the native templating options available in Magnolia and its rapid and powerful tag based language easily unlocks the power of Magnolia’s Jackrabbit JCR. In short, they were made for each other.

Lets put these two together:

1. Download the latest railo custom all os war, extract to /merge-target. I’ll refer to this directory as the location of our new merged app, however you can name it what you wish.
2. Delete these files from /merge-target/WEB-INF/lib These files overlap with magnolia’s jars.
   1. apache-jakarta-commons-codec.jar
   2. apache-jakarta-commons-collections.jar
   3. apache-jakarta-commons-fileupload.jar
   4. apache-jakarta-commons-httpclient.jar
   5. apache-jakarta-commons-io.jar
   6. apache-jakarta-commons-lang.jar
   7. apache-jakarta-oro.jar
   8. apache-lucene.jar
   9. backport-util-concurrent.jar
   10. concurrent.jar
   11. PDFBox.jar
3. Download the latest railo patch (currently 3.1.2.006.rc). Put it in /merge-target/WEB-INF/lib/railo-server/patches/
4. Download Magnolia Community Edition war extract to /magnolia-temp
5. Copy /magnolia-temp/WEB-INF/lib/* to /merge-target/WEB-INF/lib/* There should be no file name conflicts.
6. Copy /magnolia-temp/WEB-INF/config to /merge-target/WEB-INF/config
7. Merge web.xmls. Use Magnolia’s xml header with namespaces! It doesn’t like anything else, because it reads it in at runtime. Here is the one I created:

   <?xml version="1.0" encoding="UTF-8"?>
   <web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4">
     <description>Magnolia</description>
     <display-name>magnolia</display-name>
   
     <distributable/>
     <filter>
       <display-name>Magnolia global filters</display-name>
       <filter-name>magnoliaFilterChain</filter-name>
       <filter-class>info.magnolia.cms.filters.MgnlMainFilter</filter-class>
     </filter>
     <filter-mapping>
       <filter-name>magnoliaFilterChain</filter-name>
       <url-pattern>/*</url-pattern>
       <dispatcher>REQUEST</dispatcher>
       <dispatcher>FORWARD</dispatcher>
       <dispatcher>ERROR</dispatcher>
     </filter-mapping>
     <listener>
       <listener-class>info.magnolia.cms.servlets.MgnlServletContextListener</listener-class>
     </listener>
   
   	<servlet>
   		<servlet-name>CFMLServlet</servlet-name>
   		<description>CFML runtime Engine</description>
   		<servlet-class>railo.loader.servlet.CFMLServlet</servlet-class>
   		<init-param>
   	      <param-name>configuration</param-name>
   	      <param-value>/WEB-INF/railo/</param-value>
   	      <description>Configuraton directory</description>
   	    </init-param>
   		<!-- init-param>
   	      <param-name>railo-server-root</param-name>
   	      <param-value>.</param-value>
   	      <description>directory where railo root directory is stored</description>
   	    </init-param -->
   		<load-on-startup>1</load-on-startup>
   	</servlet>
   	<servlet>
   		<servlet-name>AMFServlet</servlet-name>
   		<description>AMF Servlet for flash remoting</description>
   		<servlet-class>railo.loader.servlet.AMFServlet</servlet-class>
   		<load-on-startup>1</load-on-startup>
   	</servlet>
   	<servlet>
   		<servlet-name>FileServlet</servlet-name>
   		<description>File Servlet for simple files</description>
   		<servlet-class>railo.loader.servlet.FileServlet</servlet-class>
   		<load-on-startup>2</load-on-startup>
   	</servlet>	 
   
   	<servlet-mapping>
   		<servlet-name>CFMLServlet</servlet-name>
   		<url-pattern>*.cfm</url-pattern>
   	</servlet-mapping>
   	<servlet-mapping>
   		<servlet-name>CFMLServlet</servlet-name>
   		<url-pattern>*.cfml</url-pattern>
   	</servlet-mapping>
   	<servlet-mapping>
   		<servlet-name>CFMLServlet</servlet-name>
   		<url-pattern>*.cfc</url-pattern>
   	</servlet-mapping>
   	<servlet-mapping>
   		<servlet-name>AMFServlet</servlet-name>
   		<url-pattern>/flashservices/gateway/*</url-pattern>
   	</servlet-mapping>
   	<servlet-mapping>
   		<servlet-name>FileServlet</servlet-name>
   		<url-pattern>/</url-pattern>
   	</servlet-mapping> 
   
   <welcome-file-list>
   	  <welcome-file>index.cfm</welcome-file>
   	<welcome-file>index.cfml</welcome-file>
   </welcome-file-list>
   
   </web-app>

8. Create file /merge-target/WEB-INF/bootstrap/common/config.server.filters.bypasses.railo.xml

   <?xml version="1.0" encoding="UTF-8"?>
   <sv:node sv:name="railo" xmlns:sv="http://www.jcp.org/jcr/sv/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <sv:property sv:name="jcr:primaryType" sv:type="Name">
       <sv:value>mgnl:contentNode</sv:value>
     </sv:property>
     <sv:property sv:name="jcr:uuid" sv:type="String">
       <sv:value>11577b1a-3123-4cae-80a9-96c1cd5c27ad</sv:value>
     </sv:property>
     <sv:property sv:name="class" sv:type="String">
       <sv:value>info.magnolia.voting.voters.URIStartsWithVoter</sv:value>
     </sv:property>
     <sv:property sv:name="pattern" sv:type="String">
       <sv:value>/railo-context</sv:value>
     </sv:property>
     <sv:node sv:name="MetaData">
       <sv:property sv:name="jcr:primaryType" sv:type="Name">
         <sv:value>mgnl:metaData</sv:value>
       </sv:property>
       <sv:property sv:name="mgnl:activated" sv:type="Boolean">
         <sv:value>false</sv:value>
       </sv:property>
       <sv:property sv:name="mgnl:activatorid" sv:type="String">
         <sv:value>superuser</sv:value>
       </sv:property>
       <sv:property sv:name="mgnl:authorid" sv:type="String">
         <sv:value>superuser</sv:value>
       </sv:property>
       <sv:property sv:name="mgnl:creationdate" sv:type="Date">
         <sv:value>2007-04-25T18:23:31.784+02:00</sv:value>
       </sv:property>
       <sv:property sv:name="mgnl:lastaction" sv:type="Date">
         <sv:value>2007-05-02T17:00:15.025+02:00</sv:value>
       </sv:property>
       <sv:property sv:name="mgnl:lastmodified" sv:type="Date">
         <sv:value>2010-01-14T15:46:52.318-08:00</sv:value>
       </sv:property>
     </sv:node>
   </sv:node>

9. Set magnolia.update.auto=true in /WEB-INF/config/default/magnolia.properties
10. Start your container such as tomcat.
11. Go to /.magnolia, login superuser/superuser
12. Navigate to Configuration. server->filters->bypasses. You will see the railo node appears, in the configuration bypasses. If you inspect it you will see it is a uriStartsWithVoter that is configured with /railo-context. This node gives you bypassing of magnolia filters for any url starting with /railo-context.
13. Because of this you can hit /railo-context/admin/index.cfm and setup railo.

The bypass rule is required because Magnolia controls the url space with its chain of filters. You can right click on it and copy it to make another arbitrary bypass that is applied immediately. The filters are configurable and this gives you flexibility in fronting CFML apps with arbitrary urls configurable at runtime. At this point you can build anything you want using Magnolia’s built in templating. The bypasses allow you to run standalone CFML apps in the same JVM, under specified url paths (/myapp/*).

That is it for part one. The next article highlights how your templates and paragraphs can be built in standard CFML, and the interaction between Magnolia and Railo.

Today I ran into a weird bug in the cf admin api, if you attempt to perform a login such as this:

<cfscript>
loggedin = createObject(“component”,”cfide.adminapi.administrator”).login(‘dsafdsafsad’);
</cfscript>

It will bomb with the above error if your application name contains a space, the error is slightly different whether you use Application.cfc or <cfapplication> style.

The fix, thanks to Barney is to remove the space.