Jerry Shen

Using APN Sender to Send Push Notifications to Your IOS Devices

2012-02-14T00:00:00+00:00

Happy Valentine's Day.

Recently, I have a project based on both ruby on rails and iPhone applications, there is a requirement that is pushing notifications from server side to iPhone client, and I built a server component of an iPhone application in Ruby with apn_sender.

I want to send background notifications through Apple Push Notification servers, which I was stumbled at first, to setup the plugin is very simple, but I couldn't receive any notifications after sending them, it's very weird that everything seemed right. After further testing and trying, I found the problem is format of IOS Device Token, Because I encoded and stored it in mongodb as a Base64 string, So I have to decode it to hexadecimal.

APN Sender is based on Resque and Redis, so I wrote a script to skip the Resque Queue to make development easier.

    require 'base64'

    ios_device_token = User.where(:username => 'Jerry').first.ios_device_token
    token = Base64.decode64(ios_device_token).unpack('H*').first.scan(/\w{8}/).join(' ')

    notification = APN::Notification.new(token, { :alert => 'Hey, how are you?', :sound => true, :badge => 9 })

    sender = APN::Sender.new(:verbose => true, :environment => 'production')
    sender.send_to_apple(notification)

The app installed on my iPhone is based on Ad Hoc, it's very important that you should set the environment to production when you initialize the sender object, otherwise you would receive nothing.

Solution for System Time Error When Compiling Packages

2012-01-02T00:00:00+00:00

I was trying to recompile Nginx today, But I got a very wierd error that I couldn't pass it.

This is the error information,

configure: error: newly created file is older than distributed files!
Check your system clock

It seems that the file I created is older than the distributed files, then I checked the system clock, I found the timezone was wrong, so I reseted the timezone with:

sudo dpkg-reconfigure tzdata

Choose your current timezone, and it will update your system clock.

Awesome, it works.

Counter Cache Reset for Counters

2012-01-01T00:00:00+00:00

When you want to implement counter cache, how to handle the counters for the old data? Generally you will add a migration which runs a script to update all the counts, unfortunately you wil get an error, because the column is readonly, you can't update this column in a normal way.

Model

    class Post < ActiveRecord::Base
      belongs_to :category, :counter_cache => :resources_count
    end

Incorrect way

    class InitializeResourcesCountForCategories < ActiveRecord::Migration
      def up
        Category.find_each do |cat|
          cat.update_attribute(:resources_count => cat.posts.count)
        end
      end
    end

You should be using User.reset_counters to do this

    class InitializeResourcesCountForCategories < ActiveRecord::Migration
      def up
        Category.find_each do |cat|
          Category.reset_counters(cat.id, :posts)
        end
      end
    end

Method Missing Best Practice

2011-12-21T00:00:00+00:00

Method missing allows access to the object attributes, which are held in the @attributes hash, as though they were first-class methods.

If you call a method that doesn’t exist, Ruby will call the method_missing method, and pass the name of the method and any arguments you supplied, which means you can dynamically handle the method.

Here we go, for example, we have a messages table:

    create_table "messages", :force => true do |t|
      t.text     "content"
      t.boolean  "is_read",     :default => false
      t.boolean  "is_archived", :default => false
      t.integer  "post_id"
      t.integer  "user_id"
      t.datetime "created_at"
      t.datetime "updated_at"
    end

As a general way, many people will define some following methods

    class Message < ActiveRecord::Base
      
      def is_read?
        !!is_read
      end
      
      def is_archived?
        !!is_archived
      end
      
      def mark_as_read!
        update_attribute(:is_read, true)
      end
      
      def mark_as_unread!
        update_attribute(:is_read, false)
      end
      
      def mark_as_archived!
        update_attribute(:is_archived, true)
      end
      
      def mark_as_unarchived!
        update_attributes(:is_archived, false)
      end
      
    end

Wow, this makes your code ugly, we can use method missing instead of these all methods

    def method_missing(symbol, *args)
      case symbol
        when /^is_(un)?(.*)\?/
          eval "#{$1 ? '!' : '!!'}is_#{$2}"
        when /^mark_as_(un)?(.*)!/
          update_attribute :"is_#{$2}", ($1 ? false : true)
      else
        super
      end
    end

When you call is_[string] method or mark_as_[string] method, as you can see, there is definitely no is_[string] or mark_as_[string] method, yet Rails is smart enough to call the method with the correct parameters, What we have done is to run a regular expression against the name of the method, and if it matches the pattern is_[string] or mark_as_[string] then it calls the method with the [string] part as the first parameter and the first argument as the second parameter. Pretty powerful, don't you think?

Running Multiple Rails Versions by Standalone Gemsets with Passenger

2011-12-13T00:00:00+00:00

There was a case before that troubled me a lot, I have many projects to run on production server that each one has a different rails version, and each project should be run in a standalone gemset with RVM, I have implemented it before, and now, I will make a guide to show you guys hwo to run multiple rails versions with phusion passenger and RVM.

Just give a example to you guys, I have project 'foo' run with rails 3.0.10 and project 'bar' run with rails 3.1.3 which is the latest version for rails 3, As of Phusion Passenger 3 you can run all components as Phusion Passenger.

The setup that we currently recommend is to combine Phusion Passenger for Nginx, with Phusion Passenger Standalone. All applications that are to use a different gemset can be served separately through Phusion Passenger Standalone and hook into the main web server via a setup load paths configuration.

To run project 'foo' under gemset 'foo', you need to do several simple configurations below:

First you need to add a .rvmrc file to your rails root directory, I think every one may use this, if you don'y use rvmrc, never mind, just create it by yourself with

$ rvm --rvmrc --create 1.9.3@foo

Then the .rvmrc file will be created, yeah, that's cool for the new functionanlity by RVM.

Create config/setup_load_paths.rb file in config directory, prefill with:

    if ENV['MY_RUBY_HOME'] && ENV['MY_RUBY_HOME'].include?('rvm')
      begin
        rvm_path     = File.dirname(File.dirname(ENV['MY_RUBY_HOME']))
        rvm_lib_path = File.join(rvm_path, 'lib')
        $LOAD_PATH.unshift rvm_lib_path
        require 'rvm'
        RVM.gemset_use! 'foo'
      rescue LoadError
        # RVM is unavailable at this point.
        raise "RVM ruby lib is currently unavailable."
      end
    end

    # Pick the lines for your version of Bundler
    # If you're not using Bundler at all, remove all of them

    # Require Bundler 1.0 
    ENV['BUNDLE_GEMFILE'] = File.expand_path('../Gemfile', File.dirname(__FILE__))
    require 'bundler/setup'

    # Require Bundler 0/9
    # if File.exist?(".bundle/environment.rb")
    #   require '.bundle/environment'
    # else
    #   require 'rubygems'
    #   require 'bundler'
    #   Bundler.setup
    # end

The same as project bar, the only difference is set a difference gemset.

After these two configuration steps, you can deploy your project to server now, if there is no gemset named 'foo' or 'bar on your server, you will got a error by running cap deploy:setup

ERROR: Gemset 'foo' does not exist, rvm gemset create 'foo' first.

Follow the error message, you need to create a gemset named 'foo' on your server first.

$ rvm use 1.9.3
$ rvm gemset create foo

Then the foo gemset will be created, you can deploy your project to your server now,

$ cap deploy:setup
$ cap deploy

'bundle install' will automatically install all the gems under 'foo' gemset and run server with the right rails version.

Here is the deploy script:

    $:.unshift(File.expand_path('./lib', ENV['rvm_path']))
    require "rvm/capistrano"
    ssh_options[:forward_agent] = true

    set :application, "foo"
    set :rvm_ruby_string, "1.9.3@#{application}"
    set :rvm_path, "/home/jerry/.rvm"
    set :rvm_bin_path, "/home/jerry/.rvm/bin"
    set :rvm_trust_rvmrcs_flag, 1

    set :scm, :git
    set :repository, "your_git_repo_url_here"
    set :branch, "master"

    set :deploy_to, "your_deploy_path_here/#{application}"
    set :user, "jerry"
    set :use_sudo, false
    server "your_server_domain_or_ip_here", :app, :web, :db, :primary => true
    set :deploy_via, :copy

    task :configure, :roles => :web do
      run "ln -s #{shared_path}/config/database.yml #{current_release}/config/database.yml"
      run "cd #{current_release}; bundle install --without development test"
    end

    task :trust_rvmrc, :roles => :web do
      run "rvm rvmrc trust #{current_release}"
    end

    after "deploy:update_code", :trust_rvmrc
    after 'deploy:update_code', :configure

Wish you happy with your deployment.

Rails Style Guide

2011-12-12T00:00:00+00:00

Abstract

This guide is copy from bbatsov's work.

The goal of this guide is to present a set of best practices and style prescriptions for Ruby on Rails 3 development. It's a complementary guide to the already existing community-driven Ruby coding style guide.

While in the guide the section Testing Rails applications is after Developing Rails applications I truly believe that Behaviour-Driven Development (BDD) is the best way to develop software. Keep that in mind.

Rails is an opinionated framework and this is an opinionated guide. In my mind I'm totally certain that RSpec is superior to Test::Unit, Sass is superior to CSS and Haml (Slim) is superior to Erb. So don't expect to find any Test::Unit, CSS or Erb advice in here.

Some of the advice here is applicable only to Rails 3.1.

You can generate a PDF or an HTML copy of this guide using Transmuter.

Developing Rails Applications
- Configuration
- Routing
- Controllers
- Models
  - ActiveRecord
- Migrations
- Views
- Assets
- Mailers
- Bundler
- Priceless Gems
- Flawed Gems
- Managing processes
Testing Rails Applications
- Cucumber
- RSpec
  - Views
  - Contollers
  - Models
  - Mailers
  - Uploaders
Further Reading
Contributing
Spread the word

Developing Rails applications

Configuration

Put custom initialization code in config/initializers. The code in initializers executes on application startup.
The initialization code for each gem should be in a separate file with the same name as the gem, for example carrierwave.rb, rails_admin.rb, etc.
Adjust accordingly the settings for development, test and production environment (in the corresponding files under config/environments/)
- Mark additional assets for precompilation (if any):

        # config/environments/production.rb
        # Precompile additional assets (application.js, application.css, and all non-JS/CSS are already added)
        config.assets.precompile += %w( rails_admin/rails_admin.css rails_admin/rails_admin.js )

