Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 215 lines (127 sloc) 12.704 kb
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
1 =Casein - a lightweight Ruby on Rails CMS.
2
3 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.
4
5 ==Disclaimer
6
7 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.
8
9 Casein is available to use under the terms of the MIT License. See the LICENSE file for more details.
10
11 Casein is sponsored by Spoiled Milk (http://www.spoiledmilk.dk) and maintained by Russell Quinn (http://www.russellquinn.com)
12
7bd27d4 Update readme
Russell Quinn authored
13 Casein 3.x is built for Ruby on Rails 3 and has the following major updates:
14
15 * Supplied as a gem
16 * Runs as an Engine
17 * Now properly namespaced
67aded6 Fixed deprecation warning about form_for tag style
Russell Quinn authored
18 * Rails 3 compatibility fixes
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
19
20 ==Installation
21
22 — Create a new Rails project (or use an existing one) and enter the project directory from a terminal prompt.
23
24 — Add the Casein gem to your Gemfile:
25
587db8d Update rdocs
Russell Quinn authored
26 gem 'casein'
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
27
da96359 Updated gemspec
Russell Quinn authored
28 - Then use bundler to install Casein and its dependencies:
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
29
da96359 Updated gemspec
Russell Quinn authored
30 sudo bundle install
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
31
32 — If you have just created a new project, then remember to add your database details to /config/database.yml at this point.
33
34 — These installation instructions also assume that you have set up your RAILS_ENV environment variable.
35
36 — 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:
37
38 ActionMailer::Base.delivery_method = :smtp
39 ActionMailer::Base.raise_delivery_errors = false
40 ActionMailer::Base.smtp_settings = {
4b70861 Update rdocs
Russell Quinn authored
41 :enable_starttls_auto => false,
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
42 :address => "mail.yourdomain.com",
43 :port => 25,
44 :domain => "yourdomain.com",
45 :user_name => "donotreply@yourdomain.com",
46 :password => "whatever",
47 :authentication => :login
48 }
49
50 — 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:
51
587db8d Update rdocs
Russell Quinn authored
52 rails g casein:install
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
53
54 — Add Casein assets to your project /public folder. These should not be modified as they may be overwritten in future updates:.
55
56 rails g casein:update
57
58 - Perform a database migration to create the Casein users table:
587db8d Update rdocs
Russell Quinn authored
59
60 rake db:create (if needed)
61 rake db:migrate
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
62
63 — 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.
64
65 rake casein:users:create_admin email=you@yourdomain.com
66
67 — Run your app! (rebooting the web server if applicable)
68
69 — You can access Casein at http://yourdomain.com/casein or http://yourdomain.com/admin
70
71 <b>Casein should now be running! You should change the default password immediately!</b>
72
73 ==Usage
74
75 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.
76
77 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.
78
79 ==Configuration
80
4b70861 Update rdocs
Russell Quinn authored
81 <b>app/helpers/casein/config_helper.rb</b>
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
82
83 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.
84
4b70861 Update rdocs
Russell Quinn authored
85 <b>views/casein/layouts/_left_navigation.html.erb</b>
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
86
4b70861 Update rdocs
Russell Quinn authored
87 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.
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
88
4b70861 Update rdocs
Russell Quinn authored
89 <b>view/casein/layouts/_right_navigation.html.erb</b>
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
90
91 An ERB partial for the the right navigation tabs. Note that the ‘users’ tab is added automatically for admin users.
92
93 <b>/public/casein/javascripts/custom.js & /public/casein/stylesheets/custom.css</b>
94
4b70861 Update rdocs
Russell Quinn authored
95 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.
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
96
97 ==Customising
98
99 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!
100
101 <b>Rules and conventions</b>
102
4b70861 Update rdocs
Russell Quinn authored
103 * Casein extension controllers and helpers should be namespaced to casein::
104 * Casein extension controllers should derive from Casein::CaseinController and not ApplicationController
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
105 * 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.
106
107 <b>Right bar</b>
108
109 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.
110
4b70861 Update rdocs
Russell Quinn authored
111 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.:
587db8d Update rdocs
Russell Quinn authored
112
a9c01e5 Switched to Authlogic and updated password reset system
Russell Quinn authored
113 <%= content_for :sidebar do %>
587db8d Update rdocs
Russell Quinn authored
114 <li><%= link_to "#{casein_show_icon('table')}Back to list".html_safe, casein_users_path %></li>
115 <% end %>
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
116
14a04f5 Added route alias for /admin
Russell Quinn authored
117 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 http://www.famfamfam.com/lab/icons/silk/
118
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
119 <b>Helper functions</b>
120
121 There are several Casein helper functions that are automatically available in any of your Casein extension views.
122
4b70861 Update rdocs
Russell Quinn authored
123 <i>TODO: These will be documented later. For now, just browse the casein_helper.rb file to see what’s available.</i>
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
124
125 <b>Casein version</b>
126
4b70861 Update rdocs
Russell Quinn authored
127 Your Rails application may discover what version of Casein it is currently running by calling the function:
128
587db8d Update rdocs
Russell Quinn authored
129 casein_get_version_info
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
130
4b70861 Update rdocs
Russell Quinn authored
131 This will return an array with the keys 'major', 'minor' and 'patch'.
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
132
133 <b>Rake tasks</b>
134
4b70861 Update rdocs
Russell Quinn authored
135 There are several Casein Rake tasks available to manage users. To see what is available, list all Rake commands using:
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
136
137 rake -T
138
139 The Casein Rake tasks are all namespaced with ‘casein:’
140
141 ==Scaffolding
142
143 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.
144
145 The command to run the scaffolding generator is:
146
4b70861 Update rdocs
Russell Quinn authored
147 rails g casein:scaffold ModelName [field:type, field:type]
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
148
149 Where:
150
151 * ModelName – The singular name of your model, e.g. customer
152 * 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.
153
154 e.g. a typical scaffolding command might look like:
155
4b70861 Update rdocs
Russell Quinn authored
156 rails g casein:scaffold customer name:string age:integer date_of_birth:date is_male:boolean
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
157
158 There are currently two further command line options that can be added to the end of the generate command:
159
852c02a Fixes to casein:scaffold
Russell Quinn authored
160 --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.
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
161
162 Once the command has been executed, the generator will:
163
4b70861 Update rdocs
Russell Quinn authored
164 * Add a new tab for the model to: app/views/casein/layouts/_left_navigation.html.erb
165 * Create a controller with the name: app/controllers/casein/model_controller.erb
166 * Add views for index, new and show to: app/views/casein/model/
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
167 * 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!
168
169 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.
170
171 <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>
172
173 ===Changing form elements / other helpers
174
175 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.
176
4b70861 Update rdocs
Russell Quinn authored
177 You will find the form used for both new and show in a partial named _fields.html.erb
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
178
4b70861 Update rdocs
Russell Quinn authored
179 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.
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
180
181 casein_text_field form, model, attribute, options = {}
182 casein_password_field form, model, attribute, options = {}
183 casein_text_area form, model, attribute, options = {}
184 casein_text_area_big form, model, attribute, options = {}
185 casein_check_box form, model, attribute, options = {}
186 casein_check_box_group form, model, check_boxes = {}
187 casein_radio_button form, model, attribute, tag_value, options = {}
188 casein_radio_button_group form, model, radio_buttons = {}
189 casein_select form, model, attribute, option_tags, options = {}
2dc2ecb Added support for timezones
Russell Quinn authored
190 casein_time_zone_select form, obj, attribute, option_tags, options = {}
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
191 casein_date_select form, model, attribute, options = {}
2dc2ecb Added support for timezones
Russell Quinn authored
192 casein_time_select form, model, attribute, options = {}
193 casein_datetime_select form, model, attribute, options = {}
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
194 casein_file_field form, model, object_name, attribute, options = {}
195 casein_hidden_field form, model, attribute, options = {}
196
4b70861 Update rdocs
Russell Quinn authored
197 For more information on each function, check the 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:
859d444 Big overhaul for Rails 3 compatibility
Russell Quinn authored
198
199 :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.
200 :casein_button_label – available in casein_radio_button and casein_check_box. Used to give individual buttons their labels.
201 :casein_truncate - may be passed into casein_table_cell_link along with a maximum length to automatically truncate strings and suffix with '...'
202
203 ===Changing form layout
204
205 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.
206
207 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.
208
209 ===Adding styled help blocks
210
211 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.
212
213 ==Acknowledgements
214
215 The icons used in Casein were created by Mark James and are licensed under the Creative Commons Attribution 2.5 License (http://creativecommons.org/licenses/by/2.5/). The full series of icons are available here: http://www.famfamfam.com/lab/icons/silk/
Something went wrong with that request. Please try again.