Casein - a lightweight Ruby on Rails CMS.¶ ↑

THIS LEGACY VERSION FOR RAILS 3.x ONLY

NEW VERSION FOR RAILS 4.x AT: www.github.com/russellquinn/casein

LEGACY VERSION FOR RAILS 2.x AT: www.github.com/spoiledmilk/casein

Casein is a plugin that provides scaffolding generators and helper functions to quickly create a clean and minimal CRUD (Create, Read, Update and Delete) interface for your data. It also comes with a pre-rolled user authentication system. As Casein is completely decoupled from the front-end, it can be added to a new or existing Rails project, or used as a standalone CMS to drive platforms built on other technologies.

This version of Casein is designed for Ruby on Rails 3.x. For a legacy version that is compatible with Rails 2.x, see: github.com/spoiledmilk/casein

Disclaimer¶ ↑

Casein is the in-house CMS framework used by digital agency Spoiled Milk and is being used in many live production websites. This open source project is an attempt to extract and share the core.

Casein is available to use under the terms of the MIT License. See the LICENSE file for more details.

Casein is sponsored by Spoiled Milk (www.spoiledmilk.dk) and maintained by Russell Quinn (www.russellquinn.com)

Casein 3.x is built for Ruby on Rails 3 and has the following major updates:

• Authentication changed to use Authlogic

• Supplied as a gem

• Runs as an Engine

• Now properly namespaced

• Timezone support

• Rails 3 compatibility fixes

• Many other tweaks and improvements over Casein 2.x

Installation¶ ↑

— Create a new Rails project (or use an existing one) and enter the project directory from a terminal prompt.

— Add the Casein gem to your Gemfile:

gem 'casein'

• Then use bundler to install Casein and its dependencies:

  sudo bundle install

— If you have just created a new project, then remember to add your database details to /config/database.yml at this point.

— These installation instructions also assume that you have set up your RAILS_ENV environment variable.

— To enable Casein notification emails (used for new users and forgotten passwords) then add your SMTP server information to your initializers. For example create a new file called initializers/setup_mail.rb and add the following to it:

ActionMailer::Base.delivery_method = :smtp
ActionMailer::Base.raise_delivery_errors = false
ActionMailer::Base.smtp_settings = {
  :enable_starttls_auto => false,
  :address => "mail.yourdomain.com",
  :port => 25,
  :domain => "yourdomain.com",
  :user_name => "[email protected]",
  :password => "whatever",
  :authentication => :login
}

— Install Casein configuration files into your project. This should not be run more than once without backing up or merging the generated files, as your customisations will be overwritten:

rails g casein:install

— Add Casein assets to your project /public folder. These should not be modified as they may be overwritten in future updates:.

rails g casein:update

— Perform a database migration to create the Casein users table:

rake db:create (if needed)
rake db:migrate

— Run the following Rake task to set up an initial user. The default login and password will be displayed once the task has completed. You should specify your email address. If you set up an SMTP server in your Rails environment then you’ll also receive an email notification about the new account.

rake casein:users:create_admin [email protected]

— Run your app! (rebooting the web server if applicable)

— You can access Casein at yourdomain.com/casein or yourdomain.com/admin

Casein should now be running! You should change the default password immediately!

Usage¶ ↑

The default Casein install supports user authentication. Users may have a status of either ‘admin’ or ‘user’. The former is allowed to add, edit and delete other Casein users. The latter is only allowed to edit their own profile.

Casein is a framework allowing you to quickly build up an interface to edit and create new records from your database model. As well as the user support and user interface, there are many configurations and generators to help you along the way.

Configuration¶ ↑

app/helpers/casein/config_helper.rb

This is the main Casein configuration file that allows you to change things such as the website name, logo, notification email address, dashboard URL, etc. The options are documented within the file.

views/casein/layouts/_left_navigation.html.erb

An ERB partial for the the left navigation tabs. Note that using the scaffolding generator will automatically add tabs into this file, but it can also be manually edited and rearranged.

view/casein/layouts/_right_navigation.html.erb

An ERB partial for the the right navigation tabs. Note that the ‘users’ tab is added automatically for admin users.

/public/casein/javascripts/custom.js & /public/casein/stylesheets/custom.css

The Casein assets are located in /public/casein. These are the only two files you should change. They allow you to add custom JavaScript or CSS to your Casein deployment. These files are not overwritten using the ‘rails g casein:update’ command.

Customising¶ ↑

Now that you have the basic Casein installed and configured, you’ll want to extend it so that it actually has some functionality for your project!

Rules and conventions

• Casein extension controllers and helpers should be namespaced to ‘Casein::’

• Casein extension controllers should derive from Casein::CaseinController and not ApplicationController

• To set the page title, your controller action should set @casein_page_title. If this is not set, then Casein will use a default created from your project name.

Right bar

The right bar in Casein should be used for view specific actions, e.g. “Add user” for users/index, or “Back to list”, “Delete user” for users/show.

To specify the contents of the sidebar, you must add a ‘content_for :sidebar’ block in the relevant view file (index, show, etc.) e.g.:

<%= content_for :sidebar do %>
  <li><%= link_to "#{casein_show_icon('table')}Back to list".html_safe, casein_users_path %></li>
<% end %>

The casein_show_icon function will display any icon present in the /public/casein/images/icons folder. By default this only contains add, delete and table after install. However, more can be added as required by downloading from www.famfamfam.com/lab/icons/silk/

Helper functions

There are several Casein helper functions that are automatically available in any of your Casein extension views.

