Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/russellquinn/casein

A lightweight CMS toolkit for Ruby on Rails, based on Bootstrap
https://github.com/russellquinn/casein

Last synced: about 1 month ago
JSON representation

A lightweight CMS toolkit for Ruby on Rails, based on Bootstrap

Awesome Lists containing this project

README 

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



Casein is a Rails 5.x/6.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 5.x/6.x and Ruby 2.4.10 or later.



Casein 5.1.1.5 was the last gem release compatible with Rails 4.x.



==What’s New in 5.5.1



* Suport for Rails 6.1 (fixed deprecated usage of `update_attributes`, which was removed completely from Rails 6.1)



==What’s New in 5.5.0



* Updates minimum version of AuthLogic to 6.1 to resolve compatibility with Ruby 2.7

* Updates minimum version of Ruby to 2.4.10



==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.5.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 protected] [password=your_password]



(square brackets indicate an optional parameter, do not include)



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



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



Casein should now be running!



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



(square brackets indicate an optional parameter, do not include)



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.



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.



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



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



views/casein/layouts/_tab_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/_top_navigation.html.erb



An ERB partial for adding items to the top navigation.



/assets/javascripts/casein/custom.js & /assets/stylesheets/casein/custom.scss



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



/assets/javascripts/casein/auth_custom.js & /assets/stylesheets/casein/auth_custom.scss



These files are added to your app’s /assets directory. They allow you to add custom JavaScript or CSS to the authentication layout in 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!



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.



Sidebar



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

    
  • <%= link_to "#{casein_show_icon('th-list')}Back to list".html_safe, casein_admin_users_path %>
    • 

      <% end %>
    


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


    Helper functions
    


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


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


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


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


    ===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 = {}, html_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 also supports the newer HTML5 form helpers:
    


      casein_color_field form, obj, attribute, options = {}

      casein_search_field form, obj, attribute, options = {}

      casein_telephone_field form, obj, attribute, options = {}

      casein_url_field form, obj, attribute, options = {}

      casein_email_field form, obj, attribute, options = {}

      casein_date_field form, obj, attribute, options = {}

      casein_datetime_field form, obj, attribute, options = {}

      casein_datetime_local_field form, obj, attribute, options = {}

      casein_month_field form, obj, attribute, options = {}

      casein_week_field form, obj, attribute, options = {}

      casein_time_field form, obj, attribute, options = {}

      casein_number_field form, obj, attribute, options = {}

      casein_range_field form, obj, attribute, options = {}
    


    You can even insert custom content directly into the Casein field UI chrome:
    


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