If you're blessed (or rich) enough to have your own servers, using frameworks like Mach-II is pretty easy. Pop it on the server, do a mapping, good to go for all your sites. In a shared hosting environment, however, you will find there are some quirks and gotchas to using Mach-II that make installing it just a bit different.
If you just throw up Mach-II in the default folder name with a basic config, you may find yourself getting some downright wacky results, like a random Arabic language template wrapping your website, or errors about broken files when those files don't even exist in your site. So what's going on? ColdFusion and Mach-II are getting all kinds of confused, that's what. Fixing this is a multi-step process:
- Give your Mach-II folder a unique name! I generally do a play on my site's name, so if I had Mach-II running on this site, I might do CFBeyMachII or the like. Easy enough to type, unique enough no one else is likely to be using it. Now you might already be thinking, “it doesn't matter, I can just do an Application.cfc” mapping for my version. True enough, except the Application.cfc can't extend off a custom mapping you are setting in said Application.cfc!
- In your Application.cfc, change your CFCOMPONENT's extends attribute from MachII.mach-ii to CUSTOMNAME.mach-ii – this makes sure it is extending your installation of Mach-II.
- Now you can do a this.mappings for your Mach-II folder. It can be the same name as your folder, if you like. Also do a mapping for your site root. I usually do something like this to simplify it:
<cfset this.mappings["/SITENAME"] = GetDirectoryFromPath( GetCurrentTemplatePath() ) />
<cfset this.mappings["/SITENAMEMachII"] = GetDirectoryFromPath( GetCurrentTemplatePath() ) & "/SITENAMEMachII" />
- In your mach-ii.xml config, you need to change your Mach-II prefixes to match your new Mach-II mapping. You might also want to prefix the type attributes for your listeners, filters, and properties with your new site root map, again to prevent potential bleed over. So:
<property name="applicationProperty" type="properties.ApplicationProperty" />
<listener name="someListener" type="model.someModel.someListener" />
<property name="applicationProperty" type="SITENAME.properties.ApplicationProperty" />
<listener name="someListener" type="SITENAME.model.someModel.someListener" />
- Now comes the big, messy pain part – within your actual framework code, i.e. if you have CFBeyMachII in our example above, you need to replace all MachII. instances with AEWMachII so that it all matches its actual folder structure
With all that done, you should be good to go to use Mach-II on your site! Well, maybe with one caveat. Mach-II's documentation currently indicates that if you want to upgrade your framework, such as going from 1.6 to 1.8, you have to be able to restart your ColdFusion server, or it won't work. Obviously you can't do that in a hosted environment…but the document in question is also very dated so it may not hold true anymore. I'll be finding out myself eventually, as An Eclectic World v7 was built on 1.6, but the upgrade I'm working on will be using 1.8. Weee!