DEV Community: Alexandre Ruban

Write clean Object-Oriented code by extracting value objects in Rails

Alexandre Ruban — Wed, 03 Nov 2021 14:58:53 +0000

As Ruby on Rails developers, we tend to add too much code in the same ActiveRecord model. Very often, this is because we fail to identify new objects. This article presents a concrete tool that helps keep our ActiveRecord models sizes under control thanks to the serialize method.

Identifying value objects in Rails

Let's take a concrete example. Imagine that we are working on an invoicing system, each invoice being composed of multiple line items. Our Invoice model would look like this:

class Invoice < ApplicationRecord
  has_many :line_items, dependent: :destroy
end

In our example, a LineItem will have a quantity stored as an integer and a unit_price stored as a decimal. The LineItem model would look like this:

class LineItem < ApplicationRecord
  belongs_to :invoice

  validates :quantity, numericality: { only_integer: true, greater_than: 0 }
  validates :unit_price, numericality: { greater_than: 0 }

  def total_price
    (unit_price * quantity).round(2)
  end
end

Let's now imagine a new requirement: we have to handle VAT rates of 0%, 10%, and 20% on line items, 0% VAT rate being for tourist taxes. The most straightforward implementation would probably be to add all of the VAT rates in the LineItem model as it already exists. We would add a tax_code string field in our line_items table, and our LineItem model would start growing:

class LineItem < ApplicationRecord
  # previous associations and validations

  TAX_CODES = { vat_0: 0.0, vat_10: 0.1, vat_20: 0.2 }

  validates :tax_code, inclusion: { in: TAX_CODES.keys.map(&:to_s) }

  def tax_rate
    TAX_CODES[tax_code.to_sym]
  end

  def tourist_tax?
    tax_code.to_sym == :vat_0
  end

  # We now have to take the tax_rate into account
  def total_price
    (unit_price * quantity * (1 + tax_rate)).round(2)
  end
end

This is a very simple example of course but failing to identify value objects creates two issues:

Our LineItem model is doing too much. Failing to identify new objects will make the model longer and longer, and it will harm readability sooner or later.
Tax-related information is now entangled inside of our LineItem model. If we want to reuse tax codes elsewhere in our application, we are stuck.

Tax codes represent something important in our application and we should give them a proper place to live.

Extracting value objects in Rails

We are first going to give this object a new home and a new name. With a few minor changes, we have extracted all the methods in the TaxCode object:

# app/models/tax_code.rb

class TaxCode
  TAX_CODES = { vat_0: 0.0, vat_10: 0.1, vat_20: 0.2 }

  attr_reader :key

  def initialize(key)
    @key = key.to_sym
  end

  def tax_rate
    TAX_CODES[key]
  end

  def tourist_tax?
    key == :vat_0
  end
end

Our LineItem model is now much smaller and focused on its main responsibility as we removed all the tax code related code:

class LineItem < ApplicationRecord
  # previous associations and validations

  validates :tax_code, inclusion: { in: TaxCode::TAX_CODES.keys.map(&:to_s) }

  def total_price
    (unit_price * quantity * (1 + tax_rate)).round(2)
  end

  def tax_rate
    TaxCode.new(tax_code).tax_rate
  end
end

There is still one issue to solve: The LineItem#tax_code does not return a TaxCode object. Let's demonstrate this issue in the rails console:

line_item = LineItem.create(quantity: 1, unit_price: 100, tax_code: :vat_20)
line_item.tax_code
=> "vat_20"

We want to get a TaxCode object when calling the LineItem#tax_code method. Luckily, Rails provides a way to do precisely that, thanks to the serialize method. Let's instruct the LineItem model that its tax_code method should return a TaxCode object:

class LineItem < ApplicationController
  serialize :tax_code, TaxCode

  # all the previous code...
end

For the .serialize method to work, TaxCode should implement both the .load and .dump class methods. As mentioned in the documentation, .dump will be called to serialize an object and should return the serialized value to be stored in the database. On the other hand, .load will be called to reverse the process and deserialize from the database. In our case, that means converting a string into a TaxCode object.

Let's add those two class methods to the TaxCode class:

# app/models/tax_code.rb

class TaxCode
  def self.load(key)
    # We don't want to build TaxCodes with a nil key
    new(key) if key
  end

  def self.dump(tax_code)
    case tax_code
    when self then tax_code.key
    else tax_code
    end
  end

  # all the previous code...
end

Great! Now the LineItem#tax_code method should return a TaxCode object! Let's update the validations and the LineItem#total_price method accordingly:

class LineItem
  # all the previous code
  validates :tax_code, inclusion: { in: TaxCode.all }

  def total_price
    (unit_price * quantity * (1 + tax_code.tax_rate)).round(2)
  end
end

Let's add the .all method on TaxCode and the #== method to be able to compare two tax codes as it is necessary for the inclusion validation to be able to compare them:

# app/models/tax_code.rb

class TaxCode
  # all the previous code...

  def self.all
    TAX_CODES.keys.map { |key| new(key) }
  end

  # Tax codes are equal if they have the same key
  def ==(other)
    if other.is_a?(self.class)
      key == other.key
    end
  end
end

Let's restart our rails console and try again:

line_item = LineItem.create(quantity: 1, unit_price: 100, tax_code: :vat_20)
line_item.tax_code
=> <TaxCode:0x00007fd0c6316728 @key=:vat_20>

That was a lot of work! Let's look at the final implementation of the LineItem model:

class LineItem < ApplicationRecord
  belongs_to :invoice

  validates :quantity, numericality: { only_integer: true, greater_than: 0 }
  validates :unit_price, numericality: { greater_than: 0 }
  validates :tax_code, inclusion: { in: TaxCode.all }

  serialize :tax_code, TaxCode

  def total_price
    (unit_price * quantity * (1 + tax_code.tax_rate)).round(2)
  end
end

As we can see, our model is very small and only focused on line items related calculations. All taxes related code has been extracted to the TaxCode class.

We can notice the same beneficial effects in the TaxCode class. All tax-related code is isolated in a small class with a single responsibility:

# app/models/tax_code.rb

class TaxCode
  TAX_CODES = { vat_0: 0.0, vat_10: 0.1, vat_20: 0.2 }

  def self.load(key)
    new(key) if key
  end

  def self.dump(tax_code)
    case tax_code
    when self then tax_code.key
    else tax_code
    end
  end

  def self.all
    TAX_CODES.keys.map { |key| new(key) }
  end

  attr_reader :key

  def initialize(key)
    @key = key.to_sym
  end

  def tax_rate
    TAX_CODES[key]
  end

  def tourist_tax?
    key == :vat_0
  end

  def ==(other)
    if other.is_a?(self.class)
      key == other.key
    end
  end
end

Our TaxCode model is now completely extracted and can be reused anywhere inside our application!

Serialization in the wild

Admittedly, our value object example is a bit simple. Let's explore a real-world example. ActionText is a part of the Ruby on Rails framework and enables us to add rich text to our applications with just one line of code. To add rich text to an Article model for example, we would simply add the following line to our model:

class Article < ApplicationRecord
  has_rich_text :content
end

Under the hood, the .has_rich_text method defines a has_one association with an object of class ActionText::RichText. The ActionText::RichText object holds the rich text inside the database in a body field that gets serialized in an ActionText::Content object.

module ActionText
  class RichText < Record
    serialize :body, ActionText::Content

    # ...
  end
end

The ActionText::Content object does much more than our simple TaxCode example of course; it defines many more methods! The .load and .dump methods are defined in the ActionText::Serialization concern that is included in ActionText::Content.

Did you like this article?

You can follow me on Twitter as I announce all my articles there!

Write clean Object-Oriented code by replacing conditional with polymorphism

Alexandre Ruban — Mon, 05 Jul 2021 14:53:16 +0000

In this article, I will talk about a refactoring called replace conditional with polymorphism that we did recently at Kactus. By the end of the article, you will be able to identify probably many places where you could use this technique in your Rails application. Let's get started.

A little bit of context

Kactus is a marketplace and, because of European regulations, we have a quite complex invoicing system. To keep this article simple, we will only talk about the two different types of invoices that we have:

Marketplace invoices are not part of Kactus revenue. They represent money transfers from the client to the provider where Kactus only acts as a middleman.
Revenue invoices are issued by Kactus to account for our commission on each booking.

Those two different kinds of invoices are cashed into separate bank accounts. For the accountants to understand which bank account they should send the money, those bank accounts have a different IBAN number. To display the correct IBAN number in the PDF invoices and on the website, we use conditionals:

# Invoice PDF view

<% if @invoice.marketplace? %>
  IBAN number of the marketplace bank account
<% else %>
  IBAN number of the revenue bank account
<% end %>

We also display the IBAN number directly on the website on the show page of each invoice:

# Invoice show page 

<% if @invoice.marketplace? %>
  IBAN number of the marketplace bank account
<% else %>
  IBAN number of the revenue bank account
<% end %>

On the invoice show page, we also display the name of the bank account and a URL for the user to download its associated information:

# Invoice show page 

<% if @invoice.marketplace? %>
  Name of the marketplace bank account
<% else %>
  Name of the revenue bank account
<% end %>

We also use the URL of the bank account information in the mailers to attach the correct PDF to our transactional emails:

# Invoice mailer