While not strictly related to style, in order to use carrierwave for the files upload and fog for file storage, some configuration needs to be applied in the config/initializers/carrierwave.rb file:

    # config/initializers/carrierwave.rb

    # Store the files locally for test environment
    if Rails.env.test?
      CarrierWave.configure do |config|
        config.storage = :file
        config.enable_processing = false
      end
    end

    # Using Amazon S3 for Development and Production
    if Rails.env.development? || Rails.env.production?
      CarrierWave.configure do |config|
        config.root = Rails.root.join('tmp')
        config.cache_dir = 'uploads'

        config.storage = :fog
        config.fog_credentials = {
            provider: 'AWS',
            aws_access_key_id: 'your_access_key_id',
            aws_secret_access_key: 'your_secret_access_key',
        }
        config.fog_directory = 'your_bucket'
      end
    end

Do not use fog for the test environment, use file storage instead.
Use fog for the development environment. This will prevent unexpected problems on production.

Routing

When you need to add more actions to a RESTful resource (do you really need them at all?) use member and collection routes.

    # bad
    get 'subscriptions/:id/unsubscribe'
    resources :subscriptions

    # good
    resources :subscriptions do
      get 'unsubscribe', :on => :member
    end

    # bad
    get 'photos/search'
    resources :photos

    # good
    resources :photos do
      get 'search', :on => :collection
    end

If you need to define multiple member/collection routes use the alternative block syntax.

    resources :subscriptions do
      member do
        get 'unsubscribe'
        # more routes
      end
    end

    resources :photos do
      collection do
        get 'search'
        # more routes
      end
    end

Use nested routes to express better the relationship between ActiveRecord models.

    class Post < ActiveRecord::Base
      has_many :comments
    end

    class Comments < ActiveRecord::Base
      belongs_to :post
    end

    # routes.rb
    resources :posts do
      resources :comments
    end

Use namespaced routes to group related actions.

    namespace :admin do
      # Directs /admin/products/* to Admin::ProductsController
      # (app/controllers/admin/products_controller.rb)
      resources :products
    end

Never use the legacy wild controller route. This route will make all actions in every controller accessible via GET requests.

    # very bad
    match ':controller(/:action(/:id(.:format)))'

Controllers

Keep the controllers skinny - they should only retrieve data for the view layer and shouldn't contain any business logic (all the business logic should naturally reside in the model).
Each controller action should (ideally) invoke only one method other than an initial find or new.
Share no more than two instance variables between a controller and a view.

Models

Introduce non-ActiveRecord model classes freely.
Name the models with meaningful (but short) names without abbreviations.

ActiveRecord

Avoid altering ActiveRecord defaults (table names, primary key, etc) unless you have a very good reason (like a database that's not under your control).
Group macro-style methods (has_many, validates, etc) in the beginning of the class definition.
Always use the new "sexy" validations.
When a custom validation is used more than once or the validation is some regular expression mapping, create a custom validator file.

    # bad
    class Person
      validates :email, format: { with: /^([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})$/i }
    end

    # good
    class EmailValidator < ActiveModel::EachValidator
      def validate_each(record, attribute, value)
        record.errors[attribute] << (options[:message] || 'is not a valid email') unless value =~ /^([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})$/i
      end
    end


    class Person
      validates :email, email: true
    end

All custom validators should be moved to a shared gem.
Use named scopes freely.
When a named scope, defined with a lambda and parameters, becomes too complicated it is preferable to make a class method instead which serves the same purpose of the named scope and returns and ActiveRecord::Relation object.
Beware of the behavior of the update_attribute method. It doesn't run the model validations (unlike update_attributes) and could easily corrupt the model state.

Migrations

Keep the schema.rb under version control.
Use rake db:schema:load instead of rake db:migrate to initialize an empty database.
Avoid setting defaults in the tables themselves. Use the model layer instead.

    def amount
      self[:amount] or 0
    end

While the use of `self[:attr_name]` is considered fairly idiomatic,
you might also consider using the slightly more verbose (and arguably more
readable) `read_attribute` instead:

    def amount
      read_attribute(:amount) or 0
    end

When writing constructive migrations (adding tables or columns), use the new Rails 3.1 way of doing the migrations - use the change method instead of up and down methods.

Views

Never call the model layer directly from a view.
Never make complex formatting in the views, export the formatting to a method in the view helper or the model.
Mitigate code duplication by using partial templates and layouts.
Add client side validation for the custom validators. The steps to do this are:
- Declare a custom validator which extends ClientSideValidations::Middleware::Base

    module ClientSideValidations::Middleware
      class Email < Base
        def response
          if request.params[:email] =~ /^([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})$/i
            self.status = 200
          else
            self.status = 404
          end
          super
        end
      end
    end

Create a new file public/javascripts/rails.validations.custom.js.coffee and add a reference to it in your application.js.coffee file:

        # app/assets/javascripts/application.js.coffee
        #= require rails.validations.custom

Add your client-side validator:

        #public/javascripts/rails.validations.custom.js.coffee
        clientSideValidations.validators.remote['email'] = (element, options) ->
          if $.ajax({
            url: '/validators/email.json',
            data: { email: element.val() },
            async: false
          }).status == 404
            return options.message || 'invalid e-mail format'

Assets

Use the assets pipeline to leverage organization within your application.

Reserve app/assets for custom stylesheets, javascripts, or images.
Third party code such as jQuery or bootstrap should be placed in vendor/assets.
When possible, use gemified versions of assets (e.g. jquery-rails).

Mailers

Name the mailers SomethingMailer. Without the Mailer suffix it isn't immediately apparent what's a mailer and which views are related to the mailer.
Provide both HTML and plain-text view templates.
Enable errors raised on failed mail delivery in your development environment. The errors are disabled by default.

    # config/environments/development.rb

    config.action_mailer.raise_delivery_errors = true

Use smtp.gmail.com for SMTP server in the development environment (unless you have local SMTP server, of course).

    # config/environments/development.rb

    config.action_mailer.smtp_settings = {
      address: 'smtp.gmail.com',
      # more settings
    }

Provide default settings for the host name.

    # config/environments/development.rb
    config.action_mailer.default_url_options = {host: "#{local_ip}:3000"}


    # config/environments/production.rb
    config.action_mailer.default_url_options = {host: 'your_site.com'}

    # in your mailer class
    default_url_options[:host] = 'your_site.com'

If you need to use a link to your site in an email, always use the _url, not _path methods. The _url methods include the host name and the _path methods don't.

    # wrong
    You can always find more info about this course
    = link_to 'here', url_for(course_path(@course))

    # right
    You can always find more info about this course
    = link_to 'here', url_for(course_url(@course))

Format the from and to addresses properly. Use the following format:

    # in your mailer class
    default from: 'Your Name <info@your_site.com>'

Make sure that the e-mail delivery method for your test environment is set to test:

    # config/environments/test.rb

    config.action_mailer.delivery_method = :test

The delivery method for development and production should be smtp:

    # config/environments/development.rb, config/environments/production.rb

    config.action_mailer.delivery_method = :smtp

Bundler

Put gems used only for development or testing in the appropriate group in the Gemfile.
Use only established gems in your projects. If you're contemplating on including some little-known gem you should do a careful review of its source code first.
OS-specific gems will by default result in a constantly changing Gemfile.lock for projects with multiple developers using different operating systems. Add all OS X specific gems to a darwin group in the Gemfile, and all Linux specific gems to a linux group:

    # Gemfile
    group :darwin do
      gem 'rb-fsevent'
      gem 'growl'
    end

    group :linux do
      gem 'rb-inotify'
    end

To require the appropriate gems in the right environment, add the
following to `config/application.rb`:

    platform = RUBY_PLATFORM.match(/(linux|darwin)/)[0].to_sym
    Bundler.require(platform)

Do not remove the Gemfile.lock from version control. This is not some randomly generated file - it makes sure that all of your team members get the same gem versions when they do a bundle install.

Priceless Gems

One of the most important programming principles is "Don't reinvent the wheel!". If you're faced with a certain task you should always look around a bit for existing solutions, before unrolling your own. Here's a list of some "priceless" gems (all of them Rails 3.1 compliant) that are useful in many Rails projects:

rspec-rails - RSpec is a replacement for Test::MiniTest. I cannot recommend highly enough RSpec. rspec-rails provides Rails integration for RSpec.
cucumber-rails - Cucumber is the premium tool to develop feature tests in Ruby. cucumber-rails provides Rails integration for Cucumber.
haml - HAML is a concise templating language, considered by many (including yours truly) to be far superior to Erb.
haml-rails - haml-rails provides Rails integration for Haml.
slim - Slim is a concise templating language, considered by many far superior to HAML (not to mention Erb). The only thing stopping me from using Slim massively is the lack of good support in major editors/IDEs. Its performance is phenomenal.
simple_form - once you've used simple_form (or formtastic) you'll never want to hear about Rails's default forms. It has a great DSL for building forms and no opinion on markup.
fabrication - a great fixture replacement (editor's choice).
factory_girl - an alternative to fabrication. Nice and mature fixture replacement. Spiritual ancestor of fabrication.
machinist - Fixtures aren't fun. Machinist is.
faker - handy gem to generate dummy data (names, addresses, etc).
guard - fantastic gem that monitors file changes and invokes tasks based on them. Loaded with lots of useful extension. Far superior to autotest and watchr.
spork - A DRb server for testing frameworks (RSpec / Cucumber currently) that forks before each run to ensure a clean testing state. Simply put it preloads a lot of test environment and as consequence the startup time of your tests in greatly decreased. Absolute must have!
simplecov - code coverage tool. Unlike RCov it's fully compatible with Ruby 1.9. Generates great reports. Must have!
simplecov-rcov - RCov formatter for SimpleCov. Useful if you're trying to use SimpleCov with the Hudson contininous integration server.
capybara - Capybara aims to simplify the process of integration testing Rack applications, such as Rails, Sinatra or Merb. Capybara simulates how a real user would interact with a web application. It is agnostic about the driver running your tests and currently comes with Rack::Test and Selenium support built in. HtmlUnit, WebKit and env.js are supported through external gems. Works great in combination with RSpec & Cucumber.
devise - Devise is full-featured authentication solution for Rails applications. In most cases it's preferable to use devise to unrolling your custom authentication solution.
carrierwave - the ultimate file upload solution for Rails. Support both local and cloud storage for the uploaded files (and many other cool things). Integrates great with ImageMagick for image post-processing.
kaminari - Great paginating solution.
feedzirra - Very fast and flexible RSS/Atom feed parser.
sunspot - SOLR powered full-text search engine.
client_side_validations - Fantastic gem that automatically creates JavaScript client-side validations from your existing server-side model validations. Highly recommended!
rails_admin - With Rails Admin the creating of admin interface for your Rails app is child's play. You get a nice dashboard, CRUD UI and lots more. Very flexible and customizable.

This list is not exhaustive and other gems might be added to it along the road. All of the gems on the list are field tested, have active development and community and are known to be of good code quality.

Flawed Gems

This is a list of gems that are either problematic or superseded by other gems. You should avoid using them in your projects.

rmagick - this gem is notorious for its memory consumption. Use minimagick instead.
autotest - old solution for running tests automatically. Far inferior to guard and watchr.
rcov - code coverage tool, not compatible with Ruby 1.9. Use SimpleCov instead.
therubyracer - the use of this gem in production is strongly discouraged as it uses a very large amount of memory.

This list is also a work in progress. Please, let me know if you know other popular, but flawed gems.

Managing processes

If your projects depends on various external processes use foreman to manage them.

Testing Rails applications

The best approach to implementing new features is probably the BDD approach. You start out by writing some high level feature tests (generally written using Cucumber), then you use these tests to drive out the implementation of the feature. First you write view specs for the feature and use those specs to create the relevant views. Afterwards you create the specs for the controller(s) that will be feeding data to the views and use those specs to implement the controller. Finally you implement the models specs and the models themselves.

Cucumber

Tag your pending scenarios with @wip (work in progress). These scenarios will not be taken into account and will not be marked as failing. When finishing the work on a pending scenario and implementing the functionality it tests, the tag @wip should be removed in order to include this scenario in the test suite.
Setup your default profile to exclude the scenarios tagged with @javascript. They are testing using the browser and disabling them is recommended to increase the regular scenarios execution speed.
Setup a separate profile for the scenarios marked with @javascript tag.
- The profiles can be configured in the cucumber.yml file.

    # definition of a profile:
    profile_name: --tags @tag_name

A profile is run with the command:

cucumber -p profile_name
If using fabrication for fixtures replacement, use the predefined fabrication steps
Do not use the old web_steps.rb step definitions! The web steps were removed from the latest version of Cucumber. Their usage leads to the creation of verbose scenarios that do not properly reflect the application domain.
When checking for the presence of an element with visible text (link, button, etc.) check for the text, not the element id. This can detect problems with the i18n.
Create separate features for different functionality regarding the same kind of objects:

    # bad
    Feature: Articles
    # ... feature  implementation ...

    # good
    Feature: Article Editing
    # ... feature  implementation ...

    Feature: Article Publishing
    # ... feature  implementation ...

    Feature: Article Search
    # ... feature  implementation ...

Each feature has three main components
- Title
- Narrative - a short explanation what the feature is about.
- Acceptance criteria - the set of scenarios each made up of individual steps.
The most common format is known as the Connextra format.

    In order to [benefit] ...
    A [stakeholder]...
    Wants to [feature] ...

This format is the most common but is not required, the narrative can be free text depending on the complexity of the feature.

Use Scenario Outlines freely to keep the scenarios DRY.

    Scenario Outline: User cannot register with invalid e-mail
      When I try to register with an email "<email>"
      Then I should see the error message "<error>"

    Examples:
      |email         |error                 |
      |              |The e-mail is required|
      |invalid email |is not a valid e-mail |

The steps for the scenarios are in .rb files under the step_definitions directory. The naming convention for the steps file is [description]_steps.rb. The steps can be separated into different files based on different criterias. It is possible to have one steps file for each feature (home_page_steps.rb). There also can be one steps file for all features for a particular object (articles_steps.rb).
Use multiline step arguments to avoid repetition

    Scenario: User profile
      Given I am logged in as a user "John Doe" with an e-mail "user@test.com"
      When I go to my profile
      Then I should see the following information:
        |First name|John         |
        |Last name |Doe          |
        |E-mail    |user@test.com|

    # the step:
    Then /^I should see the following information:$/ do |table|
      table.raw.each do |field, value|
        find_field(field).value.should =~ /#{value}/
      end
    end

Use compound steps to keep the scenario DRY

    # ...
    When I subscribe for news from the category "Technical News"
    # ...

    # the step:
    When /^I subscribe for news from the category "([^"]*)"$/ do |category|
      steps %Q{
        When I go to the news categories page
        And I select the category #{category}
        And I click the button "Subscribe for this category"
        And I confirm the subscription
      }
    end

