Monday 20 August 2012

Create a management app in few minutes with active admin and rails 3.2




ActiveLeonardo let you create a management application from scratch in few minutes.

The generator is not intended to churn out the finished product but provides a basis from which to start. It creates the skeleton of the application which will cut out a dress and as we know a nice dress should be tailored by hand.


The achievement is remarkable and I recommend you give it a try.


On github there is a short tutorial and here I show you a more descriptive guide to clarify its potential.

I can summarize with this three simple steps:
  1. Create the new app
  2. Adding resources (information to manage)
  3. Starting the web server, the end!


You choose the name, you define the resources, all the remnant is a load of your PC.
My Windows 7 laptop with a second generation i7 and a 7200 rpm hard use about 1 minute. With a desktop and a SSD the operation is almost instantaneous. In any case the generator will create all the necessary in very little time and with minimum effort.

I will create a container of information in this case a rudimentary issue tracker (but could also be a recipe book, a blog, etc..) So we start by creating the application LeoTicket:

rails new LeoTicket -m dl.dropbox.com/u/52600966/active_template.rb

To accept the proposed sections just answer y. I suggest you add everything to better follow this tutorial.
The template allows you to add some basic gem for handling authentication, the permissions, the states ... you can add everything you need. 
If you include the authentication you can choose the name of the resource, the default user is used but you can replace it by any other name (eg Author) as long as you remember to specify it when you create the following resources to allow the generator successfully compile the file permissions. To do this you need to pass the parameter to the generator of the resource, for example:
rails g leosca category name --auth_class=Author


The generator leolay replaces the original file en.yml (initially empty) with his custom, answer y to overwrite it. It is not done automatically if it is not the first generation (eg to update the generator), in this case we have to manually manage the conflicts.

At this point the application is already running and we can verify this by entering the directory of the new application and starting the server:
rails s
Open your web browser and go to the address:
http://localhost:3000/



You will be prompted to authenticate, insert:
admin@leoticket.com
abcd1234

And you will be redirected to the dashboard:



It has been already created the management of the users and this is the starting point for developing the application.. We provide resources thus creating two category:

In the REST architecture, a resource is largely attributable to a table on a database.

rails g leosca category name

Since Rails 3.2, the fields are considered as string if type is omitted so that is no longer necessary to specify it.

and now we can add the resource ticket:

rails g leosca ticket category:references title description:text state:integer

category:references tells to Rails to create an association with that resource: it creates a foreign key category_id and an index that uses to manage the relationship, in the ticket model there will be:

belongs_to :category 

means that the ticket can query its category but not vice versa, if we want to query all the ticket you need to enter in the template category:

has_many :tickets

Let's go back to the project and check the result but first we have to apply to the db in that the generator has created for us:

rake db:migrate
==  CreateCategories: migrating ===============================================
-- create_table(:categories)
   -> 0.1430s
==  CreateCategories: migrated (0.1440s) ======================================
==  CreateTickets: migrating ==================================================
-- create_table(:tickets)
   -> 0.0040s
-- add_index(:tickets, :category_id)
   -> 0.0010s
==  CreateTickets: migrated (0.0070s) =========================================

in order to facilitate the development stage, are generated generic records that you may also update before insert in the db to create more real cases:

#db/seeds.rb
[
  { :id => 1, :name => "Bug" },
  { :id => 2, :name => "Update" },
  { :id => 3, :name => "Implementation" },
].each do |fields|
  category = Category.new fields
  category.id = fields[:id]
  category.save
end

Ticket.create([
  {  :category_id => 1,  :title => "New bug",  :description => "I had a bug, damn!",  :state => 10 },
  {  :category_id => 2,  :title => "Change this section",  :description => "I require a change",  :state => 10 },
  {  :category_id => 3,  :title => "New section",  :description => "I need a new resource to manage ...",  :state => 10 },
])


We want the id of the category is fixed and does not automatically attributed so we specify it and add it to the db with an alternative way to what is proposed by the generator. I do not know if there is a better way to do it.

Before proceeding we add the attribute category_id to the list of accessible attributes:
#app/models/ticket.rb

class Ticket < ActiveRecord::Base
  belongs_to :category
  attr_accessible :description, :state, :title, :category_id
end

And now we add these records to the database:
rake db:seed

If you receive the following error:
rake aborted!
Can't mass-assign protected attributes: category_id
You have not added category_id to the list of accessible attributes.