if @invoice.marketplace?
  attachments["RIB Kactus.pdf"] = URL of the marketplace bank account
else
  attachments["RIB Kactus.pdf"] = URL of the revenue bank account
end

Can you already see where I am going with this article? Can you see the repeated conditional that's spreading everywhere throughout our application?

# Everywhere

if @invoice.marketplace?
  ...
else
  ...
end

That's what we are going to learn how to solve.

Here comes the new requirement

Our finance director wants us to use two different bank accounts for marketplace invoices:

One bank account is for invoices sent to Kactus's premium accounts
One other bank account for all other marketplace invoices

What are we going to do? Add more if statements everywhere?

# Everywhere

<% if @invoice.marketplace? && @invoice.recipient.premium_account? %>
  # ...
<% elsif @invoice.marketplace? %>
  # ...
<% else %>
  # ...
<% end %>

Of course not, that would be a maintenance nightmare. It's time for a refactoring.

The replace conditional with polymorphism refactoring

Creating the missing bank account object

When I was describing the problem, there is something interesting to notice. I talked about bank account but when writing code, I never wrote bank account anywhere. We are missing an important object here.

# app/models/bank_account.rb

class BankAccount
end

That's already a huge win. We have a new object in our application that represents an important concept in real life. Note that this is a Plain Old Ruby Object, it does not inherit from ActiveRecord::Base or ApplicationRecord. You can of course add simple models like this one into your app/models folder.

Removing the if statements with a factory method

A factory method is a method that's sole purpose is to create other objects. This sounds complicated. Let's explain it easier: a factory method is the only place where if statements related to choosing bank accounts reside. By convention, we name it ".for" and it's a class method.

# app/models/bank_account.rb

class BankAccount
  # The factory `.for` method is the only place in the application
  # where the if statements should appear
  def self.for(invoice)
    if invoice.marketplace? && invoice.recipient.premium_account?
      PremiumMarketplace
    elsif @invoice.marketplace?
      DefaultMarketplace
    else
      Revenue
    end.new
  end
end

Notice how our factory method returns a new instance of BankAccount::PremiumMarketplace, BankAccount::DefaultMarketplace or, BankAccount::Revenue classes? That's exactly what a factory method is used for. Let's create those 3 missing objects now:

Creating the missing objects

All the new objects here should have the same interface. If they have the same interface, they can be substituted. That's what polymorphism is. Let's write the code of our 3 new objects:

# app/models/bank_account/premium_marketplace.rb

class BankAccount::PremiumMarketplace
  def name
    "Premium marketplace bank account name"
  end

  def iban_number
    "Premium marketplace bank account IBAN number"
  end

  def iban_url
    "Premium marketplace bank account IBAN URL"
  end
end

# app/models/bank_account/default_marketplace.rb

class BankAccount::DefaultMarketplace
  def name
    "Default marketplace bank account name"
  end

  def iban_number
    "Default marketplace bank account IBAN number"
  end

  def iban_url
    "Default marketplace bank account IBAN URL"
  end
end

# app/models/bank_account/revenue.rb

class BankAccount::Revenue
  def name
    "Revenue bank account name"
  end

  def iban_number
    "Revenue bank account IBAN number"
  end

  def iban_url
    "Revenue bank account IBAN URL"
  end
end

See how simple those objects are? Every Ruby developer can understand them very easily. The last step is now to clean our views, mailers, and models that depend on the conditional seen earlier. Let's do it.

Cleaning up our previous code

First, let's make it really easy for us to access the bank account. On the Invoice model, we will create a getter to access the correct bank account for a given invoice.

# app/models/invoice.rb

class Invoice < ApplicationRecord
  def bank_account
    @bank_account ||= BankAccount.for(self)
  end
end

And now let's see the benefits of our refactoring everywhere in our application where we used to have if statements.

# Everywhere

# No more if statemements, we replaced conditional
# with polymorphism

@invoice.bank_account.name
@invoice.bank_account.url
@invoice.bank_account.iban_number

There are other advantages, to this architecture:

Next time, when our finance director asks us to add a new bank account, it will be really easy to do so. Simply add a conditional at a single place in the factory method and add a new class for the additional bank account.
When a new member of the team is given the task to change something related to bank accounts, the architecture is already in place. No one will need to struggle with maintaining the same conditional everywhere throughout the application.

Conclusion

The replace conditional with polymorphism is a well know refactoring that will provide value immediately in your team by making maintenance easier and prevent bugs in the future. If you want to learn more about it, you can read the amazing 99 bottles of OOP book by Sandi Metz.

Rebuilding FactoryBot in 150 lines of code

Alexandre Ruban — Mon, 28 Jun 2021 15:10:45 +0000

FactoryBot is a gem that enables you to create fake data for your tests. If you work with Ruby on Rails, there are good chances that you worked with the gem on a few projects.

In this article, we will rebuild a FactoryBot clone called TinyFactory in about 150 lines of code. We will learn amazing Ruby features such as:

How the elegant FactoryBot syntax works under the hood
How to create a gem
How to use blocks and procs
How to use #method_missing and #instance_eval

By the end of the article, you will know enough to go through the source code of the real factory bot repository on your own if you want to! To get the most out of this article, you should take your time and build the gem with me, it is guided step by step for you to understand everything! Are you ready to learn some cool things in Ruby? Let's get started!

Creating the TinyFactory gem

Let's start by creating a new gem called TinyFactory with the bundle gem command:

bundle gem tiny_factory
cd tiny_factory

If you're creating a gem for the first time, I'll quickly describe the main files that were created for you, otherwise, you can skip directly to the next section!

The tiny_factory.gempspec file contains the specification of your gem. It lists various information about the gem, the author, and the list of the dependencies.

The Rakefile looks like this by default:

# frozen_string_literal: true

require "bundler/gem_tasks"
require "rake/testtask"

Rake::TestTask.new(:test) do |t|
  t.libs << "test"
  t.libs << "lib"
  t.test_files = FileList["test/**/*_test.rb"]
end

task default: :test

This code means that the default rake task will run all the test files of the test folder ending with _test.rb. To run this default rake task, simply type bundle exec rake in your terminal.

The test folder contains the tests you'll write to test your gem. The test_helper.rb file comes with some boilerplate code to automatically add the files from your lib folder in the load path. We will write some tests in this article later!

Finally, the lib folder is where you will write your source code!

All the Ruby gems are built with these conventions, so next time you open the source code of a gem, you will find the same folder hierarchy and you won't be lost!

Testing the TinyFactory gem

Adding an integration test

To clearly define what we will build in this article, let's first write an integration test! We will consider that we have succeeded in our mission when all the integration tests are green! Let's create a file called integration_test.rb in our test folder:

# test/integration_test.rb

require "test_helper"

class IntegrationTest < Minitest::Test
  def setup
    TinyFactory.define :user do
      first_name { "Alexandre" }
      last_name { "Ruban" }
      email { "#{first_name}@hey.com".downcase }
    end
  end

  def test_attributes_for
    attributes = attributes_for(:user)

    assert_kind_of Hash, attributes

    assert_equal "Alexandre",         attributes[:first_name]
    assert_equal "Ruban",             attributes[:last_name]
    assert_equal "alexandre@hey.com", attributes[:email]
  end

  def test_build
    user = build(:user)

    assert_kind_of User, user
    assert user.new_record?

    assert_equal "Alexandre",         user.first_name
    assert_equal "Ruban",             user.last_name
    assert_equal "alexandre@hey.com", user.email
  end

  def test_create
    user = create(:user)

    assert_kind_of User, user
    assert user.persisted?

    assert_equal "Alexandre",         user.first_name
    assert_equal "Ruban",             user.last_name
    assert_equal "alexandre@hey.com", user.email
  end
end

As you can see, the syntax in the #setup method is close to the real FactoryBot syntax. This is what we will build step by step in this article!

To make our test pass later, we still need to add a little bit of boilerplate.

Adding the required dependencies

To make our test pass, we need to add a User model to our application. This User model will inherit from ActiveRecord::Base to simulate a real model in a Rails application.

Let's add all the dependencies we need in the gemspec:

# tiny_factory.gemspec

require_relative "lib/tiny_factory/version"

Gem::Specification.new do |spec|
  # ...
  # Don't remove the automatically generated code
  # Add these dependencies at the end

  spec.add_development_dependency("activerecord", "~> 6.1")
  spec.add_development_dependency("sqlite3", "~> 1.4.2")
  spec.add_dependency("activesupport", "~> 6.1")
end

As you can see, we add a development dependency on active record and sqlite3. This is because we'll need a User model inheriting from ActiveRecord::Base. We will also need to save User instances in a sqlite3 database in memory.

Note that we also added a dependency on active support that we will talk about later in the article.

Now that we listed the dependencies, we can run the bundle install command. Bundler might complain that there are some "TODO" in the gemspec file. Removing them should enable you to run bundle install without any troubles!

Creating our User model

Let's create the User model in the test_helper.rb file:

# test/test_helper.rb

require "tiny_factory"
require "minitest/autorun"
require "active_record"

ActiveRecord::Base.establish_connection(
  database: ":memory:",
  adapter: "sqlite3"
)

class CreateSchema < ActiveRecord::Migration[6.0]
  def self.up
    create_table :users, force: true do |t|
      t.string  :first_name
      t.string  :last_name
      t.string  :email
    end
  end