Always use the Capybara negative matchers instead of should_not with positive, they will retry the match for given timeout allowing you to test ajax actions. See Capybara's README for more explanation

RSpec

Use just one expectation per example.

    # bad
    describe ArticlesController do
      #...

      describe 'GET new' do
        it 'assigns new article and renders the new article template' do
          get :new
          assigns[:article].should be_a_new Article
          response.should render_template :new
        end
      end

      # ...
    end

    # good
    describe ArticlesController do
      #...

      describe 'GET new' do
        it 'assigns a new article' do
          get :new
          assigns[:article].should be_a_new Article
        end

        it 'renders the new article template' do
          get :new
          response.should render_template :new
        end
      end

    end

Make heavy use of describe and context
Name the describe blocks as follows:
- use "description" for non-methods
- use pound "#method" for instance methods
- use dot ".method" for class methods

    class Article
      def summary
        #...
      end

      def self.latest
        #...
      end
    end

    # the spec...
    describe Article
      describe '#summary'
        #...
      end

      describe '.latest'
        #...
      end
    end

Use fabricators to create test objects.
Make heavy use of mocks and stubs

    # mocking a model
    article = mock_model(Article)

    # stubbing a method
    Article.stub(:find).with(article.id).and_return(article)

When mocking a model, use the as_null_object method. It tells the output to listen only for messages we expect and ignore any other messages.

    article = mock_model(Article).as_null_object

Use let blocks instead of before(:all) blocks to create data for the spec examples. let blocks get lazily evaluated.

    # use this:
    let(:article) { Fabricate(:article) }

    # ... instead of this:
    before(:each) { @article = Fabricate(:article) }

Use subject when possible

    describe Article do
      subject { Fabricate(:article) }

      it 'is not published on creation' do
        subject.should_not be_published
      end
    end

Use specify if possible. It is a synonym of it but is more readable when there is no docstring.

    # bad
    describe Article do
      before { @article = Fabricate(:article) }

      it 'is not published on creation' do
        @article.should_not be_published
      end
    end

    # good
    describe Article do
      let(:article) { Fabricate(:article) }
      specify { article.should_not be_published }
    end

Use its when possible

    # bad
    describe Article do
      subject { Fabricate(:article) }

      it 'has the current date as creation date' do
        subject.creation_date.should == Date.today
      end
    end

    # good
    describe Article do
      subject { Fabricate(:article) }
      its(:creation_date) { should == Date.today }
    end

Views

The directory structure of the view specs spec/views matches the one in app/views. For example the specs for the views in app/views/users are placed in spec/views/users.
The naming convention for the view specs is adding _spec.rb to the view name, for example the view _form.html.haml has a corresponding spec _form.html.haml_spec.rb.
spec_helper.rb need to be required in each view spec file.
The outer describe block uses the path to the view without the app/views part. This is used by the render method when it is called without arguments.

    # spec/views/articles/new.html.haml_spec.rb
    require 'spec_helper'

    describe 'articles/new.html.haml' do
      # ...
    end

Always mock the models in the view specs. The purpose of the view is only to display information.
The method assign supplies the instance variables which the view uses and are supplied by the controller.

    # spec/views/articles/edit.html.haml_spec.rb
    describe 'articles/edit.html.haml' do
    it 'renders the form for a new article creation' do
      assign(
        :article,
        mock_model(Article).as_new_record.as_null_object
      )
      render
      rendered.should have_selector('form',
        method: 'post',
        action: articles_path
      ) do |form|
        form.should have_selector('input', type: 'submit')
      end
    end

Prefer the capybara negative selectors over should_not with the positive.

    # bad
    page.should_not have_selector('input', type: 'submit')
    page.should_not have_xpath('tr')

    # good
    page.should have_no_selector('input', type: 'submit')
    page.should have_no_xpath('tr')

When a view uses helper methods, these methods need to be stubbed. Stubbing the helper methods is done on the template object:

    # app/helpers/articles_helper.rb
    class ArticlesHelper
      def formatted_date(date)
        # ...
      end
    end

    # app/views/articles/show.html.haml
    = "Published at: #{formatted_date(@article.published_at)}"

    # spec/views/articles/show.html.haml_spec.rb
    describe 'articles/show.html.html' do
      it 'displays the formatted date of article publishing'
        article = mock_model(Article, published_at: Date.new(2012, 01, 01))
        assign(:article, article)

        template.stub(:formatted_date).with(article.published_at).and_return '01.01.2012'

        render
        rendered.should have_content('Published at: 01.01.2012')
      end
    end

The helpers specs are separated from the view specs in the spec/helpers directory.

Controllers

Mock the models and stub their methods. Testing the controller should not depend on the model creation.
Test only the behaviour the controller should be responsible about:
- Execution of particular methods
- Data returned from the action - assigns, etc.
- Result from the action - template render, redirect, etc.

        # Example of a commonly used controller spec
        # spec/controllers/articles_controller_spec.rb
        # We are interested only in the actions the controller should perform
        # So we are mocking the model creation and stubbing its methods
        # And we concentrate only on the things the controller should do

        describe ArticlesController do
          # The model will be used in the specs for all methods of the controller
          let(:article) { mock_model(Article) }

          describe 'POST create' do
            before { Article.stub(:new).and_return(article) }

            it 'creates a new article with the given attributes' do
              Article.should_receive(:new).with(title: 'The New Article Title').and_return(article)
              post :create, message: { title: 'The New Article Title' }
            end

            it 'saves the article' do
              article.should_receive(:save)
              post :create
            end

            it 'redirects to the Articles index' do
              article.stub(:save)
              post :create
              response.should redirect_to(action: 'index')
            end
          end
        end

Use context when the controller action has different behaviour depending on the received params.

    # A classic example for use of contexts in a controller spec is creation or update when the object saves successfully or not.

    describe ArticlesController do
      let(:article) { mock_model(Article) }

      describe 'POST create' do
        before { Article.stub(:new).and_return(article) }

        it 'creates a new article with the given attributes' do
          Article.should_receive(:new).with(title: 'The New Article Title').and_return(article)
          post :create, article: { title: 'The New Article Title' }
        end

        it 'saves the article' do
          article.should_receive(:save)
          post :create
        end

        context 'when the article saves successfully' do
          before { article.stub(:save).and_return(true) }

          it 'sets a flash[:notice] message' do
            post :create
            flash[:notice].should eq('The article was saved successfully.')
          end

          it 'redirects to the Articles index' do
            post :create
            response.should redirect_to(action: 'index')
          end
        end

        context 'when the article fails to save' do
          before { article.stub(:save).and_return(false) }

          it 'assigns @article' do
            post :create
            assigns[:article].should be_eql(article)
          end

          it 're-renders the "new" template' do
            post :create
            response.should render_template('new')
          end
        end
      end
    end

Models

Do not mock the models in their own specs.
Use fabrication to make real objects.
It is acceptable to mock other models or child objects.
Create the model for all examples in the spec to avoid duplication.

    describe Article
      let(:article) { Fabricate(:article) }
    end

