Casein

=Casein - a lightweight Ruby on Rails CMS.

THIS VERSION FOR RAILS 2.x ONLY

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

NEW VERSION FOR RAILS 3.x AT: http://github.com/spoiledmilk/casein3

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.

==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 the first attempt at extracting and sharing the core.

We will be expanding on the documentation, adding screenshots and other resources in due course.

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 (http://www.spoiledmilk.dk) and maintained by Russell Quinn (http://www.russellquinn.com)

==Installation

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

— Casein uses JQuery as its JavaScript library and the JRails plugin is required. Install this first:

script/plugin install git://github.com/aaronchi/jrails.git

— Install the Casein plugin

script/plugin install git://github.com/spoiledmilk/casein.git

— If you are adding Casein to 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 environment settings. For example in config/environment.rb:

ActionMailer::Base.delivery_method = :smtp ActionMailer::Base.raise_delivery_errors = false ActionMailer::Base.smtp_settings = { :tls => false, :address => "mail.yourdomain.com", :port => 25, :domain => "yourdomcina.com", :user_name => "donotreply@yourdomain.com", :password => "whatever", :authentication => :login }

— Add Casein routes. Add the following to your project config/routes.rb file:

At the top:

include CaseinAddRoutes

Then inside the Routes.draw block:

CaseinAddRoutes::mapper map

— Install required Gems. Casein requires the calendar_date_select and will_paginate gems. The dependencies are automatically added to your config. So, to install dependencies just run:

sudo rake gems:install

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

script/generate casein_install

— Add Casein assets to your project /public folder. These files should not be altered and it is safe to run this multiple times.

script/generate casein_update

— Run the following Rake task to perform the Casein database migrations and 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:init email=you@yourdomain.com

— 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! You should change the default password immediately!</b>

==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

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

<b>views/casein_layouts/_navigation.html.erb</b>

An ERB partial for the 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/_right_navigation.html.erb</b>

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

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

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 ‘script/generate 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!

<b>Rules and conventions</b>

• Casein extension controllers and helpers should be prefixed with casein_
• Casein extension controllers should derive from 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>Right bar</b>

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 right bar, you must create a partial with the following filename:

_[action]_right_bar.html.erb

For example to specify the right bar contents for a Casein extension controller called ‘casein_companies’ and the action ‘new’:

/app/views/casein_companies/_new_right_bar.html.erb

These files are optional. Casein will generate a blank right bar if it cannot find a matching ERB partial.

<b>Helper functions</b>

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

<i>TODO: These will be documented later. For now, just browse the file at /vendor/plugins/casein2/helpers/casein_helper.rb to see what’s available.</i>

<b>Casein version</b>

Your Rails application may discover what version of Casein it is currently running by using the following variables:

$CASEIN_MAJOR_VERSION - number, e.g. 2 $CASEIN_MINOR_VERSION - number, e.g. 0 $CASEIN_BUILD_INFO - build number or string, e.g. 231 or 'alpha'

<b>Rake tasks</b>

There are several Casein Rake tasks available to generate test users, or reset the user database. 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:

script/generate 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:

script/generate casein_scaffold customer name:string age:integer date_of_birth:date is_male:boolean

There are currently two further command line options that can be added to the end of the generate command:

--force-plural = Forces the generation of a plural ModelName --create-model-and-migration = Also creates a model, migration and tests. By default the scaffold generator will work from existing models, but this option will generate the model 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/_navigation.html.erb
• Create a controller with the name: app/controllers/casein_model_controller.erb
• Add a helper template at: app/helpers/casein_model_helper.rb
• Add a test template at: test/functional/casein_model_controller_test.rb
• Add views for index, new, show and their sidebars 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.

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

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