end

CreateSchema.migrate(:up)

class User < ActiveRecord::Base
  validates :first_name, :last_name, :email, presence: true
end

This piece of code creates a new connection to a sqlite3 database in memory, runs a migration that creates the users table, and creates the User model that inherits from ActiveRecord::Base just like you would do in a Rails application. As we required the "test_helper" in our integration_test.rb file, the User model will be available here as well!

Now that our test files and our dependencies are all set, we are ready to dive into the FactoryBot code!

The two steps of FactoryBot

FactoryBot works in two steps:

You define a factory
You run the factory

The definition is what happens when we write those lines in our integration test.

TinyFactory.define :user do
  first_name { "Alexandre" }
  last_name { "Ruban" }
  email { "#{first_name}@hey.com".downcase }
end

We then run the factory when we use one of the methods #attributes_for, #build or #create.

Defining a Factory

We will start this article by understanding how to define the :user factory of our integration test. The definition relies on two simple classes: Factory and Attribute. Let's understand them!

The Factory class

The Factory class is responsible for holding the factory name and the attributes' definitions! Let's make that clear with a piece of code:

# lib/tiny_factory/factory.rb

module TinyFactory
  class Factory
    # A factory has a factory_name and holds the attributes
    attr_reader :factory_name

    def initialize(factory_name)
      @factory_name = factory_name
      @attributes = []
    end

    # Here comes the Attribute object!
    def add_attribute(name, definition)
      @attributes << Attribute.new(name, definition)
    end
  end
end

In our example, the factory_name is :user and the attributes are first_name, last_name, and email.

Now that we understand that our Factory holds its name and adds attributes definitions to a list of attributes, let's move on to the Attribute class.

The Attribute class

The Attribute class is the simplest of all! It's only responsible for holding an attribute name and its definition.

# lib/tiny_factory/attribute.rb

module TinyFactory
  class Attribute
    def initialize(name, definition)
      @name = name.to_sym
      @definition = definition
    end
  end
end

Let's take our email attribute as an example. When we write email { "#{first_name}@hey.com".downcase } in the integration test, what we are creating under the hood is an Attribute with its name equals to :email and its definition equals to a proc that we could write like this Proc.new { "#{first_name}@hey.com".downcase }

Now, if you're not familiar with procs, you will understand them much more after reading this article so keep going!

A proc is an object that holds a piece of code that will be evaluated later! Here, the definition Proc.new { "#{first_name}@hey.com".downcase } has not been evaluated yet! It is a piece of code waiting to be called. We will see later in the article that the definition is evaluated when you run the factory.

Adding syntactic sugar

Now that we have the Factory and the Attribute objects, it's time to reveal the mysteries behind this beautiful syntax:

TinyFactory.define :user do
  first_name { "Alexandre" }
  last_name { "Ruban" }
  email { "#{first_name}@hey.com".downcase }
end

With the Factory and Attribute classes we just coded, we could define a factory like this:

factory = TinyFactory::Factory.new(:user)
factory.add_attribute(:first_name, Proc.new { "Alexandre" })
factory.add_attribute(:last_name,  Proc.new { "Ruban" })
factory.add_attribute(:email,      Proc.new { "#{first_name}@hey.com".downcase })

This works but it is not very elegant.

We are building a gem that will be used by a lot of developers and we want it to have an easy-to-remember API. To make our syntax elegant, we will add syntactic sugar. This means that our gem will keep the same features it already has but we will make the API easier to write and remember.

Let's transform our current syntax into the elegant syntax. First, we need to add the TinyFactory.define method:

# lib/tiny_factory.rb

# This was generated by the `bundle gem tiny_factory` command
require "tiny_factory/version"

# You need to require the files we just created
require "tiny_factory/factory"
require "tiny_factory/attribute"

module TinyFactory
  def self.define(name, &block)
    factory = Factory.new(name)
    factory.instance_eval(&block)
    factory
  end
end

The Tinyfactory.define method instanciates a new Factory (with a name of :user in our example) and then calls #instance_eval with the block on it! What does the #instance_eval method do? It evaluates the block in the context of the instance on which it was called. This means that factory.instance_eval(&block) is equivalent in our example to writing:

factory.first_name { "Alexandre" }
factory.last_name  { "Ruban" }
factory.email      { "#{first_name}@hey.com".downcase }

All right but our factory does not respond to #first_name or #last_name or even #email! It only responds to #add_attribute. Let's change that by adding the #method_missing method to our Factory class.

What is #method_missing? It's a Ruby method that gets called when the method was not found on the object or any of its ancestors! Let's do a small example for you to understand:

class Random
end

Random.new.email
# => undefined method `email' for #<Random:0x00007fa950a840e8> (NoMethodError)

As you can see, calling email on an instance of the Random raises a NoMethodError. We can change that by adding method_missing to the Random class

class Random
  def method_missing(name, *args, &block)
    puts "The method #{name} was called"
    puts "The method was called with #{args} as arguments" if args.any?
    puts "The method was also given a block" if block
  end
end

Random.new.first_name
# => The method first_name was called


Random.new.names("Alexandre", "Ruban")
# => The method names was called
# => The method was called with ["Alexandre", "Ruban"] as arguments

Random.new.email { "#{first_name}@hey.com".downcase }
# => The method email was called
# => The method was also given a block

As you can see, #method_missing prevents the NoMethodError. The name of the missing method that was called on the object becomes the first argument of #method_missing. The arguments of the missing method that was called can be retrieved with *args which turns those arguments into an array. Last but not least if a block was passed to the missing method it can be transformed as a proc and passed as an argument!

What we want is to make those two syntax equivalent:

factory.add_attribute(:email) { "#{first_name}@hey.com".downcase }
factory.email { "#{first_name}@hey.com".downcase }

This can be achieved with #method_missing like this:

# lib/tiny_factory/factory.rb

module TinyFactory
  class Factory
    # All the previous code
    # ...

    def method_missing(name, &block)
      add_attribute(name, block)
    end
  end
end

Now calling #first_name and passing a block to an instance of Factory is equivalent to calling #add_attribute with :first_name and passing the block!

What is the & signed used for before the block? It is used to convert a block to a proc and vice versa. If you pass a block to a function, &block will convert it to a proc that you can store for later evaluation. Similarly, if you have a variable my_proc that stores a proc, &my_proc will convert the proc to a block. It's as simple as that!

This is what syntactic sugar is! You are only making the API simpler to remember and more elegant!

Adding a factory registry

There is one last thing we need to do to complete our factory definition! We want to store all the defined factories in a registry to be able to retrieve them later based on their name. This will be useful when running one factory.

Let's add this feature very quickly when we define the Factory:

# lib/tiny_factory.rb

module TinyFactory
  @factories = []

  def self.factories
    @factories
  end

  def self.register_factory(factory)
    factories << factory
  end

  # Edit the .define method here
  def self.define(name, &block)
    factory = Factory.new(name)
    factory.instance_eval(&block)
    register_factory(factory)
    factory
  end

  # All the previous code
  # ...
end

Now all the factories that are defined are stored in the TinyFactory.factories array!

Wow! Nice work our Factory :user is now correctly defined!
Let's manually test it to see what happens by creating a test.rb file at the root of the project:

# test.rb

# This line enables you to require "tiny_factory" here
# You do not need to understand it
$LOAD_PATH.unshift File.expand_path("./lib", __dir__)
require "tiny_factory"

factory = TinyFactory.define :user do
  first_name { "Alexandre" }
  last_name { "Ruban" }
  email { "#{first_name}@hey.com".downcase }
end

p factory

If we then run this script in the console, here is what we get:

ruby test.rb

# =>
# #<TinyFactory::Factory:0x00007f93f305d000
#   @factory_name=:user,
#   @attributes=[
#     #<TinyFactory::Attribute:0x00007f93f305cd58
#       @name=:first_name,
#       @definition=#<Proc:0x00007f93f305ce20 test.rb:5>>,
#     #<TinyFactory::Attribute:0x00007f93f305cc90
#        @name=:last_name,
#        @definition=#<Proc:0x00007f93f305ccb8 test.rb:6>>,
#     #<TinyFactory::Attribute:0x00007f93f305cb28
#       @name=:email,
#       @definition=#<Proc:0x00007f93f305cb78 test.rb:7>>
#   ]>

As we can see, we get back a Factory object with a factory_name of :user and holding three attributes :first_name, :last_name and :email, each of them holding their definition proc!

That's a great achievement already! Now it's time for us to run the factory with one of the three methods #attributes_for, #build or #create!

Running a Factory

Now that our Factory is defined, we need to run it. In our example it can mean three things:

