elegant brew

Ruby on Rails is a web application framework written in the - wait for it - Ruby programming language. For the past few years, my company has been recommending it to our clients for multiple reasons. If you are starting a new web project, I urge you to consider Rails as a potential solution.

1. Rapid Development

Rails was designed for rapid application development. It provides simple commands for generating database tables for storing your data, models for representing your data, views for displaying your data, and controllers for connecting everything together.

Ruby libraries and packages are called “gems”. The open source community has built many gems that make common features available in your app with only a few lines of code. This makes it possible to setup a basic application with user registration, login, and SEO-friendly URLs in minutes.

2. Stability

Rails has been around since 2005. It has changed over the years, but it is definitely not a fad technology that will disappear in the near future. It’s free and open source with nearly 3,000 contributors continuously working to make it better.

The stability of Rails shows in the many well-known companies that have built their platforms upon it. Airbnb, Basecamp, Goodreads, Groupon, Hulu, Indiegogo, and Kickstarter are all using Rails.

3. Testability

Ruby is an extremely flexible language that makes writing testable code easy. The community has built many testing frameworks, and most of them integrate well with Rails.

It’s possible (and highly-recommended) to create an automated test suite that tests all features of your application. This greatly increases confidence that changes in your application have not broken any existing features.

4. JSON APIs

Native mobile device apps (iPhone, Android, etc.) and “single page” web applications are both extremely popular right now. However, these applications still need backends to store data, fetch data, and authenticate users. Rails fills this need by making it easy to build API-only apps or add API support to existing apps.

5. Hassle-free Hosting

Gone are the days of dragging files back and forth in clunky FTP programs and hoping no files are lost. Services like Heroku, Amazon AWS, and Engine Yard make it possible to host your application and deploy updates without the hassle of low-level server maintenance.

Written specifically for developers who have experience with HTML and want to learn how to program, this book provides an introduction to object-oriented programming that will make sense to anyone who has ever built a web page.

Learn how to make this:

div = Div.new(id: 'main') div << 'Hello World!'

turn into this:

<div id="main">Hello World!</div>

Read the free sample or purchase a copy for as low as $10.

My first ebook is complete. Check out a free sample at https://leanpub.com/rubyforwebdesigners. Pickup a copy for as low as $10!

My ebook is almost complete! It is written specifically for developers with HTML experience who want to learn how to program. Each chapter introduces a new programming topic by rebuilding part of a web page in Ruby. If you ever built a web page, this book will make sense!

For now, you can get it for as low as $9.99!

Say you have the following Rails model and you want to list all profiles but sort them by the number of orders the user has placed.

class Profile < ActiveRecord::Base belongs_to :user has_many :purchases, through: :user end

Some users may not have placed any orders, but you still want to display their profiles in the results.

Using .join will work, but it does an inner join by default. This means that profiles of users with zero purchases will not appear in the result set.

You can work around this by writing a custom left outer join so that all profiles will still be included.

It’s amazing what you can do with the geocoder gem by simply adding latitude and longitude attributes to a model and setting up an after_validation callback to populate them based on an address field.

# app/models/restaurant.rb geocode_by :zip after_validation :geocode

Right out of the box, you can find all records within 50 miles of an address.

Restaurants.near("Rehoboth Beach, DE, US", 50)

I was recently faced with an interesting problem. My client’s app has a collection of services. Each service has a zip code and a radius (in miles) within which the service is available. When a visitor enters a zip code, they need to see a list of services that are available in that area.

So, instead of searching for items within a given radius of a zip code, we’re searching for items whose own radius includes a given zip code.

If there were a limited number of records, this could be done by iterating over all of them and keeping those whose distance from the zip code is less than the radius.

coordinates = Geocoder.coordinates(zip_code) @services = Service.all.select { |service| service.distance_from(coordinates) <= service.radius }

We’re dealing with potentially thousands of records. I wanted to find a way to perform this search in the database instead of in code. Here’s what I did…

First, I found that you can use Geocoder::Calculations.bounding_box to get the coordinates for a square containing the radius. If you’re not okay with a larger area and need a circle, this might not be a good solution for you.

I removed the latitude and longitude attributes from the service model and added four new attributes: latitude_lb, latitude_ub, longitude_lb, longitude_ub for the lower and upper bounds of the box. Then, I replaced the geocode callback with a custom method to find and store the coordinates.

