Upgrading Modules to 3.4.x
Clone this wiki locally
BrowserCMS 3.4.x will be compatible with Rails 3.1.x. In order to use existing modules with this version of browsercms, they also need to be upgraded to work against browsercms 3.4.x (and rails 3.1). To help simplify this process, we have updatedthe command line tool in the BrowserCMS gem, called
bcms-upgrade. This tool can be run on an existing BrowserCMS 3.3.x module to upgrade it.
In addition, its very likely that these instructions will also work when upgrading to Rails 3.2.x/BrowserCMS 3.5.x.
A. What Changed in 3.4.x?
Here's the changes for 3.4.x that will affect modules.
- Asset Pipeline - Modules can now include their JS/HTML/CSS/Images via the Asset pipeline, which allows for improved code organization.
- Namespaced Classes - Nearly all the Core CMS classes are now namespaced under Cms::, which should allow BrowserCMS (and modules) to be added to other projects without namespacing conflicts.
- Standardized Version Column - In <= 3.3.x, each versioned block has its own versions table, which maintained a pointer to the 'current' row by a named column. So in html_block_versions, it had a
html_block_idcolumn. With how Rails treats namespaced models, this got too messy, so ALL Block Versions just use the column
original_record_id. This means, for any modules, you need to update your
B. How to Upgrade
First things first: Check in your module code. Upgrading a module is going to delete and alter a large number of files. 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 inside your project's directory
$ gem install browsercms $ bcms-upgrade module
This will modify a whole bunch of files. From there, you will need to make some further tweaks, depending on how your module works.
C. Next Steps
The examples below assume a module called 'bcms_petstore' wherever paths are used.
1. Configuring Routing
Move any Engine routes from
config/routes. Assume you have the following file:
# In lib/bcms_petstore/routes.rb module Cms::Routes def routes_for_bcms_petstore namespace(:cms) do content_blocks :pet_food end end end
config/routes.rb to look like this, then delete
BcmsPetstore::Engine.routes.draw do content_blocks :pet_food end
Not that you do not need to namespace under :cms anymore (Isolated engines automatically are namespaced under the engine name).
2. Update the Gemspec
Review the gemspec and make sure it has:
- Correct dependencies (i.e. browsercms ~> 3.4.0)
- Packages the right files
3. Namespace classes
Any references to core BrowserCMS classes need to have a Cms:: added to them. This will mostly likely show up in seed data/migrations, or in portlets/controllers. Hopefully your unit/integration tests will catch theses. For example, before:
ContentType.create!(:name => "Widgets", :group_name => "Widget") widget_page = Page.create!( :name => "Widget", :path => "/widget", :section => Section.root.first, :template_file_name => "default.html.erb")
Cms::ContentType.create!(:name => "Widgets", :group_name => "Widget") widget_page = Cms::Page.create!( :name => "Widget", :path => "/widget", :section => Cms::Section.root.first, :template_file_name => "default.html.erb")
You will also need to move all your Engines controllers/class under the Engine namespace. So for example,
# Before: app/controllers/cms/widgets_controller.rb class Cms::WidgetsController < Cms::ContentBlockController end # After: app/controllers/bcms_your_module/widgets_controller.rb module BcmsYourModule class WidgetsController < Cms::ContentBlockController end end
Ensure the Engine has an isolated namespace, like so:
# In lib/bcms_widgets/engine.rb require 'browsercms' module BcmsWidgets class Engine < Rails::Engine isolate_namespace BcmsWidgets include Cms::Module end end
You will need to make some changes to your migrations before rake and generators will work. Eventually, you will want to run the following tasks, but until
rake -T stops throwing errors you will need to keep debugging the issues.
$ cd test/dummy $ bundle exec rake railties:install:migrations # Will add BrowserCMS migrations to your test/dummy project $ rails g browser_cms:cms # Add seed data to the test/dummy project $ bundle exec rake db:install # In root of project, you need to run `rake app:db:install`
You may need to reorder the timestamps of your engine's migrations so they come after BrowserCMS ones. The exact timestamps don't matter anymore, as
rake railties:install:migrations will generate new relative timestamps when adding migrations to a project.
Add a migration to rename the table to start with the name of your module, i.e.: bcms_your_module_
# For CMS 3.5.x require 'cms/upgrades/v3_5_0' def change v3_5_0_apply_namespace_to_block("BcmsYourModule", "Widget") end # For CMS 3.4.x def change rename_table :widgets, :bcms_your_module_widgets rename_table :widget_versions, :bcms_your_module_widget_versions if column_exists? :bcms_your_module_widget_versions, :widget_id rename_column :bcms_your_module_widget_versions, :widget_id, :original_record_id end end
In your Installation generator, you can add the following to have it copy all your project migrations as part of the installation.
def copy_migrations rake 'bcms_your_module:install:migrations' end
4. Test installing the gem
When you are done with all your changes, be sure to package and test the gem locally on a BrowserCMS project, using the following steps:
$ rake install $ cd /path/to/projects $ bcms new test_project $ cd test_project $ rails g cms:install bcms_your_module $ rake db:install
Then boot the server, and verify your module works. You may need to edit the .gemspec to make sure things work correctly. Also, review the Install Generator and make sure it's doing everything it needs to (including mounting the engine if needed), like so:
def add_routes mount_engine(BcmsYourModule) end
See [https://gist.github.com/2776664] for a very abbreviated version of these commands.
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.