If you receive a "primary key violation" error:
rake aborted!
SQLite3::ConstraintException: PRIMARY KEY must be unique
You're probably running the import again, comments the categories in the file seeds.rb

You can run it multiple times to add more records.

The test application is ready, restart the server and update the browser:
 rails s
 http://localhost:3000/


Easy, not it?

The next steps are:
  1. Developing localization
  2. Customize permissions
  3. Customize activeadmin views
  4. Develop models
  5. Create any alternative frontend


Localization

The application comes localized in English (default) and Italian (but you can extend the generator pretty easily) and just change the tags within files config/locales/*.yml


Customize permissions

Using cancan, edit the permissions is very simple, it is all contained within the file app/models/ability.rb


Customize views

Also Active Admin customizations are very simple. Everything is concentrated in the file relative to resource: list, consultation, form data, exports etc..
Each file is located in the folder app/admin/*.rb

We can customize many things:

ActiveAdmin.register Ticket do
  menu :if => proc{ can?(:read, Ticket) }
  
  #change the default sort
  config.sort_order = 'id_asc'
  
  #add scopes: lists with preset filters
  scope :open
  scope :closed
  
  controller do
    load_resource :except => :index
    authorize_resource
  end

  #choose the column in the list
  index do
    id_column
    column :category
    column :title
    column :description
    column I18n.t('attributes.ticket.state'), :sortable => :state do |ticket|
      span ticket.human_state_name.capitalize, :class => "status #{ticket.state_name}"
    end
    default_actions
  end
  
  #...in the show
  show do |ticket|
    attributes_table do
      row :category
      row :title
      row :description
      row I18n.t('attributes.ticket.state') do
        span ticket.human_state_name.capitalize, :class => "status #{ticket.state_name}"
      end
    end
  end
  
  #...the form
  form do |f|
    f.inputs do
      f.input :category
      f.input :title
      f.input :description
      f.input :state, :as => :select, :collection => Ticket.state_machine.states.map{|s|[s.human_name.capitalize, s.value]}, :include_blank => false
    end
    f.buttons
  end
  
  #...and customize the export
  csv do
    column I18n.t('models.category') do |ticket| 
      ticket.category.try(:name)
    end
    column :title
    column :description
    column I18n.t('attributes.ticket.state') do |ticket|
      ticket.human_state_name.capitalize
    end
    column(I18n.t('attributes.created_at')) { |user| user.created_at.strftime("%d/%m/%Y") }
    column(I18n.t('attributes.updated_at')) { |user| user.updated_at.strftime("%d/%m/%Y") }
  end
end
...and many other things for which I refer you to the official documentation of ActiveAdmin.

Pay attention to load related resources! (eager loading)
In rails is automatic but if it is not indicated to load them in advance, they will be retrieved when needed.

If we check in log / development.log will notice three individual queries to the archive of the categories, one for each ticket for which you show the name:

 
  [1m [36mCategory Load (1.0ms) [0m   [1mSELECT "categories".* FROM "categories" WHERE "categories"."id" = 1 LIMIT 1 [0m
  [1m [35mCategory Load (1.0ms) [0m  SELECT "categories".* FROM "categories" WHERE "categories"."id" = 2 LIMIT 1
  [1m [36mCategory Load (1.0ms) [0m   [1mSELECT "categories".* FROM "categories" WHERE "categories"."id" = 3 LIMIT 1 [0m


For small lists is not a big problem but instead it is for large amounts of data, such as extractions csv format, so you need a little change on the controller. ActiveAdmin relies on Inherited Resources and you must act in this way:

ActiveAdmin.register Ticket do
  #...[CUT]...
  controller do
    load_resource :except => :index
    authorize_resource
    def index
      super do |format|
        format.html { @tickets = @tickets.includes(:category) }
        format.csv { @tickets = @tickets.includes(:category) }
      end
    end
  end
  #...[CUT]...
end


If you now check the log again you find a single query:
  [1m [36mCategory Load (0.0ms) [0m   [1mSELECT "categories".* FROM "categories" WHERE "categories"."id" IN (1, 2, 3) [0m

Develop models

Models management is also very simple. We modify the related files in app / models / *. Rb adding validations, scopes, state management, etc..


class Ticket < ActiveRecord::Base
  belongs_to :category
  attr_accessible :description, :state, :title, :category_id
  
  state_machine :state, :initial => :new do
    state :new,           :value => 10
    state :working,       :value => 20
    state :canceled,      :value => 30
    state :completed,     :value => 40
  end
  
  OPEN_STATES =  [state_machine.states[:new].value, 
                  state_machine.states[:working].value]
  CLOSED_STATES =  [state_machine.states[:canceled].value, 
                    state_machine.states[:completed].value]
                  
  validates :state, :inclusion => { :in => state_machine.states.map(&:value),
                                       :message => "%{value} is not a valid value! Available states: #{state_machine.states.map(&:value).compact.join(', ')}" }, :allow_nil => true

  scope :open, where(:state => OPEN_STATES)
  scope :closed, where(:state => CLOSED_STATES)
end

And here is the customized version:

Visualizzazione
Form dati
Lista

For the moment thats all

If you like this article take a look at my sponsors, thank you!

Thursday 23 February 2012

Leonardo: update to 1.10 version

With 1.10 version I introduced the following changes:


  • In the index page, I moved the filters on the right and layout now seems more clean. For numeric fields, and dates can be filtered more easily by inserting the operator <, >, <>, <= o >= directly in the text field.
  • The generator detects the field named "state" and imposed a series of operations to manage the state (intended as the process status) in accordance with the gem state_machine.
  • Still in the index page, clicking the arrow beside the name of the nested resource, will perform an ajax call that adds information dynamically under the parent resource. Clicking on the name instead, you run a http call as before.
  • I improved the automatic routes creation

But we get into detail with some examples.
Create a new application and name it as suggested by your imagination, I call it Leonardo:

rails new Leonardo -m template.rb

At the moment is recommended to use the template locally, so download it or take it from the root where you installed the gem.

Respond y everything you want to include. You can choose whether to install the gems locally, by specifying the name of the folder, or if you install it in the default path by simply pressing Enter. I also added the choise to install activeadmin and if you decide to include it you need:

rename the file app\assets\stylesheets\application.css to application.css.scss

inside that file remove the line
*= require_tree .

and add at the bottom
@import "cloudy";
cloudy is the style name, currently also the only one

if we now start the server and visit the address
http://127.0.0.1:3000

You should see the graphic layout without defects created by the interference of the activeadmin css
and here
http://127.0.0.1:3000/admin

you can sign in activeadmin using the default credentials as currently reported in the documentation

 admin@example.com e password

will be accessible only to the dashboard and I would refer you to the documentation for how to use it.
To sign in the leonardo interface instead, you have the usual three users with three different roles that can be managed as provided by the gem cancan:user@leonardo.com
manager@leonardo.com
admin@leonardo.com

replace leonardo with the name of your application
user@yourapp.com

for all these the password is รจ abcd1234

now create the product resource taking advantage of rails 3.2:

rails g leosca product name description:text 'price:decimal{9,2}' 'in_stock:integer{2}' available:boolean from:date 'state:integer{1}'

create the table
rake db:migrate

If we added the state field, Leonardo tries to involve the gem state_machine so you have to add the states into the model:

class Product < ActiveRecord::Base
  state_machine :state, :initial => :new do
    state :new,         :value => 10
    state :working,     :value => 20
    state :completed,   :value => 30
    state :closed,      :value => 40
    state :canceled,    :value => 50
  end
end

before populate the new table, edit the file db \ seed.rb customizing state values ​​as included in the model after which we can perform:
rake db:seed

Visit the product list:


Note the filter on the price for values ​​above 10 pound, with the operator directly in the text box before the value

Note also the State column with the default color and description I18n both easily customizable.

To change the language, you just pass the parameter lang anywhere in the application:
http://127.0.0.1:4000/products?lang=it

will change the standard text and the names will be translated manually into the file:
\config\locales\it.yml

In edit view, the states can be update by a select box:



Now create comment, a nested resource under product:

rails g leosca comment product:references body:text approved:boolean 'score:integer{1}' --under=product

Also in this case, before to populate the table you can customize the file db \ seed.rb inserting for example more records associated with the first product. Furthermore I usually comment out the entries have already been used to avoid creating duplicates, then perform again:
rake db:seed

if we visit the previous list, you will find the reference to nested resources and if you click on the small arrow next to the name the list will be updated directly with the list of related resource:


Of course leonardo provides only a starting point and nothing more than an unconventional scaffolds

Unfortunately, I was not able to update rspec tests which do not pass in the presence of the state field, but will be in next version.

I hope that this work will come in handy. There is still much to do and anyone interested to help me out can send me an email.