# app/models/service.rb after_validation :store_bounding_box def store_bounding_box if zip && delivery_radius coordinates = Geocoder.coordinates(zip) self.latitude_lb, self.longitude_lb, self.latitude_ub, self.longitude_ub = Geocoder::Calculations.bounding_box(coordinates, delivery_radius) end end

Now, we have the the area where each service is available stored in the database. When a user inputs a zip code, we find only the services whose area contains the zip code’s coordinates.

# app/models/service.rb def self.delivers_to_zip(zip) latitude, longitude = Geocoder.coordinates(zip) self.where("latitude_lb <= ? AND latitude_ub >= ? AND longitude_lb <= ? AND longitude_ub >= ?", latitude, latitude, longitude, longitude) end

And in the controller…

# app/controllers/services_controller.rb def index if params[:zip] @services = Service.delivers_to_zip params[:zip] end end

I prefer working with Rails and Drupal (in that order), but, when a client has simpler needs, WordPress can be a great solution. When those needs grow, it can become difficult to bend WordPress to fit the requirements. Enter Pods...

The Pods plugin provides support for custom post types with various fields. If you want to add events to your WordPress site, you can create an Event post type with a date field in addition to the post title and body. However, when you view the event on the front-end, the date field will be nowhere in sight.

You'll end up googling "how to display pod fields" and "how to list pods" and all you'll find is poor documentation. 

You can use short-codes to display the fields, but you shouldn't have to paste a short-code into every event body just to display the date. Additionally, if the events have an optional end date field, you probably need to use PHP to format the date field.

I recently solved this problem by creating a custom object for displaying pods. Let's start by creating a value object with instance variables for guid, post_title, and any custom fields. Set any empty fields to null.

// yourtheme/library/pod_printer.php class PodPrinter { function __construct($pod) { $fields = array_merge( array('guid', 'post_title'), array_keys($pod->api->pod_data['fields']) ); foreach($fields as $field) { $value = trim($pod->display($field)); $this->{$field} = empty($value) ? null : $value; } } } $printer = new PodPrinter($pod); echo $printer->post_title; echo $printer->guid; echo $printer->start_date;

That's a start, but the real use comes in adding custom functions for formatting and outputting the fields. Let's add a method for printing the title as a linked header.

