Adding BrowserCMS to an existing Rails project

Hans Wannop edited this page May 20, 2015 · 13 revisions
Clone this wiki locally

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

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 cms:install:migrations
$ 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. Controllers and the CMS

Existing Rails controllers can tap into the CMS behavior in several different ways. To start, just include the following in your controller.

class MyProjectsController < ApplicationController
  include Cms::Acts::ContentPage
end

4a. 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"

  def index
  end
end

Where the subpage.html.erb is the name of the CMS template you want this page to use. Since this is not an editable page, no CMS toolbar will be displayed. Assuming the template has two containers named :main and :sidebar you can display content on the page by putting the following in your view:

# In app/view/my_projects/index.html.erb

<% content_for :main do %>
Main Content goes here
<% end %>
<% content_for :sidebar do %>
Sidebar content goes here
<% end %>

As of 3.4.0, any content not wrapped in a content_for block won't be displayed on the page. (Later versions may likely change this later to make it default show to the :main container.

4b. Customizing the Page Title

By default, the title of the page will be the same as the controller (i.e. 'My Projects'). To customize this on a per action basis, do the following:


class MyProjectsController < ApplicationController
  include Cms::Acts::ContentPage

  def index
    self.page_title = "A Custom Title"
  end
end

4c. Authentication

4d. Menus/Breadcrumbs

In order to have menus and breadcrumbs work correctly with your custom controllers, there is a bit of a work around to tell the CMS which section of the site it should logically be a part of. Let's assume we want our custom controller to appear in the root section of the site.

class CustomController < ApplicationController
  include Cms::Acts::ContentPage
  layout "templates/default"

  helper_method :current_page

  def index
    root = Cms::Section.root.first
    @page = OpenStruct.new(page_title: "Custom", path: "/custom", section: root, ancestors: [root])
  end

  def current_page
    @page
  end

end

The key changes are overriding the current_page and @page values which are used by render_menu and render_breadcrumbs, and providing an ancestor section from which to create the menu.

4e. Error Pages

You can allow your controllers to make use of the built in error pages found under /system/. Here is an example:

class CustomController < ApplicationController
  include Cms::Acts::ContentPage

  # Renders /system/access_denied
  def denied
    raise Cms::Errors::AccessDenied
  end

  # Renders /system/not_found
  def missing
    raise ActiveRecord::RecordNotFound
  end

  # Renders /system/server_error
  def error
    raise Exception
  end
end