Return a hash of attributes (#attributes_for)
Return a built instance (#build)
Return a created instance persisted in the database (#create)

We will start by making #attributes_for work and then it will be very easy to add the #buildand #createfeatures.

Making the attributes_for strategy work

For each of these three methods, we will define a strategy. Let's start with the AttributesFor strategy:

# lib/tiny_factory/strategy/attributes_for.rb

module TinyFactory
  class Strategy
    class AttributesFor
      def initialize
        @result = {}
      end

      def get(attribute)
        @result[attribute]
      end

      def set(attribute, value)
        @result[attribute] = value
      end

      def result
        @result
      end
    end
  end
end

The AttributesFor class is responsible for holding the result which is the hash of attributes that attributes_for(:user) returns in our integration test! What can we do with this class? We can get attributes from the result hash, set attributes to the result hash and, get the final result of our computation! Easy!

Now let's see how we can run this strategy! We will use TinyFactory.attributes_for(:user) for now instead of attributes_for(:user). This syntactic sugar will be added at the end of the article!

Let's add the TinyFactory.attributes_for method:

# lib/tiny_factory.rb

# All the previous requires
#...
# /!\ Don't forget to add this new require
require "tiny_factory/strategy/attributes_for"

module TinyFactory
  # All the previous code
  # ...

  def self.attributes_for(factory_name)
    find_factory(factory_name).run(Strategy::AttributesFor)
  end

  def self.find_factory(factory_name)
    factories.find { |factory| factory.factory_name == factory_name }
  end
end

As you can see, we defined a TinyFactory.attributes_for method that looks for the factory by its name and the calls #run on it with the AttributesFor strategy class!

Let's add the #run method to the Factory class:

# lib/tiny_factory/factory.rb

module TinyFactory
  class Factory
    # All the previous code
    # ...

    def run(strategy_class)
      strategy = strategy_class.new
      @attributes.each do |attribute|
        attribute.add_to(strategy)
      end
      strategy.result
    end
  end
end

As you can see here, we create a new instance of the strategy class, then iterate through all the attributes of the factory and add each attribute to the strategy thanks to the Attribute#add_to method. Finally, we return the strategy result.

You guessed it, we are missing a #add_to method on the Attribute class. Let's add it:

# lib/tiny_factory/attribute.rb

module TinyFactory
  class Attribute
    def initialize(name, definition)
      @name = name
      @definition = definition
    end

    def add_to(strategy)
      # Not the final implementation
      strategy.set(@name, @definition.call)
    end
  end
end

Let's explain the #add_to method carrefully because there is a trick!

In our integration test example, our user factory has a first_name attribute and its definition is equivalent to Proc.new { "Alexandre" }. In this case @definition.call return "Alexandre". That means that when we do strategy.set(@name, @definition.call) we are adding to the result hash, the key :first_name and the value "Alexandre"

Now let's take a look at our email attribute and its definition that is equivalent to Proc.new { "#{first_name}@hey.com".downcase }. This is more complicated because the #first_name method is not defined on the email attribute! How might we retrieve its value? We need to have a look at the strategy. But the strategy does not respond to the first_name method either. What are we going to use? You probably guessed it: method_missing!

# lib/tiny_factory/strategy/attributes_for.rb

module TinyFactory
  class Strategy
    class AttributesFor
    # All the previous code
    # ...

    def get(attribute)
      @result[attribute]
    end

    def method_missing(attribute)
      get(attribute)
    end
  end
end

Now our strategy responds to the #first_name method and returns the value that was set earlier on the result hash of the strategy instance.

The final implementation of the #add_to method is as follows:

# lib/tiny_factory/attribute.rb

module TinyFactory
  class Attribute
    def initialize(name, definition)
      @name = name
      @definition = definition
    end

    def add_to(strategy)
      strategy.set(@name, strategy.instance_eval(&@definition))
    end
  end
end

Notice the & before @definition? It converts the @definition proc to a bloc. Remember, the & sign before a block converts it to a proc and the & sign before a proc converts it back to a block, it's as simple as that!

We did it!

In the integration test, if you replace #attributes_for(:user) with TinyFactory.attributes_for(:user), the test is green! We'll add the syntactic sugar to avoid having to write TinyFactory at the end of the article but that"s already a huge step forward!

Making the build strategy work

To do this, we need to add a TinyFactory::Strategy::Build:

# lib/tiny_factory/strategy/build.rb

module TinyFactory
  class Strategy
    class Build
      # One small difference here, the strategy needs to be
      # initialized with a class. In our example, as we are building
      # a User instance, our build strategy will be initialized with the
      # User class.
      def initialize(klass)
        @instance = klass.new
      end

      def get(attribute)
        @instance.send(attribute)
      end

      def set(attribute, value)
        @instance.send("#{attribute}=", value)
      end

      def method_missing(attribute)
        get(attribute)
      end

      def result
        @instance
      end
    end
  end
end

Notice how it's almost the same as the AttributesFor strategy? The result of the strategy is not a Hash but an instance of the class passed to the initialize method. This means that to read an attribute, we need to send the attribute name to the instance, and to set an attribute with some value, we need to send the message #{attribute}= with the value.

As you noticed, we changed the number of arguments taken by the initialize method of a strategy. We want all our strategies to have the same API to make them interchangeable. This is known in Object-Oriented Programming as polymorphism. Let's change the AttributesFor strategy so that is also initialized with an argument:

module TinyFactory
  class Strategy
    class AttributesFor
      # We use an underscore here to indicate the argument passed is never used
      def initialize(_)
        @result = {}
      end

      # All the rest of the code
    end
  end
end

Even if we don't use the argument passed to initialize in the AttributesFor strategy, we still add it because we want to keep the same API between all of our strategies. This is called polymorphism and it's one of the most powerful features of OOP! If we didn't do that, we would need to check with if and else statements if the strategy we are using is AttributesFor or Build. This is called type checking and it's a code smell!

Let's go back to our Build strategy. We said that we are creating an instance of a class, but which class? By convention, when we create a factory with a name of :user, the class of the instance we build will be User! Let's add a tiny bit of code to create this convention:

# lib/tiny_factory/factory.rb

module TinyFactory
  class Factory
    # All the previous code

    def run(strategy_class)
      strategy = strategy_class.new(build_class)
      @attributes.each do |attribute|
        attribute.add_to(strategy)
      end
      strategy.result
    end

    private

    def build_class
      # This is why we need ActiveSupport as a dependency.
      # `classify` and `constantize` are Active Support methods.
      factory_name.to_s.classify.constantize
    end
  end
end

Thanks to ActiveSupport#classify and ActiveSupport#constantize, a factory with a name of :user will have a build_class of User and a factory with a name of :billing_information will have a build_class of BillingInformation. This is the convention we created! We guess the class to pass to the strategy from the name of the factory!

Wow! That's great progress!

One last thing to make it work, we need to require the file in our tiny_factory.rb and create the .build method.

# lib/tiny_factory.rb

# /!\ Add this require to the list
require "tiny_factory/strategy/build"

module TinyFactory
  # All the previous code

  def self.build(factory_name)
    find_factory(factory_name).run(Strategy::Build)
  end
end

You can now check that both the #attributes_for and the #build integration tests pass if you replace attributes_for(:user) with TinyFactory.attributes_for(:user) and build(:user) with TinyFactory.build(:user)!

Making the create strategy work

This one is much much easier, we already did all the work! We simply need to add our TinyFactroy::Strategy::Create:

# lib/tiny_factory/strategy/create.rb

module TinyFactory
  class Strategy
    class Create < Build
      def result
        @instance.save!
        @instance
      end
    end
  end
end

The Create strategy is the same as the Build strategy except that we
need to save! the result instance in the database before we return it. To do this we make the Create strategy inherit from the Build strategy and simply override the #result method.

Once again, let's add the TinyFactory.create method and require the create_strategy.rb file:

# lib/tiny_factory.rb

# /!\ Add this require to the list
require "tiny_factory/strategy/create"

module TinyFactory
  # All the previous code
  # ...

  def self.create(factory_name)
    find_factory(factory_name).run(Strategy::Create)
  end
end

You can now make the create integration test pass by using TinyFactory.create(:user) instead of create(:user).

You did it!

Let's now add one last piece of syntactic sugar and we will be done with this FactoryBot clone and you will know enough to dig through the real source code!

The TinyFactory::Syntax::Default module

In our tests, we want to use attributes_for(:user) instead of TinyFactory.attributes_for(:user), it is too verbose and we care about the syntax we will use every day as developers!

Let's add one last piece of syntactic sugar by creating a TinyFactory::Syntax::Methods module:

# lib/tiny_factory/syntax/methods.rb

module TinyFactory
  module Syntax
    module Methods
      def attributes_for(name)
        TinyFactory.attributes_for(name)
      end

      def build(name)
        TinyFactory.build(name)
      end

      def create(name)
        TinyFactory.create(name)
      end
    end
  end
end

The three methods created here only delegate to the TinyFactory module. This is very simple but will improve our experience as developers when we use the library!

To use this module we simply need to add this line in our test helper and to require the file in tiny_factory.rb:

# lib/tiny_factory.rb

# Add this require statement
require "tiny_factory/syntax/methods"

# test/test_helper.rb

# All the previous code
# ...
class Minitest::Test
  include TinyFactory::Syntax::Methods
end

How does this work? Our integration test inherits from Minitest::Test. By including our syntactic sugar module in Minitest::Test we automatically gain access to the #attributes_for, #build and #create methods that delegate to the TinyFactory module!

Let's run the integration test from the beginning of the article now. Everything should be green, you are now able to understand how FactoryBot works! Congratulations!

Takeaways

In this articles, we learned:

To create a gem with the bundle gem command
To convert a block to a proc and vice versa with the & character
To intercept class to undefined methods on an object thanks to #method_missing
That polymorphism is an important concept in Object-Oriented Programming. If you want to learn more about the topic I highly recommend the 99 bottles of OOP book by Sandi Metz
That it is possible to add syntactic sugar to your code to make it more elegant and easy to remember
How the real FactoryBot works!

Did you like this article?

If you liked this article and want to be notified when I publish more, follow me on Twitter! Feel free to share this article with your developer friends and coworkers!

Infinite scroll pagination with Rails and Stimulus

Alexandre Ruban — Mon, 21 Jun 2021 15:15:29 +0000

In this article, we'll learn how to build an infinite scroll pagination system using only a few lines of code. We will create a very simple Rails application and implement the infinite scroll feature in a Stimulus Controller that you can reuse to paginate all the resources of your app. We will do this step by step so let's begin!

Creating the Rails application

Let's start by creating a new Rails application with Stimulus installed:

rails new infinite-scroll-article --webpack=stimulus

We'll start by building a pagination feature that works without any Javascript. Let's first create a model Article with a string title and a text content.

rails g model Article title content:text
rails db:migrate

Now that we have our Article model, let's create a seed that creates 100 articles for us to paginate.

# db/seeds.rb

puts "Remove existing articles"
Article.destroy_all

puts "Create new articles"
100.times do |number|
  Article.create!(
    title: "Title #{number}",
    content: "This is the body of the article number #{number}"
  )
end

To persist those 100 articles in the database, let's run the command:

rails db:seed

We are good to go for the model part, let's now create a controller with only the #index method and the corresponding view to display those 100 articles.

rails g controller articles index

In the routes file, let's make our articles list the home page:

# config/routes.rb

Rails.application.routes.draw do
  root "articles#index"
end

In the controller, let's query all the articles from the database:

# app/controllers/articles_controller.rb

class ArticlesController < ApplicationController
  def index
    @articles = Article.all
  end
end

Finally, let's display all of our 100 articles in the view.

<!-- app/views/articles/index.html.erb -->

<h1>Articles#index</h1>

<% @articles.each do |article| %>
  <article>
    <h2><%= article.title %></h2>
    <p><%= article.content %></p>
  </article>
<% end %>

You can now launch your local server rails s and webpack server webpack-dev-server and see on the homepage the list of 100 articles we just created!

We're now ready to add a very simple pagination as a second step.

Adding pagination without the infinite scroll

For the pagination, we will use a very simple gem created by the Basecamp team called geared pagination. It is very small (less than 50 commits at the time I write this article) and very well written.

Let's add the gem to our Gemfile and install it. Don't forget to restart your server after that!

bundle add geared_pagination
bundle install

Using the gem is very easy, we just have to use the set_page_and_extract_portion_from method in the controller like this:

# app/controllers/articles_controller.rb

class ArticlesController < ApplicationController
  def index
    # Note that we specify that we want 10 articles per page here with the
    # `per_page` option
    @articles = set_page_and_extract_portion_from Article.all, per_page: [10]
  end
end

In the view, we simply have to add the pagination logic at the end of the page:

<!-- app/views/articles/index.html.erb -->

<h1>Articles#index</h1>

<% @articles.each do |article| %>
  <article>
    <h2><%= article.title %></h2>
    <p><%= article.content %></p>
  </article>
<% end %>

<% unless @page.last? %>
  <%= link_to "Next page", root_path(page: @page.next_param) %>
<% end %>

The pagination works! Click on the next page link to see the page changing. But that's not what we want! What we want is an infinite scroll and that's the most interesting part of this article!

Adding the infinite scroll pagination with Stimulus

The infinite scroll will work as follow:

Every time the viewport intersect the hidden next page link, we will trigger an AJAX request to get the additional articles
We will then append those articles to the list and replace the current next page link with the next one
We will then repeat the process until we reach the last page!

Are you ready? Let's go!

First, let's create a pagination controller with Stimulus and connect it to our articles index page.

Let's add a nextPageLink target and log it in the console when the controller initialized.

// app/javascript/controllers/pagination_controller.js

import { Controller } from "stimulus"

export default class extends Controller {
  static targets = ["nextPageLink"]

  initialize() {
    console.log(this.nextPageLinkTarget)
  }
}

To make it work, we also need to update our HTML by adding data-controller="pagination" to the articles list and data-pagination-target="nextPageLink" to the next page link. Our index code now looks like this:

<!-- app/views/articles/index.html.erb -->

<div data-controller="pagination">
  <% @articles.each do |article| %>
    <article>
      <h2><%= article.title %></h2>
      <p><%= article.content %></p>
    </article>
  <% end %>

  <% unless @page.last? %>
    <%= link_to "Next page",
                root_path(page: @page.next_param),
                data: { pagination_target: "nextPageLink" } %>
  <% end %>
</div>

Refresh your page and you should now see the next page link logged into your console.

Now that everything is wired correctly, we are ready to add our feature. The first thing we are going to do, is to console.log("intersection") when the viewport intersects the next page link.

How do you do this?

With a Javascript object called IntersecionObserver! The Intersection Observer API provides a way to asynchronously observe changes in the intersection of a target element with an ancestor element or with a top-level document's viewport.

Let's add this in our Stimulus controller:

// app/javascript/controllers/pagination_controller.js

import { Controller } from "stimulus"

export default class extends Controller {
  static targets = ["nextPageLink"]

  initialize() {
    this.observeNextPageLink()
  }

  // private

  async observeNextPageLink() {
    if (!this.hasNextPageLinkTarget) return

    await nextIntersection(this.nextPageLinkTarget)
    console.log("intersection")
  }
}

const nextIntersection = (targetElement) => {
  return new Promise(resolve => {
    new IntersectionObserver(([element]) => {
      if (!element.isIntersecting) {
        return
      } else {
        resolve()
      }
    }).observe(targetElement)
  })
}

Wow! That's the most complicated part of the feature! Let's break it down.

First, when the Stimulus controller is initialized, we start observing the next page link.

initialize() {
  this.observeNextPageLink()
}

If there is no next page link on the page, then the controller does nothing. However, if there is a next page link, we'll wait for the intersection and then console.log("intersection"). Note that this process is asynchronous: we don't know when the next intersection is going to happen!

How do we do asynchronous Javascript? With async / await and promises!

The function observeNextPageLink is asynchronous for this reason. See how it reads like plain English now? Wait for the next intersection with the next page link and then console.log("intersection").

async observeNextPageLink() {
  if (!this.hasNextPageLinkTarget) return

  await nextIntersection(this.nextPageLinkTarget)
  console.log("intersection")
}

Last but not least, the nextIntersection function has to return a Promise that will resolve when the next page link intersects the viewport. This can be done easily by creating a new IntersectionObserver that will observe the next page link.

const nextIntersection = (targetElement) => {
  return new Promise(resolve => {
    new IntersectionObserver(([element]) => {
      if (!element.isIntersecting) {
        return
      } else {
        resolve()
      }
    }).observe(targetElement)
  })
}

Now that our mechanic is in place, we need to replace our console.log("intersection") with something useful. Instead of logging "intersection" in the console, we will fetch the articles from the next page and append them to the list of articles we already have!

To do AJAX requests with Rails, we will use the brand new rails/request.js library that was created in June 2021. This library is a wrapper around fetch that you'll normally use to do AJAX requests in Javascript. It integrates nicely with Rails, for example, it automatically sets the X-CSRF-Token header that is required by Rails applications, this is why we'll use it!

Let's add it to our package.json using yarn:

yarn add @rails/request.js

Now let's import the get function in our Pagination Controller and replace the console.log("intersection") with the actual logic. The code now looks like this:

import { Controller } from "stimulus"
import { get } from "@rails/request.js"

export default class extends Controller {
  static targets = ["nextPageLink"]

  initialize() {
    this.observeNextPageLink()
  }

  async observeNextPageLink() {
    if (!this.hasNextPageLinkTarget) return

    await nextIntersection(this.nextPageLinkTarget)
    this.getNextPage()
  }

  async getNextPage() {
    const response = await get(this.nextPageLinkTarget.href) // AJAX request
    const html = await response.text
    const doc = new DOMParser().parseFromString(html, "text/html")
    const nextPageHTML = doc.querySelector(`[data-controller~=${this.identifier}]`).innerHTML
    this.nextPageLinkTarget.outerHTML = nextPageHTML
  }
}

const nextIntersection = (targetElement) => {
  return new Promise(resolve => {
    new IntersectionObserver(([element]) => {
      if (!element.isIntersecting) {
        return
      } else {
        resolve()
      }
    }).observe(targetElement)
  })
}

The only changes here are the import { get } from "@rails/request.js" that we use to make a get AJAX request to our server and the console.log("intersection") that was replaced by this.getNextPage(). Let's understand this last method.

async getNextPage() {
  const response = await get(this.nextPageLinkTarget.href) // AJAX request
  const htmlString = await response.text
  const doc = new DOMParser().parseFromString(htmlString, "text/html")
  const nextPageHTML = doc.querySelector(`[data-controller=${this.identifier}]`).outerHTML
  this.nextPageLinkTarget.outerHTML = nextPageHTML
}

First, we issue a get request to the server, wait for the response and store it in the response variable. Then we extract the text from the response and store it in the htmlString variable. As we want to use querySelector on this htmlString, we first need to parse it to make it an HTML document with DOMParser. We then store this document in the doc variable. We then extract the next page articles and the next page link from this document and append them to our articles list by replacing the current next page link.

Our infinite scroll is now working, but only for one iteration! We need to make it recursive. Every time new articles are added to the page, a new next page link is also added! We need to observe this new next page link to be able to have a read infinite scroll!

Let's add this recursion!

Here is the final controller:

import { Controller } from "stimulus"
import { get } from "@rails/request.js"

export default class extends Controller {
  static targets = ["nextPageLink"]

  initialize() {
    this.observeNextPageLink()
  }

  async observeNextPageLink() {
    if (!this.hasNextPageLinkTarget) return

    await nextIntersection(this.nextPageLinkTarget)
    this.getNextPage()

    await delay(500) // Wait for 500 ms
    this.observeNextPageLink() // repeat the whole process!
  }

  async getNextPage() {
    const response = await get(this.nextPageLinkTarget.href)
    const html = await response.text
    const doc = new DOMParser().parseFromString(html, "text/html")
    const nextPageHTML = doc.querySelector(`[data-controller~=${this.identifier}]`).innerHTML
    this.nextPageLinkTarget.outerHTML = nextPageHTML
  }
}

const delay = (ms) => {
  return new Promise(resolve => setTimeout(resolve, ms))
}

const nextIntersection = (targetElement) => {
  // Same as before
}

Here, we only changed the two last lines of the observeNextPageLink function by waiting 500ms to avoid scrolling too fast, and then, we observe the new next page link if there is one, thus repeating the whole process we just went through!

The last think you can do is hide the next page link on the page to make it a real infinite scroll.

<% unless @page.last? %>
  <%= link_to "Next page",
              root_path(page: @page.next_param),
              data: { pagination_target: "nextPageLink" },
              style: "visibility: hidden;" %>
<% end %>

You did it, you built a real infinite scroll with Rails and Stimulus!

Takeaways and useful resources

rails/request.js is a library that provides a wrapper around fetch. It is very useful when working with Rails applications because it sets a few headers under the hood for you that are required by your Rails application.
basecamp/gearder_pagination is a very small pagination gem (less than 50 commits). You should read the code if you want to learn a few tricks in Ruby / Rails!
When working with asynchronous actions in Javascript, you should work with promises and async / await. The Intersection Observer API can help you trigger actions based on the viewport intersecting other elements on the page.

Credits

This article is heavily inspired by hey.com's infinite scroll. Thanks to the Basecamp team for leaving the source maps open. It was really helpful when I had to build a similar feature!

Did you like this article?

You can follow me on Twitter to get notified when I publish new articles. I sometimes do when I work on interesting features like this infinite scroll!

Lessons from the Gilded Rose refactoring Kata

Alexandre Ruban — Wed, 07 Apr 2021 09:59:56 +0000

The Gilded Rose refactoring Kata is a famous exercise used to teach some principles of Object Oriented design. In addition to finding this Kata really fun, I think it illustrates perfectly 3 very important aspects of real world software development: the need for a robust test suite, when to refactor your code and how to refactor your code. Are you ready? Let's dive in!

The requirements of the Gilded Rose Kata

The owner of the Gilded Rose inn, Allison, sells some of the finest goods (aged bries, backstage passes, sulfuras and normal goods). Those goods have 3 attributes:

The name of the good
A quality integer which denotes how valuable the good is
A sell in integer which represents the number of days before the sell by date

Unfortunately, the goods are constantly degrading in quality as they approach their sell by date and of course, the rules of the quality changes per day are different for each type of good.

To keep track of her inventory, Allison uses a legacy software that is in charge of keeping track of the quality and number of days before the sell by date. She was really happy with it until now, because she needs a new feature. She hires you as a developer to add a new type of "conjured" goods to her inventory management tool.

If you want to read the full description of the Kata, you will find the complete set of requirements here.

You need a robust test suite

Well there are 2 things you should know about Allison's inventory management tool:

The application is almost only composed of a single 46 lines method full of conditionals
There are no tests

Now I want you to have a look at this method and imagine having to add a new set of rules for a new good here. How does it make you feel? The answer is probably terrified of breaking everything without even knowing it and you are right! The first part if you want to solve this Kata is to write good tests.

In real applications, the complexity naturally grows just like in the Gilded Rose Kata. Without a robust test suite, you will inevitably break things, get a lot of errors in production and frustrate your users.

You should not refactor your code when it doesn't have to change

Before she needed this new feature, Allison was really happy with her inventory management tool. Refactoring was not needed, in fact, there was no need to change anything before the new requirement. At this point, you should not refactor your code because you only risk making things worse by breaking a tool Allison is happy working with. If you as the developer are not working on this part of the application, all you need to do is safely ignore this ugly code even if you could "improve" it.

The new requirement however changes everything. Should you start by a refactoring or should you add the new feature while keeping the old "architecture"? Here, you really have two ways to go. You could, as Kent Beck said "make the change easy then make the easy change" and refactor the code first or you could just add the new feature in a quick and dirty way.

There are no absolute rules here.

What is the cost of refactoring? Maybe it's not worth your time if the code almost never changes. Maybe the code isn't that clean but still manageable. What is the cost of not refactoring? Will I lose even more time trying to add my new feature in poorly designed code than refactoring and then adding the new feature? What is the long term impact of not refactoring? Am I likely to pay a small cost frequently that will compound and become much bigger than to refactor now?

In our Gilded Rose Kata however the answer is obvious. You will really struggle to add the new feature in this untangled mess of conditionals. It will be even longer than to add a reliable test suite, make the change easy by applying refactoring techniques to the legacy code and only then make the easy change.

How to refactor?

The main ideas in Object Oriented design are always the same. You want to have small objects with a single responsibility that knows as little as possible about one another. The refactoring technique you should use here is called replace conditional with polymorphism. The main idea here is that instead of having conditionals everywhere, you will have one factory method centralizing the conditions and in charge of generating an instance of the right type of good, where each type of good has its own class implementing the same interface.

If you want to learn more about refactoring techniques, here is the link to the amazing talk of Sandi Metz during RailsConf 2014 that inspired this article. If you like this kind of refactoring Katas, you should definitely check her great book 99 bottles of OOP, it is almost the same exercise and it's really fun to read!

Thanks for reading! If you liked this article, you can subscribe to my newsletter, I try to write an article once a month!

Achieving simple design with simple CSS

Alexandre Ruban — Mon, 23 Nov 2020 21:29:54 +0000

A few weeks ago, I came across this article from the Basecamp team explaining how they achieve "simple design" in both their products Basecamp and Hey. They mention what they call "Fisher Price" design (always choosing clarity over being slick or fancy). I am a big fan and user of both Basecamp and Hey. I love how simple and straight to the point both products are and I kept wondering what the impacts on the CSS and HTML code are. Let's have a look!

To prepare this article, I rebuilt the "How it works" page of Hey's marketing website. Here is what I learned.

You need fewer variables

If you use open source CSS libraries like Bootstrap in some of your web projects, then you know what a huge scss variables file looks like. If you have a look at the variables file of Bootstrap you will notice that this file alone is about 1300 lines long! This is a huge amount of work compared to the 50 variables extracted from the Hey source code. If you are working with a small team and want to build a custom design, rebuilding a Bootstrap like design system will probably take you ages.

Let's have a closer look at the Hey variables:

:root {
  /* Colors */
  --color-white: #fff;
  --color-black: #222;
  --color-grey: #777471;
  --color-stone: #edeae6;
  --color-yellow: #f5d652;
  --color-canary: #fff5ca;
  --color-canary-tint: #fffae5;
  --color-cobalt: #0074e4;
  --color-sky: #b6dbff;
  --color-sky-tint: #daedfe;
  --color-blurple: #5522fa;
  --color-lavender: #d5d2ff;
  --color-lavender-tint: #eae8fe;
  --color-purple: #7700a2;
  --color-pink: #cb84de;
  --color-pink-tint: #efdaf5;
  --color-salmon: #ec8580;
  --color-peach: #fee5da;
  --color-peach-tint: #fef2ed;
  --color-teal: #5fddc5;
  --color-mint: #b3f4e0;
  --color-mint-tint: #d8f9f0;

  /* Concrete colors */
  --color-shadow: rgba(0, 0, 0, 0.1);
  --color-shadow-dark: rgba(0, 0, 0, 0.2);
  --color-text: var(--color-black);
  --color-background: var(--color-stone);
  --color-sheet: var(--color-white);
  --color-neutral: var(--color-grey);
  --color-link: var(--color-blurple);
  --color-accent: var(--color-teal);

  /* Spaces modular scale */
  --space-x-small: 0.25em;
  --space-small: 0.5em;
  --space-medium: 1em;
  --space-large: 2em;
  --space-x-large: 3em;
  --space-xx-large: 4em;
  --space-xxx-large: 6em;
  --space-navbar: 4em;

  /* Font families */
  --font-sans: 'Source Sans Variable', 'Helvetica Neue', helvetica, 'Apple Color Emoji', arial, sans-serif;
  --font-mono: monospace;

  /* Font size modular scale */
  --type-base: calc(1.6em + 0.5vw);
  --type-xxx-small: 55%;
  --type-xx-small: 65%;
  --type-x-small: 75%;
  --type-small: 85%;
  --type-medium: 100%;
  --type-large: 125%;
  --type-x-large: 150%;
  --type-xx-large: 200%;
  --type-xxx-large: 300%;
}

html {
  font-size: 10px;
}

body {
  font-size: var(--type-base);
}

Out of 50 variables, 30 correspond to the colors of the palette, 2 correspond to the fonts, 8 correspond to spaces used for both margin and paddings and 10 correspond to the different font sizes the designer can choose. That's a much smaller variable file! And it is more than enough to create a "simple design".

There are two more interesting things in this variable file:

First, they use a responsive font size. The document font size is set to 10px in the html tag (so 1 rem is always 10px) and then overriden to var(--type-base) in the body tag. Having a closer look at the --type-base variable, we can notice that it is set to calc(1.6em + 0.5vw) which means 1.6 * 10px + 0.5% of the viewport width. This means that the font size will scale with the viewport width and so the em also scales with it. In other words, the font size on smaller screen will be smaller than on bigger screens. The font size is changed with media queries for the two breakpoints 45em and 91em globally by overriding the --type-base variable.

@media (min-width: 45em) {
  :root {
    --type-base: calc(0.9em + 0.9vw);
  }
}

@media (min-width: 91em) {
  :root {
    --type-base: 2.2em; /* font size stops scaling after 91em */
  }
}

Second, the unit of the spaces variables is em and not rem. This means that the spacings also scale with the viewport width. This works the same as for the font size, the spaces will be smaller on smaller screens than on bigger screens. Rather than hardcoding pixels, your design will keep the same proportions on different devices. We will see another use of this feature shortly so keep in mind that spaces for margins and paddings are in em, this is a great feature of CSS! If you are still using pixels for your spaces units, you should consider switching to ems!

You need a simpler layout

Now that we have our set of variables in place let's talk about the layout. Hey uses CSS grid to create a really simple layout. If you're not familiar with CSS grid, now is the time to learn its powers! (Note that the indentation of the grid-template-columns property is only there for readability purposes on this blog but is not required).

.grid {
  display: grid;
  grid-template-columns: [max] 1fr
    [l] 1fr
    [m] repeat(3, [m] 28vw)
    [m] 1fr
    [l] 1fr
    [max];
}

These 2 lines of code above divides the screen into 7 columns. The 8 lines that divides those 7 columns are named in order max, l, m, m, m, m, l and max thanks to the [] notation (otherwise they would simply be numbered 1 to 8). Out of those 7 columns, 4 of them have a width of 1fr and the 3 center columns have a width of 28vw. The fr unit stands for fraction and it really means a fraction of the available space. The vw unit means 1% of the viewport width. If we go further here, the 3 columns in the center will each take 28vw for a total of 84vw. There are 100vw available (100% of the viewport width) so 16vw to split in 4 fractions means that each fraction is 4% of the viewport width! If this feels a bit complicated, it is illustrated in the picture bellow:

The sizes of those 7 columns are overriden for the two breakpoints 45em and 91em as shown bellow.

@media(min-width: 45em) {
  .grid {
    grid-template-columns: [max] 1fr
      [l] minmax(11ch, 0.7fr)
      [m] repeat(3, [m] 21.66ch)
      [m] minmax(11ch, 0.7fr)
      [l] 1fr
      [max];
  }
}

@media (min-width: 91em) {
  .grid {
    grid-template-columns: [max] 1fr
      [l] 15ch
      [m] repeat(3, [m] 21.66ch)
      [m] 15ch
      [l] 1fr
      [max];
  }
}

The most important thing to learn here is this minmax function. Here minmax(11ch, 0.7fr) simply means that the column width can shrink until it reaches a width of 11ch otherwise it will have a width of 0.7fr. Easy right? This minmax notation is widely used with CSS grid!

We can also learn about 1 more spacing unit called ch which corresponds to the width of the zero character (0) in the current font size. It is usually used for paragraph widths as paragraphs are considered very readable at about 70ch width.

Now that we have our 7 columns layout, it's time to define CSS classes to fill those columns.

.grid__max {
  grid-column: max / max 2;
}

.grid__wide {
  grid-column: l / l 2;
}

.grid__medium {
  grid-column: m / m 4;
}

.grid > :not([class*="grid"]) {
  grid-column: m / m 4;
}

In a grid layout, the element that defines the columns with the property grid-template-columns is called the grid container. Its direct descendants are called the grid items and their place on the grid is determined by the property grid-column.

The first class .grid__max means that the element it is applied to will fill the space from the first grid column named max to the second grid column named max. If you have a look at the picture of the grid above this basically means the whole width of the grid container.

The same thing applies for the .grid__wide class as the element it is applied to will fill the space from the first grid column named l to the second grid column named l. In the picture above, you can see that the hero picture received this .grid__wide class.

Last but not least, the elements with .grid__medium class will fill the space from the first grid column named m to the fourth grid column named m. That's the 3 center columns of the grid and if you have a look at the picture again, this is where the text lives.

Does it mean that we need to specify .grid__max, .grid__wide or .grid__medium on every single direct descendant of the grid container? No! Thanks to the last selector .grid > :not([class*="grid"]) if a direct descendent of the grid container (a grid item) has no class that contains the string grid it will act like a .grid__medium by default! Neat!

If you visit hey.com you will realise that with this set of variables, and this layout in place, almost all of the heavy lifting is already done. This is a very good example of "simple design".

Note that the grid is not completely supported on Internet Explorer. The Hey team wants to use grid on their site, so they will "force" users to upgrade to a more recent browser using the media query @supports (display: grid). Let's have a look at how they do it:

<div class="unsupported">
  <p>
    <strong>
      Sorry, this website uses features that your browser doesn’t support.
    </strong>
    Upgrade to a newer version of
    <a href="https://www.mozilla.org/en-US/firefox/new/">Firefox</a>,
    <a href="https://www.google.com/chrome/">Chrome</a>,
    <a href="https://support.apple.com/downloads/safari">Safari</a>,
    or
    <a href="https://www.microsoft.com/en-us/edge">Edge</a>
    and you’ll be all set.
  </p>
</div>

First, they add HTML markup to suggest that the user upgrades his browser to a newer version.

.unsupported {
  position: fixed;
  width: 100%;
  height: 100%;
  top: 0;
  padding: 4em 2em;
  z-index: 10000;
  font-size: 24px;
  font-weight: bold;
  text-align: center;
  color: #000;
  background-color: #fff
}

.unsupported p {
  max-width: 800px;
  margin: 0 auto
}

/* Don't show the '.unsupported' element if the browser supports grid */
@supports (display: grid) {
  .unsupported {
    display:none;
    visibility: hidden;
  }
}

Then they add css to make this suggestion visible only to users that does not support grid thanks the media query @supports (display: grid).

Use BEM or another convention

CSS is often a misunderstood language. There is a lot to learn and it can become a real mess very quickly it you don't have clear rules about what should go where. The Basecamp team uses the BEM methodology to organise CSS code. Let's have a look at how BEM methodology helps you organise your code by redesigning those boxes.

First let's have a look at the corresponding HTML (notice the .grid__wide from previous paragraph!):

<section class="hiw-box grid__wide">
  <div class="hiw-box__copy txt-center-mobile">
    <h3 class="push-small--top">
      The Imbox is for your important email
    </h3>
    <p>
      When you say “Yes” to someone in The Screener, their email lands in
      the Imbox by default. It’s the place for emails you actually want to
      read, from people and services you absolutely want to hear from.
    </p>
  </div>
  <figure class="hiw-box__image">
    <img src="imbox.jpg" alt="The Imbox">
  </figure>
</section>

<section class="hiw-box hiw-box--blurple hiw-box--reverse grid__wide">
  <div class="hiw-box__copy txt-center-mobile">
    <h3 class="push-small--top">
      The Feed is for your casual, whenever reads
    </h3>
    <p>
      The Feed turns your newsletters, promotional emails, and long-reads into
      a browsable, casual newsfeed. Just scroll, everything’s open already. See
      something you like? Click it and read the whole thing right in place.
    </p>
  </div>
  <figure class="hiw-box__image">
    <img src="feed.jpg" alt="The Feed">
  </figure>
</section>

Did you notice the structure? hiw-box is the name of the block. It represents the whole card. Then hiw-box__copy and hiw-box__image are elements of this block. They are prefixed with the name of the block to prevent naming conflicts in CSS. The block name and the element name are separated with a double underscore. Finally hiw-box--blurple and hiw-box--reverse are called modifiers. They are also prefixed by the name of the block. The block name and the modifier name are separated with a double "-". Et voilà, you know almost all there is to know about BEM methodology.

Let's have a look at the corresponding CSS:

/* Block */
.hiw-box {
  position: relative;
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(17em, 1fr));
  grid-gap: 1em;
  align-items: center;
  direction: rtl;
  margin: 1em 0;
  padding: 1em;
  color: var(--color-cobalt);
  background-color: var(--color-canary);
  border-radius: 0.75em;
}

@media (min-width: 45em) {
  .hiw-box {
    left:-1em;
    transform: rotate(-1deg);
    background: var(--color-canary) url(teal.svg) left -7em center /
      auto 125% no-repeat;
  }
}

/* Elements of the block */
.hiw-box__copy {
  direction: ltr;
  margin: 0 1em;
}

.hiw-box__image {
  margin: 0;
  background-color: var(--color-white);
  box-shadow: 2rem 2rem 6rem var(--color-shadow);
  border-radius: 1rem;
}

/* Modifiers */
@media (min-width: 45em) {
  .hiw-box--reverse {
    left:1em;
    direction: ltr;
    transform: rotate(1deg);
  }
}

.hiw-box--blurple {
  color: var(--color-peach);
  background-color: var(--color-blurple);
}

@media (min-width: 45em) {
  .hiw-box--blurple {
    transform:rotate(1deg);
    background: var(--color-blurple) url(pink-purple.svg) right -6em center /
      auto 126% no-repeat;
  }
}

Do you see how easy it is to read? BEM makes the HTML markup very readable and, as it is a popular methodology, a new developper joining your team will understand immediately how to organise CSS in the project.

Use the full power of CSS to write less code

Remember when I said spacing should be in ems? Now is the time to explain why a bit more in depth. If you have a closer look at hey.com, you will realize that buttons have many different sizes. However in the source code, you'll find only one .button class

.button {
  transition: color 0.2s ease, background-color 0.2s ease, box-shadow 0.2s ease;
  display: inline-block;
  padding: 0.4em 1em;
  color: var(--color-sheet);
  font-family: var(--font-sans);
  text-decoration: none;
  text-align: center;
  line-height: normal;
  -webkit-appearance: none;
  background-color: var(--color-link) !important;
  background: linear-gradient(
    90deg, var(--color-link) 0%, var(--color-cobalt) 100%
  );
  border-radius: 1.5em;
  border: 0;
  box-shadow: none;
}

The interesting thing to notice here is that padding units are in em which means relative to the element's font size. If you have utilities for font size in you css classes, scaling the size of the button becomes really easy.

<a href="#" class="button txt-small">Small button</a>
<a href="#" class="button">Medium button</a>
<a href="#" class="button txt-large">Large button</a>

This of course is a small trick but combined with all the others, it could save a lot of time for you or your team!

Build amazing animations without Javascript

Hey's navigation bar is amazing and implemented in pure CSS. In this section, we are going to rebuild it and hopefully learn a few more tricks!

Let's start with the HTML markup:

<header class="header">
  <nav class="header__nav" aria-label="Mail navigation">
    <a href="#" class="header__logo" aria-label="HEY homepage">
      Hey log
    </a>
    <input
      type="checkbox"
      role="button"
      id="hamburger"
      class="header__checkbox hide-screens"
    >
    <label class="header__toggle" for="hamburger">
      <span class="header__toggle-icon" aria-hidden="true"></span>
      Menu
    </label>

    <div class="header__links" role="menu">
      <a class="header__link" href="#" role="menuitem">How it works</a>
      <a class="header__link" href="#" role="menuitem">Tour features</a>
      <a class="header__link" href="#" role="menuitem">Pricing</a>
      <a class="header__link" href="#" role="menuitem">FAQs</a>
      <a class="header__link" href="#" role="menuitem">Sign in</a>
      <a class="header__link button" href="#" role="menuitem">Try it FREE</a>
    </div>
  </nav>
</header>

The markup again is very simple here and very readable thanks to BEM methodology. The thing to notice here is that the "Menu" toggle is nested inside a label that corresponds to the hidden checkbox just above. When you click on "Menu", you are actually clicking on the label that checks and unchecks the checkbox. With this technique, we will be able to add styles to the siblings of the checkbox using the general sibling selector ~ in CSS.

Let's have a look at how it works in detail. First, let's setup the general styles for the navigation bar.

.header {
  position: fixed;
  width: 100%;
  z-index: 1000;
  background-color: var(--color-sheet);
}

The .header block is fixed at the top of the page.

.header__nav {
  display: flex;
  align-items: center;
  justify-content: space-between;
  width: 100%;
  position: relative;
  z-index: 20000;
  margin: 0;
  padding: 0.75rem;
}

@media (min-width: 45em) {
  .header__nav {
    padding: 1rem;
  }
}

.header__logo {
  margin: 0;
  text-align: left;
}

Next, we created the inner container in the navigation bar. It's a flex container. On larger screens, the justify-content: space-between; makes sure the logo and the navigation links are each on one side of the screen. Let's have a look at the interesting part: the .header__links element.

.header__links {
  display: block;
  margin: 0;
  padding: 0;
  font-size: var(--type-medium);
}

@media (max-width: 44.99em) {
  /* They are also stacked vertically */
  /* Links are absolutely positioned outside of the screen */
  .header__links {
    position:absolute;
    top: 8rem;
    right: -25rem;
    display: flex;
    flex-direction: column;
    align-items: flex-end;
    margin: 0;
    padding: 0;
    font-size: var(--type-large);
    -webkit-overflow-scrolling: touch;
  }

  /* Creates the white backdrop when the navigation bar is opened */
  .header__links::after {
    transition: opacity 0.15s ease-in-out;
    content: '';
    position: fixed;
    z-index: -1;
    top: 0;
    right: 0;
    bottom: 0;
    left: 0;
    opacity: 0;
    pointer-events: none;
    background-color: rgba(255, 255, 255, 0.8);
  }
}

On a large screen, the wrapper around the navigation links is just a simple block.

On smaller screens, on the other hand, the header links are stacked vertically thanks to display: flex; and flex-direction: column; and aligned to the right thanks to align-items: flex-end;. They are also in position: absolute; relatively to the closest parent with position: relative; which in this case is the .header__nav element. This allows to position those links at 8rem from the top and -25rem from the right (that's outside the screen!). We'll see soon how checking the checkbox can animate those links so that they move inside the screen.

The .header__links::after pseudo element is the white transparent backdrop. The position: fixed;, top: 0;, right: 0;, left: 0; and bottom: 0; properties makes sure this pseudo element takes the full screen and z-index: -1; that it appears behind the navigation links.

Now let's have a look at how the animation works by having a look at the .header__link itself:

/* On large screens: classic inline-block link */
.header__link {
  transition: color 0.2s ease,
    text-decoration-color 0.2s ease,
    box-shadow 0.2s ease;
  transform: none;
  margin: 0 0 0 0.6em;
  display: inline-block;
  line-height: 1.5;
  font-weight: 700;
}

@media (max-width: 44.99em) {
  /* On small screens: classic inline block link with more style */
  .header__link {
    transition:transform 0.15s ease-in;
    transform: translate(0, 0);
    display: inline-block;
    padding: 0.2em 1em;
    margin: 0 0 0.25em 0;
    line-height: 2;
    text-decoration: none;
    color: var(--color-white);
    background-color: var(--color-teal);
    background: linear-gradient(
      90deg, var(--color-purple) 0%, var(--color-salmon) 100%
    );
    border-radius: 3em;
  }

  .header__link:visited,
  .header__link:hover {
    color: var(--color-white);
    box-shadow: none;
  }

  /* The animation is delayed 0.05 sec for the second header__link */
  .header__link:nth-child(2) {
    transition-delay: 0.05s;
  }

/* The animation is delayed 0.1 sec for the second header__link */
  .header__link:nth-child(3) {
    transition-delay: 0.1s;
  }

/* And it goes on like this + 0.05 sec for the next ones */
  .header__link:nth-child(4) {
    transition-delay: 0.15s;
  }

  .header__link:nth-child(5) {
    transition-delay: 0.2s;
  }

  .header__link:nth-child(6) {
    transition-delay: 0.25s;
  }

  .header__link:nth-child(7) {
    transition-delay: 0.3s;
  }

  .header__link:nth-child(8) {
    transition-delay: 0.35s;
  }
}

On large screens, a .header__link is a simple inline block element.

On smaller screens, it has a bit more decoration on it with a linear gradient as a background, but the really interesting part here is the transition delay. For each .header__link, the transition on the position will start 0.05s after the previous .header__link thanks to the :nth-child(n) selector!

And now let's have a look at how to trigger this animation:

@media (max-width: 44.99em) {
  /* When the checkbox is :checked, show the white backdrop */
  .header__checkbox:checked ~ .header__links::after {
    opacity:1;
    pointer-events: auto;
  }

  /* When the checkbox is :checked, translate the links from -27rem! */
  .header__checkbox:checked ~ .header__links .header__link {
    transition-duration: 0.25s;
    transition-timing-function: cubic-bezier(0.34, 1.56, 0.64, 1);
    transform: translate(-27rem, 0);
  }
}

Thanks to the :checked pseudo-class and to the general sibling combinator ~ we can instruct our links to translate when clicking on the label. You have a beautiful animation without a single line of Javascript. I will write about how to make an animated hamburger menu in another article.

Takeways

I had a lot of fun digging into hey.com marketing website. Here are the main takeways from this blog post summarized:

Simple design requires very few lines of CSS. The whole hey.com marketing website requires a bit more than 2000 lines of CSS (reboot and variables included) which is very small. It also has a very positive impact on the performance of the website.
Your set of variables does not have to be more than 100 lines to build your design system.
You do not need complex layouts to sell your product. A simple design and good copywriting will be more effective than "the three column layout".
Using a simple methodology like BEM makes it really easy to organise CSS and makes your HTML markup readable.
You can build amazing animations with CSS alone. You might not need Javascript for everything.
The Basecamp's team approach is a great inspiration for small teams and show how to leverage the full power of CSS's features to write very little code.