Tuesday, 20 September 2011

Leonardo: a Rails 3.1 application generator

Update to 1.6 version

I created a new Rails application generator to create 3.1 and automate tasks that are repetitive.

The name of the gem is
leonardo and it consists of two generators:
  1. leolay: to build the layout
  2. leosca: to generate the resource (it replaces original scaffold)



Why create a new generator if there is already the rails scaffold??

The scaffold generator is a handy tool which you can even customize with ease, but is designed for educational purposes and customization is limited to the views. In production I needed something more complete and customizable.

Environment setup and gem installation

Unless we already have one, we create a new ruby environment with rails 3.1:
gem install rails

We can run:
gem install leonardo

...but it is not necessary and I recommend using the process I am about to describe:

create a new application using the template I have prepared, reccomended to facilitate the start-up and to better take advantage of the gem:

rails new NewApp -m http://dl.dropbox.com/u/52600966/template.rb

If the link does not work you can still find the template in the root of the gem

Leonardo relies on the following external gems:
cancan to manage permissions
warden/devise to handle authentication
formtastic for data management
kaminari for paging
rspec/capybara/factory girl/selenium for testing
... and others with whom there is not a close relationship but they are useful to handle other tasks.

The template will propose the adoption of the aforementioned gems, i raccomended to install all answering all "y" or pressing enter when a default is proposed (for example: devise proposes "user" as model name).

It will then run a bundle install to verify the presence of gems and then will perform the various generations, all will last about a minute.

The generation of the layout will ask for confirmation to replace the file en.yml, answer y. I prefer not to force the replacement to allow other executions of the generator leolay if you wanted to update the layout.

At the end you will get an application, "ready to go," allowing them to guide development on the application.

Let's move the application folder and we start the server:cd NewApp
rails s
point your browser at http://localhost:3000 to access the home

If you click on "Sign in" you will be prompted to authenticate (if you included it) for quick access, you can enter:
email: admin@newapp.com
password: abcd1234

Signed in

Creates three users with three different roles (if you have included permission):
  1. admin@newapp.com
  2. manager@newapp.com
  3. user@newapp.com

Of course it's users for purposes related to the development.

We can consult and modify roles access to the file app / models / ability.rb as expected from cancan.

To change the language is enough to send the new one as the value of the lang parameter, eg:http://localhost:3000/?lang=it

Currently it manages language :it and :en. Add support for another language is simple, just add the yml files in the folder where you will find the first two, of course, must have the same tags.

Customize the layout

  • First you replace the logo with your own.
  • You can change the color editing app \ assets \ stylesheets \ stylename.sass (default cloudy). Choosing primary and secondary color, the shades are calculated by sass. 
  • You can customize the paging: Rails g kaminari: views THEME and replace the theme with your favorite theme. Currently available are github and google 
  • You can customize jquery-ui, currently uses a style similar to the lightness 
  • For larger customizations edit the HTML in the templates and layout of individual views. To do this copy the template in the project with Rails g leosca: install

Generate resources

Now we generate some resources leosca using the generator, a sort of custom scaffold:

rails g leosca category name:string active:boolean

rails g leosca product category:references name:string description:text price:decimal released_at:date

To create a nested resource just add the --under=parent for example if we want the product to be nested under category:
rails g leosca product ... --under=category

A resource exists within the parent resource and paths are like this:
http://localhost:3000/categories/1/products

When Leonardo detects the presence of a relationship (such as references or belongs_to) is prepared everything necessary for connecting the resources and also whether the resource is nested:
  • nested paths will be created in the controller, in the views and specs
  • will be updated the list of parent resource with links to related resources
  • the creation and / or modification does not require the selection of products related because the parent resource has already been selected before the consultation.

We then create two new tables to the database including:
rake db:migrate

and we also perform the data population that leosca has prepared for us:
rake db:seed

Listing Categories

The image above shows the case where the product was not nested resource under the category.

Some notes:
  • The export data in CSV currently does not work if you activate the paging ajax, I'm looking for a good way to solve.
  • Into the lists are automatically entered all fields in order to apply the filter, then eliminate those that do not interest us. The filters do not work with sqlite 3 and boolean fields due to a bug in the driver that does not generate a correct sql. Works seamlessly with the SQLServer.
  • Related objects show a link with the name. If the table does not have the field name, is used id which should be replaced with the field that more it represents.
  • Only the paging, the show and destroy operation is managed through ajax.
  • About the users automatically created: admin can do everything, manager all the CRUD operations, user cannot to delete.
  • The field labels are auto inserted but the translation must do it by yourself into config/locales/*.yml

Test

Leonardo creates everything you need for testing, even some additions to test the behavior of ajax sections:

rake spec

I use Firefox on Windows (I have not yet been able to do tests with linux) and I got all green, even in the presence of nested resources, though some combinations may not be covered.

Only A Few Recommendations: it will be opening a new session of firefox which you must set it to full screen otherwise selenium will do hard work to click on links. Sometimes instead, there are lag issues, in case of errors of this kind simply repeat the test.

How to customize the generator

Simply install it in your project and customize it to suit your needs:
rails g leosca:install
is located under lib and any changes will take precedence on the gem



Conclusions


For further information or updates on future developments, please consult the project homepage:
https://github.com/marcomd/Leonardo

Other links:
http://edgeguides.rubyonrails.org/generators.html
http://railscasts.com/episodes/216-generators-in-rails-3
http://railscasts.com/episodes/218-making-generators-in-rails-3
http://railscasts.com/episodes/242-thor
http://rdoc.info/github/wycats/thor/master/Thor
http://textmate.rubyforge.org/thor/Thor/Actions.html
http://railscasts.com/episodes/265-rails-3-1-overview

No comments:

Post a Comment