HomePortals/ColdBox Integration Revisited

A while ago I wrote a post about how to integrate the HomePortals layout rendering features into an a ColdBox application. Since then a lot has changed on both the HomePortals and ColdBox camps so I've been wanting to revisit that experiment and see if it could be made in an easier way now, using the advances on both frameworks. Read on for the findings.

The goal here is to have a fully functional ColdBox applications in which some pages are rendered using the HomePortals engine instead of the normal layout/view rendering of ColdBox.

To begin we need the following:

- ColdBox 3.0 Beta 2

- HomePortals 3.1.475 (or later)

Install both under /coldbox and /homePortals respectively (or using the appropriate CF mappings).

The application we will tackle will be 'simple' application template (this is found in the coldbox install directory).

Create a directory named hpcbox and copy in there the sample application template.

HomePortals works as a singleton, that means that we need to initialize and persist a single instance of it through out the application life. For this we will use the integrated model factory in ColdBox to manage our HomePortals instance. In ColdBox-speak we will need to add the HomePortals 'components' directory as an "external model location" in the main ColdBox config file.

/hpcbox/config/coldbox.xml.cfm

This will allow us to get an instance of any component under homePortals/components/ just by doing a getModel() call.

The next thing we need to do is create an event handler to serve the HomePortals page. Remember, what we want is to have both normal and homePortals-based pages living togehter on the same app.

Here is the listing for the event handler:

/hpcbox/handler/cms.cfc

Our handler has two methods only, the first is the preHandler() event that will execute for every request to any event on this handler, and the second is the onMissingAction() that will execute whenever coldbox cannot find a method definition for a requested action. Since we are not defining any other methods, pretty much the onMissingAction will be executed for every requested event on this handler.

The preHandler() method uses the ColdBox caching features to see if we have a cached instance of "homePortalsEngine". If not, then asks the model factory for a new instance of the HomePortals engine, initializes it with the path to the application and stores it in the cache. This is the homePortals singleton that we will use to render our pages.

Note To Any ColdBox Gurus out there: I wanted to have the model factory do the persistence and initialization for me but couldn't figure it out how to do it without making changes to the original component (homePortals.cfc). That is why I had to explicitly put my instance on the cache. If you have any tips they will be very welcome.

The onMissingAction() method is very simple, it only sets a value named "hp.page" on the request collection with the same name of the requested action, and then overrides the default layout to use a special layout that we named "Layout.HomePortals" which we will use to handle our homePortals rendering.

This way if we want to display a HomePortals page named "mysuperpage", all we need to do is make a request like:

http://localhost/hpcbox/index.cfm?event=cms.mysuperpage

Finally we need to do our custom layout:

/hpcbox/layouts/Layout.HomePortals.cfm

This couldn't be any simpler. We get our page name from the request collection ("hp.page"), get the HomePortals engine instance from the cache, and then tell HomePortals to render the HTML.

That's it for the ColdBox side of the equation, now we need to deal with HomePortals side.

First, we need to provide a config file for HomePortals. We do this by creating a file named homePortals-config.xml.cfm and placing it on the config/ directory of our app:

/hpcbox/config/homePortals-config.xml.cfm

Here we tell HomePortals that we will use the /hpcbox/pages directory to store our pages. Also we define a custom page template to handle the overall HTML structure. This is where we will indicate where to put the header, the sidebar, etc.

As you can see from the xml declaration the page template is just an HTML file. We put this file on the Layouts directory to keep the same ColdBox conventions, and also because both types of layouts fulfill the same goal (although with different implementation), which is to provide the top level structure or decoration of the page's main content.

Here is the template: /hpcbox/layouts/Layout.Page.htm:

It may not be obvious at first glance but this template follows the same HTML structure of the homepage of the original codbox application template that we used. It basically has a header, a main column for content and a sidebar.

Now for the last piece of the puzzle: the page to be displayed:

We already declared that our HomePortals pages will be stored on the /pages directory, and also that the page name is given by the event called on the handler. ColdBox uses the "index" event when no explicit event has been requested on a handler. So we will create a page named "index":

/hpcbox/pages/index.xml:

In this page we name our two content regions, and place a widget on each one. We use an RSS reader for the main content, and an image for the sidebar. Remember that these are part of the widgets that come standard with HomePortals. Here is an screenshot of the page:

Without much work ColdBox apps can benefit from a whole different set of reusable widgets provided by HomePortals. Additionally since the page was requested through a regular ColdBox event handler, you have all the ColdBox bells and whistles at your disposal.

Ok, that was good, but the integration so far is still not too tight. I mean, you have ColdBox views on one side, and HomePortals views on the other. So let's do something to make them become even more integrated.

Let's add ColdBox event requests as elements on a HomePortals page.

Ehhh... what? Let me explain, you saw how on the homePortals page we used the < rss > and < image > tags to display widgets or modules on the page, right? Well, a nice aspect of HomePortals is that you can write your own content tag renderers (that's what they are officially called). Then you can use your own renderers on your pages, move them around, call them multiple times, do whatever you want with them.

We will create a content tag renderer to encapsulate a ColdBox event handler request. So our tag will include an "event" attribute that will point to any ColdBox event action, it will then follow (almost) the same process lifecycle of a regular event and then display whatever view is set by the event. All encapsulated on the little space provided to the widget on the page. Moreover, we will be able to have multiple of these tag handlers on the same page, each one making independent requests from each other.

We will call our renderer "widgetEventHandler".

The code for the renderer is a bit more complicated, but basically it does the following:

• Extends "homePortals.components.contentTagRenderer" • Implements a method named "renderContent" • Replicates a customized version of the process coldbox follows when processing any event

Here is the code: Warning: ColdBox authors may have a heart attack just by looking at how I attrociously bastardized their pretty code :)

/hpcbox/widgetEventHandler.cfc

Finally we need to tell HomePortals about our new tag renderer. To do this we append the following section to our homePortals-config.xml.cfm file:

/hpcbox/config/homePortals-config.xml.cfm

And then we modify our index.xml page to use the new tag:

/hpcbox/pages/index.xml

Note that our widget tags are calling a new event handler named widgets. Which is defined as follows:

/hpcbox/handlers/widgets.cfc

I won't list the code for the views here but they are regular ColdBox views, using the normal ColdBox features available. You can find the entire code on the download at the end of this post.

So here is the final result:

So that's it. I showed how you can enrich your ColdBox applications using the layout and widget management features of the HomePortals framework. Take the time to explore the new HomePortals, I'm sure you will find some interesting features to improve your applications, especially when dealing with modular content.

Oh and more thing!

Once you have your app setup like this, why not throw a little CMS to manage your content without modifying your Coldbox site at all?

Stay tuned for more HomePortals integration on other frameworks too!

PS: You can find the sample app attached to this post.