Adding BrowserCMS to an existing Rails project
Clone this wiki locally
- 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
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
$ rake cms:install:migrations $ rake db:migrate $ rake db:seed:browsercms # This will seed ONLY the browsercms data (not db/seeds.rb)
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.
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 %>
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.
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
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
: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
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
- See Controllers with CMS Authentication for some behavior that is added with Acts::As::ContentPage.
- See CMS Authentication for an overview of how the CMS Authentications system works.
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