TODO: These will be documented later. For now, just browse the casein_helper.rb file to see what’s available.

Casein version

Your Rails application may discover what version of Casein it is currently running by calling the function:

casein_get_version_info

This will return an array with the keys ‘major’, ‘minor’ and ‘patch’.

Rake tasks

There are several Casein Rake tasks available to manage users. To see what is available, list all Rake commands using:

rake -T

The Casein Rake tasks are all namespaced with ‘casein:’

Scaffolding¶ ↑

Casein has a scaffolding generator to automatically create all the views and controllers for your project models. This is the fastest way to add Casein support to your project.

The command to run the scaffolding generator is:

rails g casein:scaffold ModelName [field:type, field:type]

Where:

• ModelName – The singular name of your model, e.g. customer

• field:type – The name of your database fields and their types, e.g. name:string. The field name must match the name in your migrations and the type must be one of the Rails migration types (string, text, integer, float, decimal, datetime, timestamp, time, date, binary, boolean). Note that you do not have to specify all of the fields in your model, but just the ones that you wish to be editable in Casein.

e.g. a typical scaffolding command might look like:

rails g casein:scaffold customer name:string age:integer date_of_birth:date is_male:boolean

There is one command-line option that can be added to the end of the generate command:

--create-model-and-migration = Also creates a model and migration. By default the scaffold generator will work from existing models, but this option will generate the model and database migration files for you. This means you can also use Casein to set up a new project quickly as well.

Once the command has been executed, the generator will:

• Add a new tab for the model to: app/views/casein/layouts/_left_navigation.html.erb

• Create a controller with the name: app/controllers/casein/model_controller.erb

• Add views for index, new and show to: app/views/casein/model/

• If you restart and run your application now, you’ll be able to log in to Casein and directly edit and create new instances of your model data right away!

However, you’ll probably want to customise your views and side bars and extend your controller to suit your project. The scaffold generator just sets up the defaults for you.

NOTE: Once you start customising the generated scaffolding files, you should be aware that if you run the generator again you should not overwrite the changed files without backing them up first. The generator will warn you each time it finds a file that you’ve customised. If you run the scaffold generator from a new version of Casein, then you should manually merge your backup and the new file. You can of course however, leave your originals untouched.

Changing form elements / other helpers¶ ↑

Casein will insert form elements suitable for the field types you specified in the command line. However, you may wish to customise these, e.g. swap a text field for a password field, swap an integer field for a select dropdown, or swap a date field for a full calendar picker, etc.

You will find the form used for both new and show in a partial named _fields.html.erb

All of the standard Rails form helpers are available, but the Casein versions are prefixed with casein_. These versions are styled for the Casein interface and have automatic support for validation error reporting.

casein_text_field form, model, attribute, options = {}
casein_password_field form, model, attribute, options = {}
casein_text_area form, model, attribute, options = {}
casein_text_area_big form, model, attribute, options = {}
casein_check_box form, model, attribute, options = {}
casein_check_box_group form, model, check_boxes = {}
casein_radio_button form, model, attribute, tag_value, options = {}
casein_radio_button_group form, model, radio_buttons = {}
casein_select form, model, attribute, option_tags, options = {}

casein_time_zone_select form, obj, attribute, option_tags, options = {}

casein_date_select form, model, attribute, options = {}

casein_time_select form, model, attribute, options = {}

casein_datetime_select form, model, attribute, options = {}
casein_file_field form, model, object_name, attribute, options = {}
casein_hidden_field form, model, attribute, options = {}

For more information on each function, check the app/helpers/casein/casein_helper.rb file within the project. The method parameters are typically the same as the Rails form tag helpers. There are some extra Casein options that can be passed through as part of the options hash:

:casein_label – by default the humanized version of the database field name is used as the label, but this will override it with a string of your choice.
:casein_button_label – available in casein_radio_button and casein_check_box. Used to give individual buttons their labels.
:casein_truncate - may be passed into casein_table_cell_link along with a maximum length to automatically truncate strings and suffix with '...'

Changing form layout¶ ↑

A basic two-column layout is automatically created by the scaffold generator. The position of form elements is controlled by parent DIVs. A left column element is housed in a “tfContainer” and a right column element in “tfContainer tfContainerSecond”. Note that the generator does not take form element height into account, so you may need to have two sequential matching tfContainer types to balance out some of the larger components, such as the calendar picker.

There is an optional container class that forces form elements to use the whole width of the page. This is “tfContainer tfContainerFullWidth” and if used together with casein_text_area_big will create a textarea suitable for, say, editing full page content.

Adding styled help blocks¶ ↑

Sometimes it is necessary or useful to add guidelines or help text to your forms and tables. Casein offers a CSS class for this called “help”, which can be used throughout your views as necessary.

Routes¶ ↑

Casein adds the routes for the scaffolded models to the top of your application’s routes.rb file. It also adds default routes for basic Casein functionality after your application’s routes. If you have a catch-all style route defined, then these defaults won’t be run. You can solve this be using Rails’ constraint feature and the supplied Casein::RouteConstraint, which will stop your catch-all from matching if the request is for a Casein resource.

e.g.

match ':controller(/:action(/:id(.:format)))', :constraints => Casein::RouteConstraint.new

Acknowledgements¶ ↑

The icons used in Casein were created by Mark James and are licensed under the Creative Commons Attribution 2.5 License (creativecommons.org/licenses/by/2.5/). The full series of icons are available here: www.famfamfam.com/lab/icons/silk/