-
Notifications
You must be signed in to change notification settings - Fork 260
Adding BrowserCMS to an existing Rails project
- 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.
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)
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:
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_"
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
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.
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.
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