Adding BrowserCMS to an existing Rails project

A. Prerequisites

• This guide is valid for BrowserCMS 3.4.0 or later.
• You have installed the BrowserCMS gem as detailed in the Getting Started Guide
• You have an existing Rails project (3.1.x) that you want to add BrowserCMS to.

B. Getting Starting

BrowserCMS is designed as a mountable engine, which means it can be added to existing Rails applications. From within your rails project, run the following:

$ bcms install
$ rake db:install 

The db:install command will run both db:migrate and run db:seed, so depending on whether your projects has existing data in db/seeds.rb already, you may need to manually run the following tasks instead of db:install:

$ rake db:migrate
$ rake db:seed:browsercms # This will seed ONLY the browsercms data (not db/seeds.rb)

Getting Started

After you log in at /cms, you will end up being redirected to /, which is probably NOT the homepage of the CMS. To access the CMS UI, enter /cms/sitemap into your URL bar.

C. Configuration

At this point, you will have BrowserCMS and your application coexisting, but there are some likely configuration you will want to do:

1. Which homepage?

By default, BrowserCMS will serve the home page (i.e. /) if there is no 'root' route in a project. This is handled as the last route in the project. There are few things in the CMS that key off the / route, including the 'BrowserCMS Logo' as well as logging.

You may want to add a Sitemap link to your Rails pages for your 'authorized' users, so they can access the CMS UI. Like so:

<%= link_to "CMS", cms.sitemap_path %>

2. Authentication

One of the decisions you will want to make about your merged CMS and Rails app is how you want authentication to be handled. BrowserCMS has its own authentication system based on Restful Authentication. It's possible to hook your application's authentication into this, which means the CMS admin UI can be used to manage adding/editing users and the groups they are in. Alternatively, you can leave the authentication pieces separate, but this may make for a disjointed user experience.

More work will be done in future versions to make authentication more 'pluggable'. But for now, you can make your existing user class behave as though it were a CMS User with an existing set of groups.

class MyProjectUser < ActiveRecord::Base
  acts_as_cms_user :groups => [Cms::Group.find_by_code('cmsadmin')]
end

When a user logs into your application, they would be considered in the 'cmsadmin' group as well, for the purposes of what the CMS allows them to see. This would affect whether they can edit content through the CMS UI, or view certain pages.

3. Tables

When the CMS is added to an existing project, it will automatically prefix all of the tables with cms_ to avoid conflicts with existing tables. You can configure this prefix in the config/initializers/browsercms.rb file like so:

Cms.table_prefix = "cms_"

4. CMS Templates as Layouts

To use CMS layouts as templates, you can add the following to your controller classes:

class MyProjectsController < ApplicationController
  include Cms::Acts::ContentPage
  layout "templates/subpage"
end

Where the subpage.html.erb is the name of the CMS template you want this page to use.