-
Notifications
You must be signed in to change notification settings - Fork 261
Upgrading modules to 3.3
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.
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::Module
that will be included each the Engine for each module. - Both Modules and BrowserCMS now serve static assets from the gem. This means less clutter in individual projects, especially for gems (like bcms_fckeditor) that had a ton of javascript/css being copied to projects. This should make it much easier to tell what’s specific to a project, and what’s part of BrowserCMS or its Modules.
- 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.
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
- Run
bcms-upgrade check
– This will analyze the project and determine what needs to be done next. - Take the corrective action listed in
check
. Reruncheck
until there are no more errors. - Check in those ‘pre-upgrade’ changes.
- Run
bcms-upgrade upgrade
. This will upgrade the project to Rails 3. - Follow the instructions printed to test. You can run
bcms-upgrade next_steps
at any time to reprint the instructions.
Upgrades can be tricky things, so here is a potential set of things you might need encounter while upgrading to make things work.
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'
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