=Casein - a lightweight CMS toolkit for Ruby on Rails, based on Bootstrap

** ALL-NEW CASEIN 5.1.1 — featuring new responsive UI based on Bootstrap 3.3! **

Casein is a Rails 4.x gem that provides scaffolding generators and helper functions to quickly create a clean and minimal CRUD interface for your data.

It comes with a pre-rolled user-authentication system, supports user-based timezones, and is mobile ready.

As Casein is completely decoupled from the front end, it can be added to new or existing Rails projects, or used as a standalone CMS to drive platforms built on other technologies.

Screenshots at: http://www.caseincms.com

==Requirements

This version of Casein is designed for Ruby on Rails 4.x and Ruby 2.x.

==What’s New in 5.1.1

Casein 5.1.1 has the following updates:

* Fixes for Rails 4.2 compatibility
* Added new Casein helpers for HTML5 form helpers (see “Changing form elements” below)
* First steps in building a test suite
* Switched from Jeweler to Bundler for gem distribution

Version 5.1.1 should be a drop-in replacement for 5.1.0

Thanks to @bunnymatic for this release.

==What Was New in 5.1.0

* Finally updated to Boostrap 3.3 (all bundled Bootstrap files removed in favor of bootstrap-sass gem)
* Rake task to create admin user now takes an optional password
* Authlogic version bumped to 3.4.3
* UI tweaks

Version 5.1.0 should be a drop-in replacement for 5.0.0

==What Was New in 5.0.0

* Now based on Bootstrap 3
* Complete UI overhaul, now mobile-first
* Support for strong parameters
* Support for asset pipeline
* Rails 4 compatibility fixes
* Many other tweaks and improvements over Casein 3.x and 4.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', '~>5.1.1'

— Then use bundler to install Casein and its dependencies:

  bundle install

— If you have just created a new project — and don't want to use the default SQLite settings — then remember to add your database details to /config/database.yml at this point.

— To enable Casein notification emails (used for new users and forgotten passwords) then add your SMTP server information to your initializers. For development, you can use something cool like MailCatcher (http://mailcatcher.me)

— 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

— 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. You should specify your email address and password (or omit the password parameter to have a random password assigned.) If you've 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=you@yourdomain.com [password=your_password]

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

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

<b>Casein should now be running!</b>

==Usage

The default Casein install supports user authentication. Users may have a role of either ‘administrator’ 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.

==Scaffolding

Casein has a scaffolding generator to automatically create all the CRUD 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 has_paid:boolean

By default the scaffold generator expects the model and database migration to already exist. This is because you typically won't want all of your model attributes to be editable in Casein. So you'd set up your model and migration the usual way, then run the Casein scaffold generator just for the appropriate attributes. However, you can add --create-model-and-migration to the generator to also create these files at the same time.


Command-line options that can be added to the end of the scaffold generate command:

  --create-model-and-migration = Also creates a model and migration.
  --read-only = Creates scaffolding to view model data only (you will not be able to edit, create, or delete records). This is useful if you want to create a read-only viewer of data that's generated elsewhere.
  --no-index = Excludes the index view and does not add the model to the navigation. The _table partial is still generated. This is useful when generating has/belongs relationships.

Once the command has been executed, the generator will:

* Add a new tab for the model to: app/views/casein/layouts/_tab_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 sign in to Casein and directly edit and create new instances of your model data right away!

However, you’ll 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.

<em>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.</em>

==General Configuration

<b>app/helpers/casein/config_helper.rb</b>

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.

To change the default page that Casein shows, you should change casein_config_dashboard_url. For example, to just go straight to the index page for a model named Page, you'd use:

  def casein_config_dashboard_url
    url_for casein_pages_path
  end

<b>views/casein/layouts/_tab_navigation.html.erb</b>

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.

<b>view/casein/layouts/_top_navigation.html.erb</b>

An ERB partial for adding items to the top navigation.

<b>/assets/javascripts/casein/custom.js & /assets/stylesheets/casein/custom.css.scss</b>

These files are added to your app’s /assets directory. They allow you to add custom JavaScript or CSS to your Casein deployment.

==Customising

Once you have the Casein core installed and configured, and have added support for your models with the scaffolding generator, you’ll want to extend it so that it actually has some functionality for your project!

<b>Rules and conventions</b>

* 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.

<b>Sidebar</b>

The sidebar 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('th-list')}Back to list".html_safe, casein_admin_users_path %></li>
  <% end %>

