I've mentioned before how impressed I am with Sava, an open source ColdFusion CMS released by Blue River Interactive. In my spare time, I've been tinkering with it quite a bit, but now I am really looking forward to an upcoming project in which I will be knee-deep in Sava.
One of the cool things about Sava is how it's been designed to be extended and integrated with third party code. For example, in the content editor, a developer is able to include custom ColdFusion code simply by putting it between [sava][/sava] tags. The [sava] tag can even be used to integrate entire front-controller applications. The Sava download comes with Fusebox and Model-Glue skeleton applications. So simply putting this snippet in the content editor of a page will bring up the "Model-Glue is running!" default home page when you navigate to that page:
The path that is passed into the dspInclude() function is the location of the index.cfm file of the skeleton M-G app and is relative the the "includes" folder within the particular site folder that you are working with (Sava CMS is capable of managing multiple sites per install and each site has its own folder within the Sava webroot). Like I metioned before, ANY front controller application in which all requests go through a single "entry" .cfm file can be integrated this way. The only caveat to this is that the applicaton in question can't require Application.cfc. This was kind of a bummer for me because, as anyone who has read this blog before knows, I'm partial to the ColdBox framework, which actually DOES require Application.cfc. ....or so I thought. After getting some guidance from Mr. ColdBox, Luis Majano, here is how I was able to make a skeleton ColdBox application that you can use to integrate CB apps with Sava.
First, download and install Sava CMS. These instructions I'm describing here are for "Sava Standard", not the "Express" version. The current version is 5.0584. I'll be working with the "default" site in Sava. Normally you don't want to use the default site when you are developing a new Sava site, because the CMS uses it as a template when you add new sites. But because of that, by setting up a ColdBox skeleton application in the default site, it will be available to me in all new sites that I set up.
Then download the latest stable release of the ColdBox framework (version 2.6.1) and expand the zip file. We will be using the "system" and "ApplicationTemplate" directories.
There is a "requirements" directory in the web root of your Sava install. Create a directory named "coldbox" within that directory. Put the "system" folder from the ColdBox download into "requirements/coldbox/".
Open the "config/applicationSettings.cfm" file (relative from the Sava root). Go to the bottom of the file where the mappings are set up and add this line:
Get the "ApplicationTemplate" directory from the ColdBox download and place it wihin this directory of your Sava installation: "default/includes/display_objects/custom/". Rename the "ApplicationTemplate" directory to "coldboxtemplate".
Delete "Application.cfc" from within the "coldboxtemplate" directory.
Open the "index.cfm" file within the "coldboxtemplate" directory and add the following line at the bottom:
Now, open this file "requirements/coldbox/system/coldbox.cfm". After the header comments, you'll see this line:
Replace that line with this:
Just keep in mind that if you rename the coldboxtemplate directory when you use it to build a module, you'll have to make the corresponding change to the config path above.
We're almost there. There's one more change we have to make. Because both Sava and ColdBox use SES urls, you can get weird results if you include a ColdBox app within a Sava page at this point. I'm currently experimenting with ways you can make them work together (and will probably write a follow up blog post about it), but for now to make things simple we'll disable the SES interceptor in ColdBox. Go to your ColdBox routes config file: "default/includes/display_objects/custom/coldboxtemplate/config/routes.cfm". After the header comments, change the line so it reads:
Now let's get this ColdBox template to show up. From within the Sava admin, click on "Site Manager" from the left side menu and add a page (see instructions here for adding a page). Make sure you enter a title and add the following line in the wysiwig content editor:
Navigate to the frontend of the site and click on the link of the page you just added. You should see this:
If you view the source of this page, you'll see that the included ColdBox page is a complete html page, so you'll have <html> tags from the ColdBox page nested within the <html> tags of the Sava page. To address this you'll either want to modify your ColdBox layout files and strip them down to maybe <div> tags surrounding your ColdBox views or just omit your ColdBox layouts altogether. For all you ColdBox newbies, I'll refer you to the ample ColdBox docs on this subject.
And there you have it. Now you can integrate your ColdBox applications within Sava! Cool.
UPDATE
After posting this, I realized I left out a step and I also wanted to change one of the instructions.
In the ColdBox config file (/default/includes/display_objects/custom/coldboxtemplate/config/coldbox.xml.cfm), you have to explicitly set the "AppMapping" setting. So make sure you have the following line included within the "Settings" element:
(As before, if you change the name of your coldboxtemplate directory, you'll have to modify this line to reflect that change. Also when you set up a new Sava site, replace "default" with the siteID of your site, which will also be the name of the generated subfolder containing the site files).
One of my instructions above was to set the COLDBOX_CONFIG_FILE variable in the /requirements/coldbox/system/coldbox.cfm file. If you're only integrating a single ColdBox app, it's fine to leave it that way. But if you anticipate that you'll have multiple CB apps it would be better not to designate the path to the config file within the framework core files or else all of your coldbox applications will use the same configuration file. So instead, just cut out that line and designate the COLDBOX_CONFIG_FILE variable in the local index.cfm file of your ColdBox application, right above the line which includes the coldbox.cfm. So your /default/includes/display_objects/custom/coldboxtemplate/index.cfm file should contain these lines:
That should be it. Now you can designate the path to the config file for each application. If something wasn't clear, ask away.
Nov 22, 2008 at 10:30 PM That's awesome! Thanks for figuring that out and sharing.
Nov 23, 2008 at 6:25 AM I have been using Sava CMS for a little while and must say its very customisable as you just proved. thanks for the write up :)
Nov 23, 2008 at 7:37 PM Hey Tony, thanks for posting this... From your POV, do you think it would be challenging to configure Sava as a plugin for another framework like ColdBox or the onTap framework as opposed to the other way around? I may be a bit confused here, but it kind of sounds like the way Sava is designed, it sort of insists that the application framework be part of the site or site template for the CMS versus having the CMS as an integrated component within an application framework. I'd been thinking about creating a CMS plugin for the onTap framework though and am wondering if it might make more sense to just build a plugin for an existing tool. :)
Nov 24, 2008 at 4:47 AM Hi Isaac,
I think you're right -- Sava seems to be designed to bring in other apps as subapplications rather than be a subapplication itself. To be completely honest, though, I haven't really dug into the Sava architecture too much yet. I do know that the Sava admin uses Fusebox, ColdSpring and Reactor.
I definitely think that trying to configure Sava as a plugin would be worthwhile to look into at least. I would start by posing the question in their forums.
Nov 24, 2008 at 12:10 PM so thats allows you to use the ColdBox framework in pages created by Sava, cool, do you think it would be as simple to use ColdBox for the layout of the whole front end?
at the moment you would still need to style the layout in the standard way and not via ColdBox, you could only use the layout and views of ColdBox inside the Display Regions of Sava, am i right?
Nov 24, 2008 at 12:49 PM @Glyn,
That's right. I've just started working with this integration (and I'm not exactly a Sava expert yet either), but at this point you're still laying out your Sava templates and then your ColdBox layouts and views are included within those.
That said, I don't think there's much stopping you from using ColdBox for 'the whole front end'. Since Sava allows you to designate a template for each page, I imagine you could have a template in Sava that is just a blank page and then use the CB layouts and views to construct your entire page. (I haven't tried this myself though). Although, to keep the layout of the site consistent, I'd be inclined to use a Sava template throughout my site for both ColdBox and non-ColdBox pages. (unless, of course there is a specific reason for not doing that)
Nov 24, 2008 at 1:21 PM very good idea about using the blank page that would be the easiest way to do it. the fusebox admin part of Sava does cover most of the ColdBox stuff such as caching etc so your right it would be easy to replace but not much point unless your replacing the whole thing as important backend stuff such as app reload caching etc would all have to be rewritten from fusebox to CB. I like the idea of what you have done with just doing it in the pages, this way i can use all the CB goodies. again thanks for the write up.
Mar 9, 2009 at 6:50 AM I tried to follow your instructions to install ColdBox on Sava, the only difference I used the last version of ColdBox 2.63
When I run the page which is supposed to run ColdBox (http://www.giampierobonifazi.info/index.cfm/lab/demos/welcome-to-coldbox/) I receive this error:
Element CBCONTROLLER is undefined in a Java object of type class [Ljava.lang.String;
I do not know if it's a ColdBox or Sava Error
Any help would be appreciate
Thanks
Giampiero
Mar 10, 2009 at 5:21 AM (Following my message above) Now (without any modification) the error I have is 'Config File could not be located: config/environments.xml.cfm. Please check again.' Any suggestions?
Mar 10, 2009 at 7:28 AM Giampiero,
in the Interceptors section of your coldbox config file (/[siteid]/includes/display_objects/custom/coldboxtemplate/config/coldbox.xml.cfm), try this for the <property> tag where you declare your environmentControl interceptor:
<Property name='configfile'>/[siteid]/includes/display_objects/custom/coldboxtemplate/config/environments.xml.cfm</Property>
Of course replace '[siteid]' with your real site directory name.
Mar 10, 2009 at 9:20 AM It works! thanks Tony :-)
This is the right and permanent link to my demo page site running ColdBox:
http://www.giampierobonifazi.info/index.cfm/lab/demos/welcome-to-coldbox/
Mar 10, 2009 at 9:22 AM Awesome! Glad I could help!
Mar 11, 2009 at 7:10 PM Greetings,
I've been looking into Sava for a non-profit I work for. Not a developer, just a jack-of-all-trades Web person. We have a number of custom CF applications which each have their own application.cfc as well as some legacy .asp apps that we won't be modifying at least for now.
I'd like to be able to have a page that is managed by Sava in which a legacy app can run in. There doesn't need to be any interaction between the CMS and the application at all, just want the page shell for navigation and SEO ability with a "window" for the legacy app. Is this possible? Thanks!
-Brian
Mar 11, 2009 at 9:02 PM @Brimard,
Sava has a couple of built-in ways of including third-party applications within pages. One is to use the [sava] tags with the dspInclude() function (the same technique that is used to include framework code as described in this blog post). You can also now develop plugins to do this. The only thing that might trip you up is that the included apps can't have their own Application.cfc. So you might want to convert them to use Application.cfm.<br />
I suppose another possibility would be to use good ol' fashioned iframes. You could put the code for an iframe to your external app into a Sava component and then insert that into your page.
Mar 26, 2009 at 12:44 PM @Giampiero,
I just remembered that you can dynamically set your config settings using ${} notation. So this should also work for your environmentControl interceptor property:
<Property name="configfile">/${AppMapping}/config/environments.xml.cfm</Property>
This way seems a lot cleaner to me.
Mar 26, 2009 at 2:59 PM @Tony
Yes, thanks for the tip. I just tried and it works. It's a lot cleaner.
(Please, can you remove or change in http://www.giampierobonifazi.info/index.cfm/lab/demos/welcome-to-coldbox/ the link from my comment 8. it just pointed to a wrong page)
Jul 1, 2009 at 11:01 AM Hi,
great post.
I have this issue. Coldbox looks like is not able to find handlers folder:
Error Type: Framework.loaderService.HandlersDirectoryNotFoundException : [N/A]
Error Messages: The handlers directory: C:\inetpub\wwwroot\mura\requirements\mura\default\handlers does not exist please check your application structure or your Application Mapping.
Any suggestion??
Andrea
Jul 11, 2009 at 1:45 AM Hi Andrea,
Sorry for not replying sooner. I must've missed the notification. That's wierd that ColdBox is looking for the handlers directory in the Mura folder. Did you configure the AppMapping setting as I described?
Sep 18, 2010 at 12:12 PM Has anyone used colbox to manage mura? I want to write a coldbox app that will allow my coldbox users to create a site in a mura install.
Oct 6, 2010 at 3:00 PM I'm trying to do this and getting:
Config File could not be located: config/environments.xml.cfm. Please check again.
Any suggestions? I followed the steps and verfied them a few times. I am using coldbox 2.6.4 and mura 5.2.2263.
Oct 7, 2010 at 3:11 AM @Jonathan,
That issue has already been brought up in the comment thread. Look at comments # 9, 10, 15, 16 for the solution
Oct 7, 2010 at 6:26 AM Yep, that fixed it. Thank you!
Oct 7, 2010 at 9:44 AM So now I'm trying to use my coldbox. I figured I could do something like:
[mura]dspInclude('display_objects/custom/coldboxtemplate/index.cfm?event=general.doSomething')[/mura]
but I'm getting the error:
"Could not find the included template /muraWRM/default/includes/display_objects/custom/coldboxtemplate/index.cfm?event=general.doSomething"
Oct 7, 2010 at 2:24 PM What happens if you just try to include the front controller (index.cfm) without the event query string?
Oct 7, 2010 at 2:43 PM if I do:
[mura]dspInclude('display_objects/custom/coldboxtemplate/index.cfm')[/mura]
This works I get the welcome to coldbox page. The colbox image isn't showing for some reason. It's point to:
http://www.domain.com/coldbox-integration-test-page/includes/images/coldbox.png
Note that I have the don't show the site in the url feature turned on and I also use a url rewite to replace the index.cfm to make user friendly URLs.
Oct 7, 2010 at 4:05 PM @Jonathan,
I know why you're seeing what you're seeing and what you need to do to navigate around your ColdBox app, but the answer got kind of long and involved so I'm putting together a blog post. Stay tuned.
Oct 7, 2010 at 4:47 PM I CAN tell you here why the image isn't showing up. You have to change all paths to images so that they are relative to the Mura root since the coldbox app isn't at the root in this case as it typically is. You can take advantage of the AppMapping coldbox setting to do this. So for example if you look at the home.cfm view, the image tag for that image that isn't showing up is:
<img src="includes/images/coldbox.png" />
If you change it to
<img src="/#getSetting('AppMapping')#/includes/images/coldbox.png"/>
It will be visible again.
Oct 8, 2010 at 5:25 AM Check out my post on navigation within ColdBox/Mura:
http://objectivebias.com/entry/navigating-within-a-coldbox-application-integrated-into-mura-cms