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

** ALL-NEW CASEIN 5.0.0 — featuring new responsive UI based on Bootstrap 3! **

Casein is a Rails 4.x gem 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.

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

==Requirements

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

Legacy versions:

Rails 3.x: http://github.com/spoiledmilk/casein3

Rails 2.x: http://github.com/spoiledmilk/casein

==Disclaimer

Casein was created and is maintained by <NAME>. http://www.russellquinn.com

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

==What’s New

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

* 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

There is no real upgrade path from previous versions of Casein, including v4.x. It’s recommended to only use Casein v5.x on new projects.

==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: (temporary git link, until official release)

  gem 'casein', '5.0.0'

— 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. The default username and a random password will be displayed once the task has completed. You should specify your email address. 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=<EMAIL>

— 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 is_male:boolean

Command-line options 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.
  --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 to the model to the navigation. The _table partial is still generated. This is useful 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 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>

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

<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>TODO: These will be documented later. For now, just browse the casein_helper.rb file to see what’s available.</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.

Note that Casein runs from the shortlived Bootstrap v3.0.0 and hasn't yet been updated to Bootstrap v3.1.x. Some of the Bootstrap syntax might be different if you're used to 3.1.x. (Update coming soon!)

===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, 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 = {}

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

===Acknowledgements

Casein uses Bootstrap and Glyphicons.

Bootstrap is copyright (c) 2013 Twitter and is used under the Apache 2.0 license. http://getbootstrap.com

Glyphicons is an extensive glyph library created by <NAME> and made available for Bootstrap under the same Apache 2.0 license. http://glyphicons.com

Bootstrap-glyphicons is copyright (c) 2013 <NAME> and is used under the MIT License. http://glyphicons.getbootstrap.com<commit_msg>Readme tweak<commit_after>=Casein - a lightweight CMS toolkit for Ruby on Rails, based on Bootstrap

** ALL-NEW CASEIN 5.0.0 — featuring new responsive UI based on Bootstrap 3! **

Casein is a Rails 4.x gem 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.

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

==Requirements

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

Legacy versions:

Rails 3.x: http://github.com/spoiledmilk/casein3

Rails 2.x: http://github.com/spoiledmilk/casein

==Disclaimer

Casein was created and is maintained by <NAME>. http://www.russellquinn.com

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

==What’s New

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

* 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

There is no real upgrade path from previous versions of Casein, including v4.x. It’s recommended to only use Casein v5.x on new projects.

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

— 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. The default username and a random password will be displayed once the task has completed. You should specify your email address. 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=<EMAIL>

— 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 is_male:boolean

Command-line options 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.
  --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 to the model to the navigation. The _table partial is still generated. This is useful 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 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>

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

<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>TODO: These will be documented later. For now, just browse the casein_helper.rb file to see what’s available.</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.

Note that Casein runs from the shortlived Bootstrap v3.0.0 and hasn't yet been updated to Bootstrap v3.1.x. Some of the Bootstrap syntax might be different if you're used to 3.1.x. (Update coming soon!)

===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, 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 = {}

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

===Acknowledgements

Casein uses Bootstrap and Glyphicons.

Bootstrap is copyright (c) 2013 Twitter and is used under the Apache 2.0 license. http://getbootstrap.com

Glyphicons is an extensive glyph library created by <NAME> and made available for Bootstrap under the same Apache 2.0 license. http://glyphicons.com

Bootstrap-glyphicons is copyright (c) 2013 <NAME> and is used under the MIT License. http://glyphicons.getbootstrap.com
{'fraction_non_alphanumeric': 0.05968902128896316, 'fraction_numerical': 0.0029063430938022234, 'mean_word_length': 4.487838915470494, 'pattern_counts': {'":': 0, '<': 77, '<?xml version=': 0, '>': 79, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3889882', 'n_tokens_mistral': 7414, 'n_tokens_neox': 7078, 'n_words': 3928}