The casein_show_icon function will display any icon from the Glyphicon collection (http://glyphicons.com). Simply enter the short name.

<b>Helper functions</b>

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

<i>NOTE: Not all are documented here.  Please browse the casein_helper.rb file to see what’s available that is not listed below.</i>


<b>Casein version</b>

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', 'patch', and 'build'.

<b>Rake tasks</b>

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:’

===Bootstrap

Casein is now based on Bootstrap (http://getbootstrap.com) and jQuery. Bootstrap offers a wealth of UI components, CSS styles, and JavaScript plugins. See the Bootstrap website for full details.

===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 _form.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, obj, attribute, options = {}
  casein_password_field form, obj, attribute, options = {}
  casein_text_area form, obj, attribute, options = {}
  casein_text_area_big form, obj, attribute, options = {}
  casein_check_box form, obj, attribute, options = {}
  casein_check_box_group form, obj, check_boxes = {}
  casein_radio_button form, obj, attribute, tag_value, options = {}
  casein_radio_button_group form, obj, radio_buttons = {}
  casein_select form, obj, attribute, option_tags, options = {}
  casein_time_zone_select form, obj, attribute, option_tags, options = {}
  casein_collection_select form, obj, object_name, attribute, collection, value_method, text_method, options = {}
  casein_date_select form, obj, attribute, options = {}
  casein_time_select form, obj, attribute, options = {}
  casein_datetime_select form, obj, attribute, options = {}
  casein_file_field form, obj, object_name, attribute, options = {}
  casein_hidden_field form, obj, attribute, options = {}
  casein_custom_field form, obj, attribute, custom_contents, options = {}
  casein_color_field form, obj, attribute, options = nil
  casein_search_field form, obj, attribute, options = nil
  casein_telephone_field form, obj, attribute, options = nil
  casein_url_field form, obj, attribute, options = nil
  casein_email_field form, obj, attribute, options = nil
  casein_date_field form, obj, attribute, options = nil
  casein_datetime_field form, obj, attribute, options = nil
  casein_datetime_local_field form, obj, attribute, options = nil
  casein_month_field form, obj, attribute, options = nil
  casein_week_field form, obj, attribute, options = nil
  casein_time_field form, obj, attribute, options = nil
  casein_number_field form, obj, attribute, range, step, options = nil
  casein_range_field form, obj, attribute, range, options = nil


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_sublabel — add a smaller, clarrifying label to the right of the main label
  :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 Bootstrap responsive two-column layout is automatically created by the scaffold generator. You can manually edit this to be any Bootstrap grid configuration. See Bootstrap documentation for full details: http://getbootstrap.com/css/#grid

===Using alerts

Casein can display three types of styled alerts: Warning, Notice, and Help.

Warning and Notice are set using Rail’s flash variables. Set flash[:warning] and flash[:notice] respectively.

Help is set on a page by adding a content_for block to a view:

  <%= content_for :help do %>
    This is some help text. It describes what this page is for in more detail.
  <% end %>

===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 <b>after</b> 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

===Default Timezone

Every Casein user can set their own timezone via their profile. To change the default timezone for new users, set config.time_zone in your app.

==Contributing

If you contribute, please help us flesh out the test suites.  Do not include new methods that you cannot test.

To run tests:

    rake app:db:migrate app:db:test:prepare
    rake spec

==Disclaimer

Casein was created and is maintained by Russell Quinn. http://www.russellquinn.com

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