class PodPrinter { // __construct() function print_title() { echo "<div class='pod-title'>"; echo "<h3><a href='{$this->guid}'>{$this->post_title}</a></h3>"; echo "</div>"; return $this; } } $printer = new PodPrinter($pod); $printer->print_title();

Now, we'll extend the PodPrinter to create a subclass specifically for printing events. Notice that the print_date() method handles events with and without end dates. We don't have to worry about that in our templates. Also, by printing the HTML in our methods and returning $this, we can chain the print methods together!

// yourtheme/library/event_printer.php class EventPrinter extends PodPrinter { function print_date() { $start = strtotime($this->start_date); echo "<div class='event-date'>"; echo date('F j Y', $start); if($this->end_date) { $end = strtotime($this->end_date); echo " - " . date('F j Y', $end); } echo "</div>"; return $this; } function print_conference() { // code to print the conference field if set } function print_location() { // code to print the location field if set } } $printer = new EventPrinter($pod); $printer->print_date()->print_conference()->print_location();

Now, let's look at how to use this in our theme.

// yourtheme/functions.php require_once("library/pod_printer.php"); require_once("library/event_printer.php"); // yourtheme/single-event.php <?php $pod = pods('event', get_the_ID()); ?> <?php $printer = new EventPrinter($pod); ?> <?php $printer->print_date(); ?> <?php the_content(); ?>

You can even use it when iterating over a collection of pods.

<?php $pod = pods('event', array()); ?> while($pod->fetch()) { $printer = new EventPrinter($pod); $printer->print_date() ->print_title() ->print_conference() ->print_location(); }

If you’ve read any books about object-oriented software design, you probably heard of the Law of Demeter a.k.a. the Principle of Least Knowledge. This rule can be summed up as “only talk to your friends.” It means that objects shouldn’t reach deep into dependent objects to access their methods and attributes. Violating this rule can lead to tightly-coupled code that will be less adaptable to future changes.

Finding violations is easy. Just count the dots! If you have more than one in a line, you might be violating the rule. Let’s take a look at some code from an ERB template. It displays the name and address of a user.

<%= user.name %><br /> <%= user.address.street %><br /> <%= user.address.city %>, <%= user.address.state %> <%= user.address.zip_code %>

The first line abides by the rule as name is a direct message to the user object. Lines 2 through 5 reach into and access different attributes of the user’s address. This code violates the Law of Demeter.

Does it really matter?

It will matter in the future if we change the way addresses are stored. For example, if we add a user profile and move the address relationship there, our code will have to change. If there are multiple areas of our application where user addresses are displayed, this might cause a real headache.

<%= user.name %><br /> <%= user.profile.address.street %><br /> <%= user.profile.address.city %>, <%= user.profile.address.state %> <%= user.profile.address.zip_code %>

A Potential Solution

One solution is to define methods on User that forward certain messages to the user’s address.

class User attr_reader :address def street address.street end def city address.city end def state address.state end def zip_code address.zip_code end end

Now, we can remove the violation from our template code.

<%= user.name %><br /> <%= user.street %><br /> <%= user.city %>, <%= user.state %> <%= user.zip_code %>

This solution is fine when our objects only have a few attributes. However, if addresses had ten attributes, we would have to define ten new methods on User!

A Cleaner Solution: Delegation

Ruby is an extremely flexible language. The standard library includes a module we can use to easily delegate messages to other objects. This makes it possible to achieve the same result with a lot less code. The code below tells the User class to forward the street, city, state, and zip_code messages to the address.

require "forwardable" class User extend Forwardable delegate [:street, :city, :state, :zip_code] => :address end

A Rails Solution

In Rails, ActiveSupport provides a method for delegation. So, the same result as above can be achieved via the following code.

class User < ActiveRecord::Base delegate :street, :city, :state, :zip_code, to: :address end

Non-violations

At the beginning of this piece, I said that multiple dots might imply a violation because there are some cases when they are perfectly acceptable. For example, methods that return the same object can be chained together without a violation.

user.set_first_name("Bob").set_last_name("Smith")

Similarly, scopes in Rails models which return an ActiveRecord::Relation should not be considered violations as they are modifying the same query.

BlogPost.published.promoted.descending

Finally, methods on Enumerables (e.g. Arrays, Hashes, etc...) that provide a way to iterate over a collection of objects should not be considered violations as they return another Enumerable.

user.friends.each do |friend| ... end

Now What?

Ruby and Rails both make it easy to avoid violating the Law of Demeter. So, take advantage of these tools and start writing cleaner code that is easier to read and maintain.

More Reading

Jim Gay goes into more detail on the differences between forwarding and delegation in his book, Clean Ruby. http://clean-ruby.com

ActiveRecord, while arguably bloated, provides easy, clean methods for performing queries and managing relationships. Unfortunately, not all developers take advantage of this. Let's take a look at some code I recently found in a production app and explore some ways to clean it up.

class Event < ActiveRecord::Base def vendors_attending_event @vendors_attending = [] @category_event_users_on_event = find_category_event_users_by_event @category_event_users_on_event.each do |join| if join.user_id.nil? || join.purchased == nil nil else @vendors_attending << User.find(join.user_id) end end return @vendors_attending end def find_category_event_users_by_event @cat_join ||= CategoryEventUser.find_all_by_event_id(self.id) return @cat_join end end class CategoryEventUser < ActiveRecord::Base attr_accessible :user_id, :event_id, :purchased belongs_to :user belongs_to :event end

The above code works, but it's not pretty. It contains explicit return statements, unnecessary instance variables, and calls to class methods of other, related models.

Let's start with find_category_event_users_by_event. It finds all CategoryEventUsers for the given event and reuses the result for future calls. In the app, this method is never called more than once during a given request. So, memoizing the result provides no benefit. Also, since this method simply finds all CategoryEventUsers for the event, it can be replaced with a has_many relationship.

class Event < ActiveRecord::Base has_many :category_event_users def vendors_attending_event @vendors_attending = [] category_event_users.each do |join| if join.user_id.nil? || join.purchased == nil nil else @vendors_attending << User.find(join.user_id) end end @vendors_attending end end class CategoryEventUser < ActiveRecord::Base attr_accessible :user_id, :event_id, :purchased belongs_to :user belongs_to :event end

Since each CategoryEventUser belongs to a User, we can obtain the User through that relationship without calling User.find.

def vendors_attending_event @vendors_attending = [] category_event_users.each do |join| if join.user_id.nil? || join.purchased == nil nil else @vendors_attending << join.user end end @vendors_attending end

The above method loops over all CategoryEventUsers for the event and builds an array of Users for those with user_id and purchased attributes present. In the app, CategoryEventUsers always have a user_id. So, we don't have to check that. We just care about the purchased attribute. So, let's just tell our relation to only give us purchased records.

def vendors_attending_event @vendors_attending = [] category_event_users.where(purchased: true).each do |join| @vendors_attending << join.user end @vendors_attending end

We can go a step further by using scopes. Scopes are shortcuts for defining queries that can be chained together on a model. In the code below, we create a scope that returns only CategoryEventUsers that are attending the event.

class Event < ActiveRecord::Base has_many :category_event_users def vendors_attending_event @vendors_attending = [] category_event_users.attending.each do |join| @vendors_attending << join.user end @vendors_attending end end class CategoryEventUser < ActiveRecord::Base attr_accessible :user_id, :event_id, :purchased belongs_to :user belongs_to :event scope :attending, where(purchased: true) end

Now, we're just iterating over attending CategoryEventUsers and building an array of their Users. By scrapping the instance variables and taking advantage of Ruby's map method, we can reduce this to a single-line method, and our cleanup is complete!

class Event < ActiveRecord::Base has_many :category_event_users def vendors_attending_event category_event_users.attending.map(&:user) end end class CategoryEventUser < ActiveRecord::Base attr_accessible :user_id, :event_id, :purchased belongs_to :user belongs_to :event scope :attending, where(purchased: true) end

A few months ago, I wrote a post about using the state_machine gem to build mutli-step forms in rails.  

Multi-step forms generally contain a "next" button allowing users to save data entered during the current step and transition another step.  They may also contain a "back" button to transition to the previous step.

I recently worked on a real-world project that featured eight distinct form steps for creating events.  The setup I described in my initial post worked perfectly.  However, the client later decided that they wanted users to be able to jump around between any of the steps they had already completed. 

Without state_machine, a possible solution for this might be to use form objects with separate views and controllers for each "step" of the event creation process.  Then, the links for each step would point to the edit form for that step.

I was not willing to give up on state_machine that easily.  I just spent hours of billable time building the form with state_machine, and it worked.  So, I tried to think of the simplest solution to this issue.  

I started by adding a route that accepted parameters for an event and a state.

resources :events do resources :step, only: [:update], to: "events/step" end

Then, I added a controller to process the step change. The Event#can_transition_to? method performs some checks on the event's attributes to determine if the transition is allowed. I used partials for each state to build the event form. So, after manually updating the state, all I had to do was redirect back to the edit path.

class Events::StepController < ApplicationController def update event = Event.find(params[:event_id]) if event.can_transition_to?(params[:id]) event.update_attributes(state: params[:id]) end redirect_to edit_event_path(event) end end

The final step was to add links for each step:

<%= link_to "Basic Info", event_step_path(event, "basic_info"), method: :put %> <%= link_to "Venue Info", event_step_path(event, "venue_info"), method: :put %>

Do you want to learn how to program? Do you have experience with HTML? Learn how to program by writing Ruby code that can be used to build web pages.

Background A few months ago I launched a Kickstarter campaign for an e-book to help web designers learn about programming. After it failed to get funded, I put the idea on hold. However, I still think the concept is worth pursuing. This will be the first in a series of blog posts showing how to write Ruby code through examples related to building HTML documents.

Object-Oriented Programming

Ruby is an object-oriented language. Classes are templates for creating objects. Objects are instances of classes that have their own state (i.e. data) and behavior. Objects can send and respond to messages. These messages can be used to retrieve or modify the object's state.

The Lesson

Let's jump right in and create a class that represents an HTML div.

class Div end

We can create Div objects like this:

my_div = Div.new your_div = Div.new

However, these objects are useless as we cannot put any content into the divs or print out the HTML they represent. They don't have state or behavior. We need to make some more additions before our Div class is useful.

In Ruby, objects can have initialize methods. The initialize method is called automatically when it is instantiated. Anything passed into a class' .new method gets passed to the initialize method. So, if we add an initialize method to our Div class, we can pass in the content that the div will contain:

class Div def initialize(content) end end

Now, when we create a Div, we can give it some content. However, we need to add some more code to store the content for later use. Ruby objects can have instance variables. Instance variables start with a "@" and store attributes of the object. We can add an instance variable to our Div class to store each Div's content.

class Div def initialize(content) @content = content end end my_div = Div.new("This is my div!")

Now, instances of our Div class can have content, but we still have no way to output the HTML. In Ruby, adding a to_s ("to string") method to a class determines how the object is displayed when used as a string. Any code placed inside #{} in a string is executed and the results are put into the string. Also, the last line of a method determines what is returned from the method. So, let's add a to_s method to our Div class that prints out the HTML code for the Div.

class Div def initialize(content) @content = content end def to_s "<div>#{@content}</div>" end end my_div = Div.new("This is my div!") print my_div # this will print <div>This is my div!</div>

If you setup a Rails 4 app, you'll notice the app/models/concerns and app/controllers/concerns directories.  Concerns are modules that can be mixed into your models and controllers to share code between them.   Some developers falsely classify mixins as composition when they are actually a form of inheritance.  When you include a module in a class, that module's methods are added to the inheritance chain just like a parent class' methods are added to a subclass.  So, don't think you've solved the problem of inheritance by simply splitting your inherited code into separate files! That being said, mixins can be a valuable tool to share code between classes that are otherwise unrelated. Here's an example of how I chose to use it recently. I am adding admin reporting features to an app I'm hoping to launch soon.  I have an admin controller with a simple before filter to redirect if the current user is not an administrator.

class AdminController < ApplicationController before_filter :check_admin_user private def check_admin_user unless current_user.admin flash[:alert] = "You can't be here!" redirect_to root_path end end end

I need two admin reports that allow filtering by month.  To stick with my routing scheme, I want a separate controller for each report.  Both controllers need to load months from the database, build a list of months, get the selected month from the query string or month list, and find records where a specific date field falls within the given month/year.  The only difference is how those records are processed before being used in the views. These are the only two admin features so far.  So, I started by putting the month filtering code in the AdminController so it could easily be shared by both.  However, it's likely that more admin features will be added later that don't need month filters.  More importantly, month filtering isn't intrinsic to   the admin section of the site.  The purpose of the AdminController is to prevent non-admins from accessing the actions.  That's it.  The month filtering code doesn't really belong there.  Where should I put it?  How about in a concern?

# app/controllers/concerns/month_filtering_for_contests.rb module MonthFilteringForContests extend ActiveSupport::Concern included do attr_reader :month, :contests before_filter :build_month_lists before_filter :set_current_month before_filter :load_contests_for_current_month end def build_month_lists @months = Contest.months_with_ended_contests @month_list = @months.map { |date| [date.strftime("%B %Y"), date.strftime("%Y-%m")] } end def set_current_month @month = if params[:month] Date.new(*params[:month].split(/-/).map {|part| part.to_i}) else @months.first end end def load_contests_for_current_month @contests = Contest.ended_during(@month) end end

Now, my AdminController can remain clean and the month filtering module can be included in each report controller.

class Admin::SampleReportController < AdminController include MonthFilteringForContests def show @totals = contests.each_with_object({}) { |contest, hash| # code to process reporting data here } end end

Sometimes it just makes sense to split the record creation process into multiple steps.  The state_machine gem provides easy state management at the model level, but you're still left on your own to keep your controllers and views uncluttered. Here's an example.  Say we have an app with a Person model.  To create a Person, we want to step through the process of adding the name, email address, and phone number separately.  Here's a test-driven walkthrough of how to make that happen. This post assumes we have a Rails 4 app with rspec-rails, capybara, and state_machine installed.  We also have a Person model with string fields for name, email, phone, and state.  For all you TL;DR folk, a repo containing the entire application can be found at https://github.com/psparrow/multistep_model_example.

First I'm going to spec out the Person model and make sure it supports the various states that we need.

Now, we'll create a feature for creating a Person.  

We update our routes and create our controllers to work towards getting the feature to pass.  Because this is a multi-step process, we'll be using the new, create, edit, and update actions of the controller.  To make sure we leave room for editing existing people later, we will make a separate controller for the person creation process.

Finally, we have our views.  Note that by naming partials after the Person states we are able to get away with the controller having very little knowledge of the actual states (except for redirecting after completion).

Our specs are passing and we can walk through creating a Person.  The nice thing about using state_machine is that we can scope our validation rules to the current state of the Person.  We can also make our forms more secure by explicitly specifying which parameters can be accepted during each form state. 

At Kettul Design we maintain a large Drupal 6 app that enforces a policy of expiring passwords after a certain time period.  Our client recently reported that users with expired passwords could not access the password reset form.  

The site uses the password_policy module.  There are no permissions associated with the module that would cause this issue.  After one quick look at the settings page (admin/settings/password_policy/password_change), it became obvious what the likely cause of the problem was...