Add an example ensuring that the fabricated model is valid.

    describe Article
      it 'is valid with valid attributes' do
        article.should be_valid
      end
    end

Add a separate describe for each attribute which has validations.

    describe Article
      describe '#title'
        it 'is required' do
          article.title = nil
          article.should_not be_valid
        end
      end
    end

When testing uniqueness of a model attribute, name the other object another_object.

    describe Article
      describe '#title'
        it 'is unique' do
          another_article = Fabricate.build(:article, title: article.title)
          another_article.should_not be_valid
        end
      end
    end

Mailers

The model in the mailer spec should be mocked. The mailer should not depend on the model creation.
The mailer spec should verify that:
- the subject is correct
- the receiver e-mail is correct
- the e-mail is sent to the right e-mail address
- the e-mail contains the required information

     describe SubscriberMailer
       let(:subscriber) { mock_model(Subscription, email: 'johndoe@test.com', name: 'John Doe') }

       describe 'successful registration email'
         subject { SubscriptionMailer.successful_registration_email(subscriber) }

         its(:subject) { should == 'Successful Registration!' }
         its(:from) { should == ['info@your_site.com'] }
         its(:to) { should == [subscriber.email] }

         it 'contains the subscriber name' do
           subject.body.encoded.should match(subscriber.name)
         end
       end
     end

Uploaders

What we can test about an uploader is whether the images are resized correctly. Here is a sample spec of a carrierwave image uploader:

    # rspec/uploaders/person_avatar_uploader_spec.rb
    require 'spec_helper'
    require 'carrierwave/test/matchers'

    describe PersonAvatarUploader do
      include CarrierWave::Test::Matchers

      # Enable images processing before executing the examples
      before(:all) do
        UserAvatarUploader.enable_processing = true
      end

      # Create a new uploader. The model is mocked as the uploading and resizing images does not depend on the model creation.
      before(:each) do
        @uploader = PersonAvatarUploader.new(mock_model(Person).as_null_object)
        @uploader.store!(File.open(path_to_file))
      end

      # Disable images processing after executing the examples
      after(:all) do
        UserAvatarUploader.enable_processing = false
      end

      # Testing whether image is no larger than given dimensions
      context 'the default version' do
        it 'scales down an image to be no larger than 256 by 256 pixels' do
          @uploader.should be_no_larger_than(256, 256)
        end
      end

      # Testing whether image has the exact dimensions
      context 'the thumb version' do
        it 'scales down an image to be exactly 64 by 64 pixels' do
          @uploader.thumb.should have_dimensions(64, 64)
        end
      end
    end

Contributing

Nothing written in this guide is set in stone. It's my desire to work together with everyone interested in Rails coding style, so that we could ultimately create a resource that will be beneficial to the entire Ruby community.

Feel free to open tickets or send pull requests with improvements. Thanks in advance for your help!

Spread the Word

A community-driven style guide is of little use to a community that doesn't know about its existence. Tweet about the guide, share it with your friends and colleagues. Every comment, suggestion or opinion we get makes the guide just a little bit better. And we want to have the best possible guide, don't we?

Ruby Style Guide

2011-12-10T00:00:00+00:00

Prelude

This guide is copy from bbatsov's work. Style is what separates the good from the great.
-- Bozhidar Batsov

One thing has always bothered me as Ruby developer - Python developers have a great programming style reference (PEP-8) and we never got an official guide, documenting Ruby coding style and best practices. And I do believe that style matters. I also believe that such fine fellows, like us Ruby developers, should be quite capable to produce this coveted document.

This guide started its life as our internal company Ruby coding guidelines (written by yours truly). At some point I decided that the work I was doing might be interesting to members of the Ruby community in general and that the world had little need for another internal company guideline. But the world could certainly benefit from a community-driven and community-sanctioned set of practices, idioms and style prescriptions for Ruby programming.

Since the inception of the guide I've received a lot of feedback from members of the exceptional Ruby community around the world. Thanks for all the suggestions and the support! Together we can make a resource beneficial to each and every Ruby developer out there.

By the way, if you're into Rails you might want to check out the complementary Ruby on Rails 3 Style Guide.

The Ruby Style Guide
- Source Code Layout
- Syntax
- Naming
- Comments
- Annotations
- Classes
- Exceptions
- Collections
- Strings
- Percent Literals
- Miscellaneous
- Design
Contributing
Spread the word

The Ruby Style Guide

This Ruby style guide recommends best practices so that real-world Ruby programmers can write code that can be maintained by other real-world Ruby programmers. A style guide that reflects real-world usage gets used, and a style guide that holds to an ideal that has been rejected by the people it is supposed to help risks not getting used at all – no matter how good it is.

The guide is separated into several sections of related rules. I've tried to add the rationale behind the rules (if it's omitted I've assumed that is pretty obvious).

I didn't come up with all the rules out of nowhere - they are mostly based on my extensive career as a professional software engineer, feedback and suggestions from members of the Ruby community and various highly regarded Ruby programming resources, such as "Programming Ruby 1.9" and "The Ruby Programming Language".

The guide is still a work in progress - some rules are lacking examples, some rules don't have examples that illustrate them clearly enough. In due time these issues will be addressed - just keep them in mind for now.

You can generate a PDF or an HTML copy of this guide using Transmuter.

Source Code Layout

Nearly everybody is convinced that every style but their own is ugly and unreadable. Leave out the "but their own" and they're probably right...
-- Jerry Coffin (on indentation)

Use UTF-8 as the source file encoding.
Use two spaces per indentation level.

    # good
    def some_method
      do_something
    end

    # bad - four spaces
    def some_method
        do_something
    end

Use Unix-style line endings. (*BSD/Solaris/Linux/OSX users are covered by default, Windows users have to be extra careful.)
- If you're using Git you might want to add the following configuration setting to protect your project from Windows line endings creeping in: $ git config --global core.autocrlf true
Use spaces around operators, after commas, colons and semicolons, around { and before }. Whitespace might be (mostly) irrelevant to the Ruby interpreter, but its proper use is the key to writing easily readable code.

    sum = 1 + 2
    a, b = 1, 2
    1 > 2 ? true : false; puts 'Hi'
    [1, 2, 3].each { |e| puts e }

The only exception is when using the exponent operator:

    # bad
    e = M * c ** 2

    # good
    e = M * c**2

No spaces after (, [ or before ], ).

    some(arg).other
    [1, 2, 3].length

Indent when as deep as case. I know that many would disagree with this one, but it's the style established in both the "The Ruby Programming Language" and "Programming Ruby".

    case
    when song.name == 'Misty'
      puts 'Not again!'
    when song.duration > 120
      puts 'Too long!'
    when Time.now.hour > 21
      puts "It's too late"
    else
      song.play
    end

    kind = case year
           when 1850..1889 then 'Blues'
           when 1890..1909 then 'Ragtime'
           when 1910..1929 then 'New Orleans Jazz'
           when 1930..1939 then 'Swing'
           when 1940..1950 then 'Bebop'
           else 'Jazz'
           end

Use empty lines between defs and to break up a method into logical paragraphs.

    def some_method
      data = initialize(options)

      data.manipulate!

      data.result
    end

    def some_method
      result
    end

Use RDoc and its conventions for API documentation. Don't put an empty line between the comment block and the def.
Keep lines fewer than 80 characters.
Avoid trailing whitespace.

Syntax

Use def with parentheses when there are arguments. Omit the parentheses when the method doesn't accept any arguments.

   def some_method
     # body omitted
   end

   def some_method_with_arguments(arg1, arg2)
     # body omitted
   end

