Upgrading modules to 3.3
Clone this wiki locally
BrowserCMS 3.3 is the first version to be released using Rails 3. In order to use existing modules with this version of browsercms, they also need to be upgraded to work against browsercms 3.3 (and rails 3). To help simplify this process, we have added a new commandline tool to the BrowserCMS gem, called
bcms-upgrade. This tool can be run on an existing Rails 2/BrowserCMS project to upgrade it.
What Changed in 3.3?
First, let’s take a look at some of the changes in BrowserCMS 3.3 as they related to modules.
- All Modules are now Rails Engines. We have provide a helper module
Cms::Modulethat will be included each the Engine for each module.
- Modules now provide an ‘install’ generator that can be used to copy migrations and other files into the project. Module developers can now update these Rails 3 generators to do whatever special cases might need to be done during module installation.
How to Upgrade
First things first: Back up or Check in your module code. Upgrading a module is going to delete and alter a large number of files. It’s far easier if you have a clean working directory that you can easily start over from if something goes wrong. And you are using source control, right?
This upgrade script assumes that the project is managed in Git, and will use Git to revert some files during the script.
Here’s what you need to do:
- Install BrowserCMS 3.3 gem
bcms-upgrade check– This will analyze the project and determine what needs to be done next.
- Take the corrective action listed in
checkuntil there are no more errors.
- Check in those ‘pre-upgrade’ changes.
bcms-upgrade upgrade. This will upgrade the project to Rails 3.
- Follow the instructions printed to test. You can run
bcms-upgrade next_stepsat any time to reprint the instructions.
Help! Something’s not working
Upgrades can be tricky things, so here is a potential set of things you might need encounter while upgrading to make things work.
While running tests, I get NoMethodError: undefined method `mock’ for …
This may happen if you are using mocha for your tests. Mocha needs to be loaded after the testing library. Make sure the following is in your Gemfile.
# Gemfile # Delays loading of mocha until later gem "mocha", :group => :test, :require=>false
Then edit your test_helper.rb like so:
# test/test_helper.rb # Must be the last statement in the file. require 'mocha'
Unknown constants for Cms classes
This will probably show up as an error that looks like this:
<top (required)>: uninitialized constant Page (NameError)
In this case, your engine can’t load a class from BrowserCMS. The issue is caused by the fact that many of BrowserCMS’s classes are located in app/models, app/controllers, etc. These classes aren’t loaded when the browsercms gem is required, but later by rails. The solution is to delay requiring any files in your module that depend on a BrowserCMS class. You can do this by adding the following to your Engine.
require 'browsercms' module BcmsYourModule class Engine < Rails::Engine include Cms::Module # Wait until Rails loads browsercms/apps directories. initializer "bcms_your_module.require_classes" do require 'bcms_your_module/some_file_referencing_cms_classes' end end end