Cream generators overview

kristianmandrup edited this page May 8, 2011 · 2 revisions

Perhaps the most powerful part of Cream is the set of generators that work to configure your application for your particular requirements.

Full application configuration

The full_config generator is the main generator and attempts to configure an application with Devise, CanCan, Roles and Permits for a given ORM.

As of 2011, it now also supports options to set which class names to use for the main model classes generated, including the abstract User, Role and for relational databases, the model for the join table between User and Role (default: UserRole) – Note: I have an outstanding issue to simply use the habtm pattern (has_and_belongs_to_many) .

The generator will only run if you pass it a valid strategy and orm combination.

1. Create cream.rb initializer – which sets up the roles available to Cream (for use in Roles configuration)
2. Optionally generate default locale files for Cream labels (please provide other translations)
3. Run sub generators
4. Optionally run migrations (currently only for Active Record)

Sub generators

The full_config generator executes the following generators in succession:

1. Cream application configuration
2. Devise configuration
3. Devise customization (optional)
4. CanCan configuration
5. Roles configuration
6. Permits configuration

The order is important. Some steps in this flow requires other steps to have been completed in order to work.

Note: the Devise configuration is split into ‘general configuration’ followed by a special devise users_ generator which sets up User models with devise strategies.

Cream application configuration

1. Removes AR code from application if non-AR ORM is used
2. Adds Welcome controller and view and setup root route if no such exists
3. Adds flash message logic to application layout file (as required by devise)
4. Creates default Guest user class used for users not logged in (with no schema or table)

In case an ORM is specified other than Active Record (AR) the generator will attempt to strip Active Record code from the application by replacing AR specific code from the application.rb file.

Configuration of Root route

For the application to demonstrate that it works in the end, it is ensured that the root route is defined. If not, a root route is inserted which points to Main#index that displays a basic welcome page (all generated).
This Main controller can be set up with a :before filter to require login if the user is not logged in.

before_filter :authenticate_user!

Devise configuration

Consists of:

  • Devise basic configuration
  • Devise user configuration
  • Devise customization

Devise basic configuration

1. Runs devise installer generator (if it hasn’t been run before – i.e no devise.rb initializer present)
2. Configures Devise for ORM chosen (installing relevant ORM adapter for Devise)
3. Inserts default mailer configuration in application.rb (localhost:3000) – change this for production!

Note: As part of this configuration, relevant gem dependencies will be added to the Gemfile and installed via Bundler (same goes for other generators if/when required)

Devise users configuration

1. Creates devise base User model (note: name of model can be customized) if the user model doesn’t already exist
4. Creates devise models for each user type. Each model subclasses the base User model.
5. Creates special devise routes for each user type with code and notes to aid in further customization if needed

Devise customization

The Devise customization step currently supports the customization of :

  • Login credentials
  • Guest user

More can be added in the future. The idea is to make this a set of best practices from the Devise wiki you can choose from and include in your app (for any ORM).

The login credentials can be set to generic to support login with either user name or password. A Guest user can be created to support the “Guest strategy” of the current_user method. The Guest user will have roles API methods stubbed to respond as if it had the role :guest. The Guest user does not and should not have a model, as you normally don’t want to persist Guest users. Please see Guest user for more details on this.

Roles configuration

1. Runs the Roles generator for the ORM selected
2. Replaces the valid_roles_are statement in the base User class as generated by the Roles generator with a reference to the roles available defined in Cream initializer (see Cream app generator)

Permits configuration

1. Runs CanCan permits generator to generate permits for each role for the ORM selected
2. Generates default licenses (you should customize these to suit your own needs)