Never use for, unless you know exactly why. Most of the time iterators should be used instead. for is implemented in terms of each (so you're adding a level of indirection), but with a twist - for doesn't introduce a new scope (unlike each) and variables defined in its block will be visible outside it.

    arr = [1, 2, 3]

    # bad
    for elem in arr do
      puts elem
    end

    # good
    arr.each { |elem| puts elem }

Never use then for multi-line if/unless.

    # bad
    if some_condition then
      # body omitted
    end

    # good
    if some_condition
      # body omitted
    end

Favor the ternary operator(?:) over if/then/else/end constructs. It's more common and obviously more concise.

    # bad
    result = if some_condition then something else something_else end

    # good
    result = some_condition ? something : something_else

Use one expression per branch in a ternary operator. This also means that ternary operators must not be nested. Prefer if/else constructs in these cases.

    # bad
    some_condition ? (nested_condition ? nested_something : nested_something_else) : something_else

    # good
    if some_condition
      nested_condition ? nested_something : nested_something_else
    else
      something_else
    end

Never use if x: ... - it is removed in Ruby 1.9. Use the ternary operator instead.

    # bad
    result = if some_condition: something else something_else end

    # good
    result = some_condition ? something : something_else

Never use if x; .... Use the ternary operator instead.
Use when x then ... for one-line cases. The alternative syntax when x: ... is removed in Ruby 1.9.
Never use when x; .... See the previous rule.
Use &&/|| for boolean expressions, and/or for control flow. (Rule of thumb: If you have to use outer parentheses, you are using the wrong operators.)

    # boolean expression
    if some_condition && some_other_condition
      do_something
    end

    # control flow
    document.saved? or document.save!

Avoid multi-line ?: (the ternary operator), use if/unless instead.
Favor modifier if/unless usage when you have a single-line body. Another good alternative is the usage of control flow and/or.

    # bad
    if some_condition
      do_something
    end

    # good
    do_something if some_condition

    # another good option
    some_condition and do_something

Favor unless over if for negative conditions (or control flow or).

    # bad
    do_something if !some_condition

    # good
    do_something unless some_condition

    # another good option
    some_condition or do_something

Never use unless with else. Rewrite these with the positive case first.

    # bad
    unless success?
      puts 'failure'
    else
      puts 'success'
    end

    # good
    if success?
      puts 'success'
    else
      puts 'failure'
    end

Don't use parentheses around the condition of an if/unless/while.

    # bad
    if (x > 10)
      # body omitted
    end

    # good
    if x > 10
      # body omitted
    end

Omit parentheses around parameters for methods that are part of an internal DSL (e.g. Rake, Rails, RSpec), methods that are with "keyword" status in Ruby (e.g. attr_reader, puts) and attribute access methods. Use parentheses around the arguments of all other method invocations.

    class Person
      attr_reader name, age

      # omitted
    end

    temperance = Person.new('Temperance', 30)
    temperance.name

    puts temperance.age

    x = Math.sin(y)
    array.delete(e)

Prefer {...} over do...end for single-line blocks. Avoid using {...} for multi-line blocks (multiline chaining is always ugly). Always use do...end for "control flow" and "method definitions" (e.g. in Rakefiles and certain DSLs). Avoid do...end when chaining.

    names = ["Bozhidar", "Steve", "Sarah"]

    # good
    names.each { |name| puts name }

    # bad
    names.each do |name|
      puts name
    end

    # good
    names.select { |name| name.start_with?("S") }.map { |name| name.upcase }

    # bad
    names.select do |name|
      name.start_with?("S")
    end.map { |name| name.upcase }

Some will argue that multiline chaining would look OK with the use of {...}, but they should
ask themselves - it this code really readable and can't the blocks contents be extracted into
nifty methods.

Avoid return where not required.

    # bad
    def some_method(some_arr)
      return some_arr.size
    end

    # good
    def some_method(some_arr)
      some_arr.size
    end

Use spaces around the = operator when assigning default values to method parameters:

    # bad
    def some_method(arg1=:default, arg2=nil, arg3=[])
      # do something...
    end

    # good
    def some_method(arg1 = :default, arg2 = nil, arg3 = [])
      # do something...
    end

While several Ruby books suggest the first style, the second is much more prominent
in practice (and arguably a bit more readable).

Avoid line continuation (\) where not required. In practice, avoid using line continuations at all.

    # bad
    result = 1 - \
             2

    # good (but still ugly as hell)
    result = 1 \
             - 2

Using the return value of = (an assignment) is ok.

    if v = array.grep(/foo/) ...

Use ||= freely to initialize variables.

    # set name to Bozhidar, only if it's nil or false
    name ||= 'Bozhidar'

Don't use ||= to initialize boolean variables. (Consider what would happen if the current value happened to be false.)

    # bad - would set enabled to true even if it was false
    enabled ||= true

    # good
    enabled = true if enabled.nil?

Avoid using Perl-style special variables (like $0-9, `$``, etc. ). They are quite cryptic and their use in anything but one-liner scripts is discouraged.
Never put a space between a method name and the opening parenthesis.

    # bad
    f (3 + 2) + 1

    # good
    f(3 + 2) + 1

If the first argument to a method begins with an open parenthesis, always use parentheses in the method invocation. For example, write f((3 + 2) + 1).
Always run the Ruby interpreter with the -w option so it will warn you if you forget either of the rules above!

Naming

The only real difficulties in programming are cache invalidation and naming things.
-- Phil Karlton

Use snake_case for methods and variables.
Use CamelCase for classes and modules. (Keep acronyms like HTTP, RFC, XML uppercase.)
Use SCREAMING_SNAKE_CASE for other constants.
The names of predicate methods (methods that return a boolean value) should end in a question mark. (i.e. Array#empty?).
The names of potentially "dangerous" methods (i.e. methods that modify self or the arguments, exit!, etc.) should end with an exclamation mark.
When using inject with short blocks, name the arguments |a, e| (accumulator, element).
When defining binary operators, name the argument other.

    def +(other)
      # body omitted
    end

Prefer map over collect, find over detect, select over find_all, size over length. This is not a hard requirement; if the use of the alias enhances readability, it's ok to use it.

Comments

Good code is its own best documentation. As you're about to add a comment, ask yourself, "How can I improve the code so that this comment isn't needed?" Improve the code and then document it to make it even clearer.
-- Steve McConnell

Write self-documenting code and ignore the rest of this section. Seriously!
Comments longer than a word are capitalized and use punctuation. Use one space after periods.
Avoid superfluous comments.

    # bad
    counter += 1 # increments counter by one

Keep existing comments up-to-date. No comment is better than an outdated comment.
Avoid writing comments to explain bad code. Refactor the code to make it self-explanatory. (Do or do not - there is no try.)

Annotations

Annotations should usually be written on the line immediately above the relevant code.
The annotation keyword is followed by a colon and a space, then a note describing the problem.
If multiple lines are required to describe the problem, subsequent lines should be indented two spaces after the #.

    def bar
      # FIXME: This has crashed occasionally since v3.2.1. It may
      #   be related to the BarBazUtil upgrade.
      baz(:quux)
    end

In cases where the problem is so obvious that any documentation would be redundant, annotations may be left at the end of the offending line with no note. This usage should be the exception and not the rule.

    def bar
      sleep 100 # OPTIMIZE
    end

Use TODO to note missing features or functionality that should be added at a later date.
Use FIXME to note broken code that needs to be fixed.
Use OPTIMIZE to note slow or inefficient code that may cause performance problems.
Use HACK to note code smells where questionable coding practices were used and should be refactored away.
Use REVIEW to note anything that should be looked at to confirm it is working as intended. For example: REVIEW: Are we sure this is how the client does X currently?
Use other custom annotation keywords if it feels appropriate, but be sure to document them in your project's README or similar.

Classes

Always supply a proper to_s method.

    class Person
      attr_reader :first_name, :last_name

      def initialize(first_name, last_name)
        @first_name = first_name
        @last_name = last_name
      end

      def to_s
        "#@first_name #@last_name"
      end
    end

Use the attr family of functions to define trivial accessors or mutators.
Consider adding factory methods to provide additional sensible ways to create instances of a particular class.
Prefer duck-typing over inheritance.
Avoid the usage of class (@@) variables due to their "nasty" behavior in inheritance.
Assign proper visibility levels to methods (private, protected) in accordance with their intended usage. Don't go off leaving everything public (which is the default). After all we're coding in Ruby now, not in Python.
Indent the public, protected, and private methods as much the method definitions they apply to. Leave one blank line above them.

    class SomeClass
      def public_method
        # ...
      end

      private
      def private_method
        # ...
      end
    end

Use def self.method to define singleton methods. This makes the methods more resistant to refactoring changes.

    class TestClass
      # bad
      def TestClass.some_method
        # body omitted
      end

      # good
      def self.some_other_method
        # body omitted
      end

      # Also possible and convenient when you
      # have to define many singleton methods.
      class << self
        def first_method
          # body omitted
        end

        def second_method_etc
          # body omitted
        end
      end
    end

Exceptions

Don't suppress exceptions.
Don't use exceptions for flow of control.
Avoid rescuing the Exception class.

Collections

It's ok to use arrays as sets for a small number of elements.
Prefer %w to the literal array syntax when you need an array of strings.
Avoid the creation of huge gaps in arrays.
Use Set instead of Array when dealing with lots of elements.
Use symbols instead of strings as hash keys.
Avoid the use of mutable object as hash keys.
Use the new 1.9 literal hash syntax in preference to the hashrocket syntax.
Rely on the fact that hashes in 1.9 are ordered.
Never modify a collection while traversing it.

Strings

Prefer string interpolation instead of string concatenation:

    # bad
    email_with_name = user.name + ' <' + user.email + '>'

    # good
    email_with_name = "#{user.name} <#{user.email}>"

Prefer single-quoted strings when you don't need string interpolation or special symbols such as \t, \n, ', etc.

    # bad
    name = "Bozhidar"

    # good
    name = 'Bozhidar'

Don't use {} around instance variables being interpolated into a string.

    class Person
      attr_reader :first_name, :last_name

      def initialize(first_name, last_name)
        @first_name = first_name
        @last_name = last_name
      end

      # bad
      def to_s
        "#{@first_name} #{@last_name}"
      end

      # good
      def to_s
        "#@first_name #@last_name"
      end
    end

Avoid using String#+ when you need to construct large data chunks. Instead, use String#<<. Concatenation mutates the string instance in-place and is always faster than String#+, which creates a bunch of new string objects.

    # good and also fast
    html = ''
    html << '<h1>Page title</h1>'

    paragraphs.each do |paragraph|
      html << "<p>#{paragraph}</p>"
    end

Percent Literals

Use %w freely.

    STATES = %w(draft open closed)

Use %() for single-line strings which require both interpolation and embedded double-quotes. For multi-line strings, prefer heredocs.

    # bad (no interpolation needed)
    %(<div class="text">Some text</div>)
    # should be '<div class="text">Some text</div>'

    # bad (no double-quotes)
    %(This is #{quality} style)
    # should be "This is #{quality} style"

    # bad (multiple lines)
    %(<div>\n<span class="big">#{exclamation}</span>\n</div>)
    # should be a heredoc.

    # good (requires interpolation, has quotes, single line)
    %(<tr><td class="name">#{name}</td>)

Use %r only for regular expressions matching more than one '/' character.

    # bad
    %r(\s+)

    # still bad
    %r(^/(.*)$)
    # should be /^\/(.*)$/

    # good
    %r(^/blog/2011/(.*)$)

Avoid %q, %Q, %x, %s, and %W.
Prefer () as delimiters for all % literals.

Misc

Write ruby -w safe code.
Avoid hashes as optional parameters. Does the method do too much?
Avoid methods longer than 10 LOC (lines of code). Ideally, most methods will be shorter than 5 LOC. Empty lines do not contribute to the relevant LOC.
Avoid parameter lists longer than three or four parameters.
If you really have to, add "global" methods to Kernel and make them private.
Use class instance variables instead of global variables.

    #bad
    $foo_bar = 1

    #good
    class Foo
      class << self
        attr_accessor :bar
      end
    end

    Foo.bar = 1

Avoid alias when alias_method will do.
Use OptionParser for parsing complex command line options and ruby -s for trivial command line options.
Write for Ruby 1.9. Don't use legacy Ruby 1.8 constructs.
- Use the new JavaScript literal hash syntax.
- Use the new lambda syntax.
- Methods like inject now accept method names as arguments.

      [1, 2, 3].inject(:+)

Avoid needless metaprogramming.

Design

Code in a functional way, avoiding mutation when that makes sense.
Do not mutate arguments unless that is the purpose of the method.
Do not mess around in core classes when writing libraries. (Do not monkey patch them.)
Do not program defensively.
Keep the code simple and subjective. Each method should have a single, well-defined responsibility.
Avoid more than three levels of block nesting.
Don't overdesign. Overly complex solutions tend to be brittle and hard to maintain.
Don't underdesign. A solution to a problem should be as simple as possible, but no simpler than that. Poor initial design can lead to a lot of problems in the future.
Be consistent. In an ideal world, be consistent with these guidelines.
Use common sense.

Contributing

Nothing written in this guide is set in stone. It's my desire to work together with everyone interested in Ruby coding style, so that we could ultimately create a resource that will be beneficial to the entire Ruby community.

Feel free to open tickets or send pull requests with improvements. Thanks in advance for your help!

Spread the Word

Migrate Blog to Jekyll with Jekyll Extension

2011-12-09T00:00:00+00:00

I'm happy to see you guys, I built my own rails blog system about 3 years ago, but long time no updates with my blog. Since known about Jekyll, a simple, blog aware, static site generator, It's cool to build a blog using jekyll without databases, that's great for me to write blog articles useing markdown format.

So I started to build my new blog system by Jekyll several days ago, but I got some problems about Jekyll extensions during the installation, with richard's help, it works, bye the way, you need to install the pyments for code highlight if you want to highlight your code. you can follow the Jekyll Wiki to get forward.

What I want for my blog system is not supported by default Jekyll, but I added some extensions according to My Jekyll Extensions, It's really cool that we can build our categories section, monthly archive section, categroy page, monthly archive page without database now.

You can clone my Jekyll blog system hansay.com at https://github.com/jerryshen/hansay.com.

Deployment with RVM, nginx, and passenger for ruby on rails

2011-12-03T00:00:00+00:00

服务器系统: ubuntu server 11.10 64bit
案例服务器: Linode VPS 512系列

租下vps, 选择所要的系统 ubuntu server 11.10 64bit, 我一直不喜欢直接用root来做部署, 所以我会创建一个具有sudo权限的用户来完成整个部署和操作, 下面以jerry为例:

$  useradd jerry            # 添加用户'jerry'
$  passwd jerry             # 为'jerry'设置密码
$  gpasswd -a jerry sudo    # 将用户jerry添加进sudo组(sudo组是默认就存在的，所以不用创建)
$  cd /home && mkdir jerry  # 为jerry创建工作目录
$  chown jerry /home/jerry  # 设置权限

添加jerry后可能是不是bash环境, 如果发现不是bash环境, 可以融过root用户将jerry的环境改成bash

$ usermod --shell=/bin/bash jerry

通过编辑authorized_keys, 添加public key到jerry用户目录下, 这样以后ssh远程登录服务器就无须输入密码了

$  cd ~  
$  mkdir .ssh  && cd .ssh  
$  vim authorized_keys      # 贴入public key

接下来需要安装RVM, 安装RVM前需要安装几个必要的packages

$  sudo apt-get install curl git-core libtool

然后安装rvm

$  bash < <(curl -s https://rvm.beginrescueend.com/install/rvm)

在 ~/.bashrc 中设置RVM的环境变量

if [[ -s "$HOME/.rvm/scripts/rvm" ]]  ; then source "$HOME/.rvm/scripts/rvm" ; fi

在 ~.bash_profile 中引用 .bashrc

source ~/.bashrc

推出终端重新进入, 你会发现RVM已经生效了

$  rvm notes

安装必要的packages

$  sudo apt-get install bison build-essential zlib1g zlib1g-dev libssl-dev libreadline-gplv2-dev libxml2-dev libxslt1-dev autoconf

安装完以上的packages后, 正式用rvm编译ruby 1.9.3, rvm会将ruby自动编译到当前用户目录的 ~/.rvm 下(非root用户).

$  rvm install 1.9.3

安装完ruby 1.9.3后, 我们可以把rvm ruby 1.9.3设置为默认

$  rvm --default ruby-1.9.3-p0

接下来就可以查看ruby 版本了

$  ruby -v

至此 Ruby 1.9.3编译已经完成

安装 Postgresql 数据库

首先需要确认当前用户 env的LANG是否为UTF8,

$  env

看显示信息是否有 LANG=en_US.UTF8，如果没有,在 /etc/profile 中加入环境变量:

export LANG=en_US.UTF8

之后退出终端再进入, 你的设置就生效了, 然后安装postgresql数据库, 以 ubuntu 11.10为例, 版本应该是 9.1

$  sudo apt-get install postgresql

切换到root用户下, 初始化postgresql用户和密码

$  su postgres -c psql postgres
$  ALTER USER postgres WITH PASSWORD 'postgres';
$  \q

其中 'postgres' 为要修改的密码

编辑 /etc/postgresql/9.1/main/pg_hba.conf

# Database administrative login by UNIX sockets
# local   all         postgres                        ident

# TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD

# "local" is for Unix domain socket connections only
local   all         all                               md5 #ident
# IPv4 local connections:
host    all         all         127.0.0.1/32          md5
# IPv6 local connections:
host    all         all         ::1/128               md5

如果不希望允许 postgres 使用密码登入的可以开启第2行 # local all postgres ident 的注释

编辑 /etc/postgresql/9.1/main/postgresql.conf, 搜索 # listen_addresses = 将其修改为

listen_addresses = 'localhost'    # which IP address(es) to listen on;

如果允许其他机器访问的请将 localhost 修改成 *

重启数据库

$  /etc/init.d/postgresql restart

安装 Phusion Passenger

ruby1.9.3安装好之后, 会自动带一个空的gemset, 切换到该gemset下并安装passenger

$ rvm use 1.9.3@
$ gem install -V passenger

安装 nginx 服务器

下载最新的stable version nginx

$  mkdir -p /home/jerry/opt/src && cd /home/jerry/opt/src
$  wget http://nginx.org/download/nginx-1.0.10.tar.gz
$  tar xvf nginx-1.0.10.tar.gz

安装编译相关类库

$  sudo apt-get install libpcre3-dev

编译安装带有 passenger 模块的nginx

使用 passenger 脚本 passenger-install-nginx-module 编译 nginx

选择 2. No: I want to customize my Nginx installation. (for advanced users)

输入 src: /home/jerry/opt/src/nginx-1.0.10 和 prefix: /home/jerry/opt/nginx

添加编译参数并编译

$  --conf-path=/home/jerry/opt/etc/nginx/nginx.conf --with-http_gzip_static_module

如果还要启动其他编译参数请自行添加

另外如果不想使用passenger自带脚本编译nginx, 也可以手工编译nginx时加入以下参数, 来启动passenger模块

--add-module='/home/jerry//opt/passenger/ext/nginx

配置 nginx

整理编译自动生成的配置文件

$  cd /home/jerry/opt/etc/nginx
$  mkdir /home/jerry/opt/etc/nginx/default
$  mv *.default default/
$  mkdir conf.d
$  mkdir sites-enabled

将 /home/jerry/opt/etc/nginx/nginx.conf 替换为

user  jerry jerry;
worker_processes  1;

events {
    worker_connections  1024;
}


http {
    include       mime.types;
    default_type  application/octet-stream;

    sendfile        on;
    #tcp_nopush     on;

    keepalive_timeout  65;
    gzip  on;

    include conf.d/*.conf;
    include sites-enabled/*;
}

添加 gzip_static 模块配置, 编辑 /home/jerry/opt/etc/nginx/conf.d/gzip_static.conf

gzip_static on;
gzip_types text/css application/x-javascript;

添加 Passneger 模块配置, 编辑 /home/jerry/opt/etc/nginx/conf.d/passenger.conf

passenger_root /home/jerry/.rvm/gems/ruby-1.9.3-p0/gems/passenger-3.0.11;
passenger_ruby /home/jerry/.rvm/bin/ruby-1.9.3-p0;

将nginx的server配置链接到sites-enabled下

$  ln -s /home/jerry/apps/conf/nginx.conf /home/jerry/opt/etc/nginx/sites-enabled/default

编辑 /home/jerry/apps/conf/nginx.conf

server{
  listen 80;
  server_name  demo.com www.demo.com;
  root /home/jerry/apps/demo/current/public;
  passenger_enabled on;

  location ~ ^/(images|javascripts|stylesheets)/  {
      root /home/jerry/apps/demo/current/public;
      expires 30d;
  }
}

如果需要配置详细的配置信息, 请参考 Nginx 文档

添加启动脚本 /home/jerry/opt/etc/init.d/nginx 内容为

#! /bin/sh

### BEGIN INIT INFO
# Provides:          nginx
# Required-Start:    $all
# Required-Stop:     $all
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: starts the nginx web server
# Description:       starts nginx using start-stop-daemon
### END INIT INFO

# PATH=/home/jerry/.rvm/gems/ruby-1.9.3-p0/bin:/bin:/home/jerry/.rvm/rubies/ruby-1.9.3-p0/bin:/home/jerry/.rvm/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games
DAEMON=/home/jerry/opt/nginx/sbin/nginx
NAME=nginx
DESC=nginx
PIDFILE=/home/jerry/opt/nginx/logs/$NAME.pid

test -x $DAEMON || exit 0

# Include nginx defaults if available
if [ -f /home/jerry/opt/etc/default/nginx ] ; then
    . /home/jerry/opt/etc/default/nginx
fi

set -e

. /lib/lsb/init-functions

test_nginx_config() {
    if $DAEMON -t; then
        return 0
    else
        return $?
    fi
}

case "$1" in
    start)
        echo -n "Starting $DESC: "
        test_nginx_config
        start-stop-daemon --start --quiet --pidfile $PIDFILE \
            --exec $DAEMON -- $DAEMON_OPTS || true
        echo "$NAME."
    ;;
    stop)
        echo -n "Stopping $DESC: "
        start-stop-daemon --stop --quiet --pidfile $PIDFILE \
            --exec $DAEMON || true
        echo "$NAME."
    ;;
    restart|force-reload)
        echo -n "Restarting $DESC: "
        start-stop-daemon --stop --quiet --pidfile \
            $PIDFILE --exec $DAEMON || true
        sleep 1
        test_nginx_config
        start-stop-daemon --start --quiet --pidfile \
            $PIDFILE --exec $DAEMON -- $DAEMON_OPTS || true
        echo "$NAME."
    ;;
    reload)
        echo -n "Reloading $DESC configuration: "
        test_nginx_config
        start-stop-daemon --stop --signal HUP --quiet --pidfile $PIDFILE \
           --exec $DAEMON || true
        echo "$NAME."
    ;;
    configtest)
        echo -n "Testing $DESC configuration: "
        if test_nginx_config; then
            echo "$NAME."
        else
            exit $?
        fi
    ;;
    status)
        status_of_proc -p $PIDFILE "$DAEMON" nginx && exit 0 || exit $?
    ;;
    *)
        echo "Usage: $NAME {start|stop|restart|reload|force-reload|status|configtest}" >&2
        exit 1
    ;;
esac

exit 0

切换到root用户, 设置nginx的随机服务启动

$  chmod +x /home/jerry/opt/etc/init.d/nginx
$  ln -s /home/jerry/opt/etc/init.d/nginx /etc/init.d/nginx
$  update-rc.d nginx defaults

到这里nginx的配置已经完成，接下来你就可以将项目发布到服务器了.

Using Nested Form with Simple Form

2011-11-30T00:00:00+00:00

I would like to introduce you guys a Rails gem for conveniently manage multiple nested models in a single form. It does so in an unobtrusive way through jQuery.

For now this gem only works with Rails 3.

Add it to your Gemfile then run bundle to install it.

    gem 'nested_form', :git => 'git://github.com/ryanb/nested_form.git'

For Rails 3.1, the only thing you have to do is just require the js file in your application.js

    # application.js
    //= require jquery
    //= require jquery_ujs
    //= require nested_form

So we can get started with nested form now, we can imagine that we have a Product model that has_many :photos. To be able to use this function, you need to add some configuration to your Product model, ad we have Photo model which is to store the photos.

    class Photo
      include Mongoid::Document

      mount_uploader :data, PhotoUploader

      field :data, type: String

      embedded_in :product

    end

    class Product
      include Mongoid::Document
      include Mongoid::Timestamps

      embedded_many :photos, cascade_callbacks: true

      accepts_nested_attributes_for :photos,
                                    reject_if: proc { |attributes| attributes['data'].blank? },
                                    allow_destroy: true
    end

If you don't have the accepts_nested_attributes_for settings for photos, you'll get a Missing Block Error.

We also use SimpleForm to make our form simpler, in this Git repo, It was implemented to use simple_nested_form_for for SimpleForm support. But this feature is not yet in a Gem release, so you can use this git repo.

Here is the form.

    = simple_nested_form_for resource, :url => products_path do |f|
      = f.input :name
      
      - resource.photos.each do |photo|
        = f.simple_fields_for :photos, photo do |p|
          .photo
            = label_tag ''
            = image_tag photo.data
            %br/
            = label_tag ''
            = p.link_to_remove 'delete this image'
            = p.input :data_cache, :as => :hidden
            
      = f.simple_fields_for :photos, resource.photos.build do |p|
        = p.input :data, :as => :file
        = p.input :data_cache, :as => :hidden
        = p.link_to_remove 'remove'
      = f.link_to_add 'Add', :photos

      .actions
        = f.submit 'Save changes'
        = button_tag 'Reset', :type => 'reset'

This gem is produced by Ryanb, many thanks.

Getting Started with RSpec

2011-11-28T00:00:00+00:00

One of the reasons that I love rails is the awesome test frameworks. Here’s an introduction for those of you interested in getting started with RSpec.

Everyone may know Behaviour Driven Development, It's an Agile development process that comprises aspects of Acceptance Test Driven Planning, Domain Driven Design and Test Driven Development. RSpec is a BDD tool aimed at TDD in the context of BDD.

Here is my gemfile.

    #gemfile
    
    # mongo support
    gem 'mongo',      '~> 1.3.1'
    gem 'mongoid',    '~> 2.3.3'
    gem 'bson',       '~> 1.3.1'
    gem 'bson_ext',   '~> 1.3.1'
    
    group :development, :test do
      gem 'machinist',        '~> 2.0.0.beta2'
      gem 'machinist_mongo',  :git => 'https://github.com/nmerouze/machinist_mongo.git', :require => 'machinist/mongoid', :branch => 'machinist2'  # you need to add this if you are using mongoid
      gem 'database_cleaner', '~> 0.6.7'
      gem 'ffaker',           '~> 1.8.1'
      gem 'launchy'
      gem 'guard-rspec'
    end

    group :test do
      gem 'rspec',            '~> 2.7.0'
      gem 'rspec-rails',      '~> 2.7.0'
      gem 'mongoid-rspec',    '~> 1.4.4'
      gem 'spork',            '~> 0.8.5'
      gem 'cucumber-rails',   '~> 1.2.0'
      gem 'capybara',         '~> 1.1.1'
      gem 'email_spec'
      gem 'simplecov',        :require => false
      gem 'rb-fsevent',       :require => false
      gem 'growl_notify'
    end

In this gemfile, I add two gems 'machinist_mongo and 'mongoid-rspec' because of I'm using Mongoid in my project, if you are using activerecord, just remove these two gems.

Installation

Just Run bundle to install all the gems listed in gemfile

RSpec works great with other assistant plugins as I listed above, I will introduce you one by one.

RSpec

Someone would say that unit testing framework is good enough, but what I would say is that RSpec is a Domain Specific Language for describing the expected behaviour of a system with executable examples.

Configuration

Initialize Rspec

$ rails g rspec:install

It will generate files and directories as below

create  .rspec
create  spec
create  spec/spec_helper.rb

Let's modify spec_helper.rb to extend some awesome tools

    require 'rubygems'
    require 'simplecov'
    require 'spork'
    SimpleCov.start 'rails'

    # This file is copied to spec/ when you run 'rails generate rspec:install'
    ENV["RAILS_ENV"] ||= 'test'
    require 'rails/mongoid'
    Spork.trap_class_method(Rails::Mongoid, :load_models)
    require File.expand_path('../../config/environment', __FILE__)
    require 'rspec/rails'

    # Requires supporting ruby files with custom matchers and macros, etc,
    # in spec/support/ and its subdirectories.
    Dir[Rails.root.join('spec/support/**/*.rb')].each {|f| require f}

    RSpec.configure do |config|
      config.mock_with :rspec
      config.include Mongoid::Matchers

      DatabaseCleaner.strategy = :truncation

      config.before do
        DatabaseCleaner.clean
      end

    end

Bye the way, I would like to suggest you change your rails generator in config/application.rb, add the following code:

    config.generators do |g|
      g.orm                 :mongoid
      g.template_engine     :haml
      g.test_framework      :rspec, :fixture => false, :views => false
      g.fixture_replacement :machinist
    end

Guard

Guard watches files and runs a command after a file is modified. This allows you to automatically run tests in the background, restart your development server, reload the browser, and more.

Configuration

After you run bundle to install everything and, once that's done, run guard init rspec to set up Guard

$ guard init
Writing new Guardfile to (here is your path)
rspec guard added to Guardfile, feel free to edit it

It will generate a Guardfile in your rails root directory, make it like:

    # A sample Guardfile
    # More info at https://github.com/guard/guard#readme

    guard 'rspec', :version => 2 do
      watch(%r{^spec/.+_spec\.rb$})
      watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
      watch('spec/spec_helper.rb')  { "spec/" }

      # Rails example
      watch(%r{^spec/.+_spec\.rb$})
      watch(%r{^app/(.+)\.rb$})                           { |m| "spec/#{m[1]}_spec.rb" }
      watch(%r{^lib/(.+)\.rb$})                           { |m| "spec/lib/#{m[1]}_spec.rb" }
      watch(%r{^app/controllers/(.+)_(controller)\.rb$})  { |m| ["spec/routing/#{m[1]}_routing_spec.rb", "spec/#{m[2]}s/#{m[1]}_#{m[2]}_spec.rb", "spec/acceptance/#{m[1]}_spec.rb"] }
      watch(%r{^spec/support/(.+)\.rb$})                  { "spec/" }
      watch('spec/spec_helper.rb')                        { "spec/" }
      watch('config/routes.rb')                           { "spec/routing" }
      watch('app/controllers/application_controller.rb')  { "spec/controllers" }
      # Capybara request specs
      watch(%r{^app/views/(.+)/.*\.(erb|haml)$})          { |m| "spec/requests/#{m[1]}_spec.rb" }
    end

Guard also has support for Growl notifications and these can be enabled by installing the growl gem, You can find rb-fsevent and growl_notify as I listed in Gemfile, but it only works via Mac OSX, remove these if you are using linux.

We can now run the guard command to start up the Guard server.

$ guard
Guard is now watching at '/Users/shenjerry/Workspace/demo'
Guard::RSpec is running, with RSpec 2!
Running all specs
...

Finished in 1.02 seconds
3 examples, 0 failures

If we make a breaking change to our code, for example remove a method in your user model, Guard will run immediately and we’ll see the broken test clearly.

Machinist

Machinist is an awesome plugin which make it easy to create objects for use in tests, It generates data for the attributes you don't care about, and constructs any necessary associated objects, leaving you to specify only the fields you care about in your test.

Configuration

$ rails g machinist:install

It will generate blueprint.rb file in your spec/support directory.

Here is a example to define a blueprint:

    require 'machinist/mongoid'

    User.blueprint do
      email     { Faker::Internet.email }
      username  { "username_#{sn}" }
      password  { "password" }
      password_confirmation { object.password }
    end

If you want to create a user in your console, you need require the blueprints first

>> require Rails.root.join('spec', 'support/blueprints')
>> User.make!

Now you can find this user in database.

Another case that you want to define a admin blueprint as the same user model, if you supposed to add a whole blueprint again, that's ugly. Here is the simple way to handle this:

    require 'machinist/mongoid'

    User.blueprint(:admin) do
      is_admin  { true }
    end

You can use User.make!(:admin) to create a admin.

>> require Rails.root.join('spec', 'support/blueprints')
>> User.make!(:admin)

Supporting Dynamic Fields Form for Mongoid

2011-11-20T00:00:00+00:00

Mongoid currently supports the dynamic fields configuration option, which provided in the mongoid.yml,

allow_dynamic_fields: true

When attributes are not defined as fields but added to an object, they will get fields added for them dynamically and will get persisted. If set to false an error will get raised when attempting to set a value that has no field defined.

But there is a problem with a dynamic fields form, you will get raised when attempting to add a undefined atribute in your form, so question comes, how to enable form to support dynamic fields that could be added to an object? The only thing you should do is that override the method_missing method in mongoid module.

    module Mongoid 
      module Attributes
        alias_method :old_method_missing, :method_missing
        def method_missing(name, *args)
          old_method_missing(name, *args)
        rescue
          nil
        end
      end
    end

You can directly put this file in config/initializer directory, or lib and require this file, whatever you like.

Customize the Redirect for Devise

2011-09-25T00:00:00+00:00

Devise has many default redirect, it depends on what you'v done with Devise.

Normally, after a user signed in, they are redirected to the root path. But we should have Devise redirect to a custom route after signed in, such as a administrator.

If you are using the default routes with Devise, add the override methods in your ApplicationController

    class ApplicationController < ActionController::Base

      protected

        def after_update_path_for(resource)
          if resource.is_admin?
            admin_root_path
          else
            super
          end
        end
    end

That's it, it very easy to customize your routes, we have other routes could be customized.

after_sign_out_path_for(resource)
after_update_path_for(resource)
sign_out_and_redirect(resource)
after_resending_confirmation_instructions_path_for(resource_name)
after_confirmation_path_for(resource_name, resource)
after_omniauth_failure_path_for(resource_name)
after_sending_reset_password_instructions_path_for(resource_name)

Allow Users to Login with Username or Email Using Devise

2011-09-20T00:00:00+00:00

Devise is a flexible authentication solution for Rails based on Warden, I love it because it's very simple to use and easy to extend or override. Many people would say that It's too huge to include all the devise's modules, but what I would say is that, take it easy, agile is the most important, and it's not so huge because of most of the modules are necessary for such a simple project.

Many websites are both enabled username and email to sign in, It will be very friendly to the users, people will unhappy that every time they must type such a long email address. So Let me show you how to allow users to login with username or email using Devise.

First of all, you must have a column named 'username' in your users table.

Then we can start, you should modify the User model and add username to attr_accessible.

    attr_accessible :username

To support both username and email, you should create a login virtual attribute in Users and set the accessible

    # Virtual attribute for authenticating by either username or email
    # This is in addition to a real persisted field like 'username'
    attr_accessor :login
    attr_accessible :login

As default, Devise use :email for authentication in the authentication_keys, so you should tell Devise to use :login in the authentication_keys, modify config/initializers/devise.rb to have:

    config.authentication_keys = [ :login ]

You should overwrite Devise’s find_for_database_authentication method in user model

    # This is for ActiveRecord
    def self.find_for_database_authentication(warden_conditions)
       conditions = warden_conditions.dup
       login = conditions.delete(:login)
       where(conditions).where(["lower(username) = :value OR lower(email) = :value", { :value => login.strip.downcase }]).first
     end
     
     # This is for Mongoid:
     field :email
     
     def self.find_for_database_authentication(conditions)
       login = conditions.delete(:login)
       self.any_of({ :username => login }, { :email => login }).first
     end

Note: This code for Mongoid does some small things differently then the ActiveRecord code above. Would be great if someone could port the complete functionality of the ActiveRecord code over to Mongoid [basically you need to port the ‘where(conditions)’]. It is not required but will allow greater flexibility.

After these settings, make sure you have the Devise views in your project so that you can update devise/sessions/new view.

    #  devise/sessions/new.html.erb
    -  <p><%= f.label :email %><br />
    -  <%= f.email_field :email %></p>
    +  <p><%= f.label :login %><br />
    +  <%= f.text_field :login %></p>

Add i18n translation for login field

    en:
      activerecord:
        attributes:
          user:  
            login: "Username or email"

Yeah, you have done with the configuration to allow user sign in with username or email address, now there is another problem, you also need to allow users to recover their password using either username or email address, right? Let's do it.

Devise set the default reset password keys to :email, so you have to tell Devise to use :loign in the reset_password_keys

    
    # config/initializers/devise.rb
    config.reset_password_keys = [:login]

Devises's finder methods in user model should be overwritten to support both username and email address.

This is for ActiveRecord

    protected

     # Attempt to find a user by it's email. If a record is found, send new
     # password instructions to it. If not user is found, returns a new user
     # with an email not found error.
     def self.send_reset_password_instructions(attributes={})
       recoverable = find_recoverable_or_initialize_with_errors(reset_password_keys, attributes, :not_found)
       recoverable.send_reset_password_instructions if recoverable.persisted?
       recoverable
     end 

     def self.find_recoverable_or_initialize_with_errors(required_attributes, attributes, error=:invalid)
       (case_insensitive_keys || []).each { |k| attributes[k].try(:downcase!) }

       attributes = attributes.slice(*required_attributes)
       attributes.delete_if { |key, value| value.blank? }

       if attributes.size == required_attributes.size
         if attributes.has_key?(:login)
            login = attributes.delete(:login)
            record = find_record(login)
         else  
           record = where(attributes).first
         end  
       end  

       unless record
         record = new

         required_attributes.each do |key|
           value = attributes[key]
           record.send("#{key}=", value)
           record.errors.add(key, value.present? ? error : :blank)
         end  
       end  
       record
     end

     def self.find_record(login)
       where(["username = :value OR email = :value", { :value => login }]).first
     end

These two are all for Mongoid

    # as finder
    def self.find_record(login)
      found = where(:username => login).to_a
      found = where(:email => login).to_a if found.empty?
      found
    end

    # This can be optimized using a custom javascript function
    def self.find_record(login)
      where("function() {return this.username == '#{login}' || this.email == '#{login}'}")
    end

Don't forget to update your view and enjoy

Setting up PPTP VPN on Linode VPS

2011-08-10T00:00:00+00:00

Linode is a VPS hosting company built upon one simple premise: provide the best possible tools and services to those that what they need.

I have a VPS on Linode, my blog runs on it, you can do any thing you want to do. For example we need to set up a PPTP VPN, it was based on Ubuntu Server 11.10 64bit.

Fir of all, you should update your sources.

$ sudo apt-get update
$ sudo apt-get upgrade

Now we can start to install VPN server, It's very easy to be set up with PPTP which is a kind of VPN Protocol.

$ sudo apt-get install pptpd

The only thing left to do is that we should add some configurations for pptpd.

Modify /etc/pptpd.conf, find 'localip' and 'remoteip' and replace with

localip 192.168.13.1
remoteip 192.168.13.50-100

After add the ip scope, we can continue adding users VPN with modifying /etc/ppp/chap-secrets, for example

jerry pptpd 123456 *

BTW, here 'jerry' is your username, '123456' is your password

Well, It's better to set a DNS to make sure pptpd can resove domains successfully when connected to VPN. You can modify /etc/ppp/options, try to find ms-dns and replace with Google's public DNS

ms-dns 8.8.8.8
ms-dns 8.8.4.4

Then modify /etc/sysctl.conf, try to find net.ipv4.ip_forward=1 and enable it.

How to make the settings work? try to run

$ sudo sysctl -p

you also should restart pptpd's server

$ sudo /etc/init.d/pptpd restart

Finally, we should transmit ips witl iptable

$ sudo /sbin/iptables -t nat -A POSTROUTING -s 192.168.13.0/24 -o eth0 -j MASQUERADE

But there is a problem here, when you restart your server, the transmitting will disappear, so we can add it into bootup script. Switch to your root user, create transmition in /etc/init.d/ directory, and add the following script

/sbin/iptables -t nat -A POSTROUTING -s 192.168.13.0/24 -o eth0 -j MASQUERADE

You also have to make transmition executable, using

$ chmod +x transmition
$ update-rc.d transmition defaults

Setting a Capisrano variable to Limit Releases

2011-06-10T00:00:00+00:00

Capistrano is a awesome tool to deploy your projects, Usually when using capistrano, I will go and manually delete old releases from a deployed application long time before. I understand that you can run cap deploy:cleanup but that still leaves 5 releases. But what I want is just keep 3 releases or even less, It's very simple to cleanup old releases to just 3 previous deploy with a capistrano variable, add it to your deploy script.

    set :keep_releases, 3
    after 'deploy:restart', 'deploy:cleanup'

Also there is option 2 to set the the capistrano variable from the command line:

$ cap deploy:cleanup -s keep_releases=3

Curl Problem when Installing Nginx Using Passenger Module

2011-05-03T00:00:00+00:00

I often got this kind of problem when installing nginx using passenger module,

Checking for required software...

 * GNU C++ compiler... found at /usr/bin/g++
 * The 'make' tool... found at /usr/bin/make
 * A download tool like 'wget' or 'curl'... found at /usr/bin/wget
 * Ruby development headers... found
 * OpenSSL support for Ruby... found
 * RubyGems... found
 * Rake... found at /home/jerry/.rvm/wrappers/ruby-1.9.3-p0/rake
 * rack... found
 * Curl development headers with SSL support... not found
 * OpenSSL development headers... found
 * Zlib development headers... found

Some required software is not installed.
But don't worry, this installer will tell you how to install them.

Yes, that's easy to resolve, your system is lack of a package named libcurl4-openssl-dev, You can install it with:

$ sudo apt-get install libcurl4-openssl-dev

Then, run your passenger-install-nginx-module, it will pass all the required packages.

Set up Git Server on Ubuntu Server

2010-06-12T00:00:00+00:00

Git是一个开源的分布式版本控制系统, 用以有效、高速的处理从很小到非常大的项目版本管理.

下面来介绍如何在安装ubuntu server系统的服务器上管理你的项目, 以 linode VPS 为例.

安装git-core和gitosis

$ sudo apt-get install git-core gitosis

线确认你本地机器中是否已经生成过public key, 查看 ~/.ssh/id_rsa.pub, 如果还没有创建你的public key, 就需要通过ssh-keygen来生成:

$ ssh-keygen

执行以上命令后会在 .ssh 目录下生成 id_rsa 和 id_rsa.pub 两个文件,

当然如果你本地机器中如果已经有了public key, 就不需要再生成一次了, 接下来要做的就是在服务器上进行git-server的配置了, 先把你本地的public key scp到服务器的 /tmp 目录下:

$ scp ~/.ssh/id_rsa.pub your_username_here@your_server_ip_here:/tmp

用刚scp上来的public key作为管理者来初始化gitosis:

$ sudo -H -u gitosis gitosis-init < /tmp/id_rsa.pub

完成后，你应该会看到以下信息:

Initialized empty Git repository in /srv/gitosis/repositories/gitosis-admin.git/
Reinitialized existing Git repository in /srv/gitosis/repositories/gitosis-admin.git/

到这里, 刚才的public key已经没有用了, 可以删除

rm /tmp/id_rsa.pub

gitosis的配置已经完成, 接下来就可以把gitosis的管理项目clone到本地进行项目的管理了，前提是在在服务器上必须有你的证书:

git clone gitosis@your_server_ip_here:gitosis-admin.git

取到gitosis-admin这个管理项目后, 我们就可以任意增加项目成员和添加新的项目了, 可以通过编辑配置文件来完成:

cd gitosis-admin
vim gitosis.conf

添加一个名为foo的项目:

[gitosis]

[group gitosis-admin]
writable = gitosis-admin
members = key

[group foo]
writable = foo
members = key

保存该文件，然后提交改动:

git commit -a -m "add a new project"
git push

接下来新建一个项目,来测试一下配置是否正确:

rails new foo
cd foo
git init
git add .
git commit -a -m "first commit"
git remote add origin gitosis@your_server_ip_here:foo.git
git push origin master

项目提交成功。foo这个项目已经可以协作开发了.

Jerry Shen

Using APN Sender to Send Push Notifications to Your IOS Devices

Solution for System Time Error When Compiling Packages

Counter Cache Reset for Counters

Method Missing Best Practice

Running Multiple Rails Versions by Standalone Gemsets with Passenger

Rails Style Guide

Abstract

Table of Contents

Developing Rails applications

Configuration

Routing

Controllers

Models

ActiveRecord

Migrations

Views

Assets

Mailers

Bundler

Priceless Gems

Flawed Gems

Managing processes

Testing Rails applications

Cucumber

RSpec

Views

Controllers

Models

Mailers

Uploaders

Further Reading

Contributing

Spread the Word

Ruby Style Guide

Prelude

Table of Contents

The Ruby Style Guide

Source Code Layout

Syntax

Naming

Comments

Annotations

Classes

Exceptions

Collections

Strings

Percent Literals

Misc

Design

Contributing

Spread the Word

Migrate Blog to Jekyll with Jekyll Extension

Deployment with RVM, nginx, and passenger for ruby on rails

Using Nested Form with Simple Form

Getting Started with RSpec

Installation

RSpec

Configuration

Guard

Configuration

Machinist

Configuration

Supporting Dynamic Fields Form for Mongoid

Customize the Redirect for Devise

Allow Users to Login with Username or Email Using Devise

Setting up PPTP VPN on Linode VPS

Setting a Capisrano variable to Limit Releases

Curl Problem when Installing Nginx Using Passenger Module

Set up Git Server on Ubuntu Server