DEV Community: Abeid Ahmed

New way of bundling JS/CSS in Rails

Abeid Ahmed — Sun, 12 Sep 2021 09:53:16 +0000

Apologies for misleading you with a vague title, but I wouldn't call this approach the new way, because under the hood webpacker and sass-rails were doing all of the bundlings without us needing to tinker with the configuration. For simpler applications, this was rock solid, but for complex applications, webpacker kind of stood in the way. But all is good now since the advent of two gems jsbundling-rails and cssbundling-rails.

So let's see what these gems have to offer. We'll start with a bare-bone version of rails without any JavaScript.

rails new myapp --skip-javascript

After initializing the rails app, go to the Gemfile and add these two gems that we'll be using.

gem 'jsbundling-rails'
gem 'cssbundling-rails'

Run bundle install after that.

In this demo, we'll be using webpack and tailwindcss as the example.

./bin/rails javascript:install:webpack
./bin/rails css:install:tailwind

These generators should create a Procfile.dev, webpack.config.js, and more. Go to the app/javascript/application.js and write some JavaScript code. Now run ./bin/dev and with any luck, your JavaScript and CSS should be bundled and compiled into app/assets/builds directory into two files, namely: application.css and application.js. This is so much better because now we can use

<%= stylesheet_link_tag "application", "data-turbo-track": "reload", media: "all" %>
<%= javascript_include_tag "application", "data-turbo-track": "reload", defer: true %>

into our layouts/application.html.erb file.

Having webpack.config.js in our root directory is even better. It's all plain vanilla webpack without any fancy wrappers around it and hence we can customize it to our hearts.

However, the above-mentioned approach to using tailwind in our app is limited. For example, we cannot use @layer or any other fancy tailwind syntax because it depends on postcss and other jazz. Again, for simpler applications it's fine, but a complex one may need those syntaxes and may need to write scss instead of css alone.

Although we can revert the changes that we made above easily, for ease of understanding let's spin up a new rails app instead.

rails new myapp2 --skip-javascript

This time we'll only be installing the jsbundling-rails gem.

./bin/rails javascript:install:webpack

As usual, the generator will create the Procfile.dev, webpack.config.js, and more.

So in this approach to installing TailwindCSS, we'll be installing postcss and its plugins to handle all situations.

yarn add tailwindcss autoprefixer css-loader mini-css-extract-plugin postcss postcss-import postcss-loader

That was quite a lot. But you can add or remove these libraries depending on your application's need.

Our approach will be the same. We'll output two files, namely: application.css and application.js in the app/assets/builds directory so that we can use the stylesheet_link_tag and javascript_include_tag in our layout/application.html.erb file.

Go to the app/assets/stylesheets/application.css and rename this file to application.scss, and also paste the following lines of code.

@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import 'tailwindcss/utilities';

Let's configure our webpack.config.js

const path = require('path')
const webpack = require('webpack')
const MiniCssExtractPlugin = require('mini-css-extract-plugin')

module.exports = {
  mode: 'production',
  entry: {
    application: [
      './app/javascript/application.js',
      './app/assets/stylesheets/application.scss',
    ],
  },
  output: {
    filename: '[name].js',
    path: path.resolve(__dirname, 'app/assets/builds'),
  },
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [MiniCssExtractPlugin.loader, 'css-loader', 'postcss-loader'],
      },
    ],
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: '[name].css',
    }),
    new webpack.optimize.LimitChunkCountPlugin({
      maxChunks: 1,
    }),
  ],
}

As you can see, we have defined two entry points inside the application array. If you have separate assets for your admin page or a marketing page, you can define another array of entry points and webpack will spit out the compiled assets into separate files.

Also, take note of the plugins array. The MiniCssExtractPlugin is responsible for compiling the stylesheet and then spitting it out into the defined directory.

Now the final piece of the puzzle is to configure postcss and manifest.js. Create a file called postcss.config.js in the root of the project directory and write down the following lines.

module.exports = {
  plugins: [
    require('postcss-import'),
    require('tailwindcss'),
    require('autoprefixer'),
  ],
}

// app/assets/config/manifest.js

//= link_tree ../images
//= link_tree ../builds

Now run ./bin/dev and check the app/assets/builds directory for your compiled assets. It wasn't that hard, was it.

I'm excited about where rails is heading to. We started with hotwire and now we have new asset bundling options. I wonder what's next. Now is the time to hop into the rails ecosystem if you haven't already.

Cover picture: https://unsplash.com/photos/cvBBO4PzWPg

Normalizing ActiveRecord attributes with a custom DSL

Abeid Ahmed — Thu, 26 Aug 2021 09:48:53 +0000

Lately, I've been reading through some Rails code that I've written for my side-projects. After reading through 4-5 projects, I noticed a common pattern that could be extracted and reused throughout the application. The pattern goes something likes this,

class User < ApplicationRecord
  before_validation :normalize_fields

  private

  def normalize_fields
    self.email = email.to_s.downcase.strip
    self.name = name.to_s.strip
    # more normalization
  end
end

I'm sure you've seen something like this or most probably you've written some field normalizers yourself.

In my case, I wasn't just normalizing the field in the User model, but through Account, Membership, Contact models, and so on. I decided to do myself a favor and took out some time off of my schedule and made up my mind to solve this issue once and for all.

My first instinct was to use a custom Ruby DSL.

DSLs are small languages, focused on a particular aspect of a software system - Martin Fowler.

I tried to look for some inspiration and stumbled across the has_secure_token method. It taps into the before_create callback and performs some action, which is analogous to what I was doing. The only difference was to use the before_validation callback in our case and perform some normalizations.

The `normalize` method

The next thing to figure out was to design the API. This was pretty simple as I knew exactly what I wanted to achieve. I also looked at the normalize gem and I came up with the following syntax,

class User < ApplicationRecord
  normalize :email, with: %i[strip downcase]
  normalize :name, with: :strip
end

Now, the only thing left is to write some code.

# app/models/concerns/normalize.rb

module Normalize
  extend ActiveSupport::Concern

  class_methods do
    def normalize(*args)
      options = args.extract_options!

      before_validation do
        args.each { |field| send("#{field}=", normalized_value(field, options[:with])) }
      end
    end
  end

  private

  def normalized_value(field, normalizers)
    if normalizers.is_a?(Array)
      normalizers.inject(send(field).to_s, :try)
    else
      send(field).to_s.send(normalizers)
    end
  end
end

Firstly, we need to define a class method called normalize. We extract the options from the normalize method and then we're left only with the fields that we want to normalize on. For example,

normalize :email, :name, with: %i[strip downcase]

If we extract the options, we're left with an array of [:email, :name], on which we can loop through and then apply the normalizers.

Secondly, the with option can be an array of symbols or just a symbol. For example,

normalize :email, :name, with: %i[strip downcase]
normalize :first_name, with: :strip

On the normalized_value method, we check for this case and apply the normalizers conditionally.

I then included this concern in the ApplicationRecord and started changing all of the previous occurrences with the newer syntax. I was pretty happy with what I achieved until I came across a code where I was doing something like,

class Account < ApplicationRecord
  before_validation :normalize_cname

  private

  def normalize_cname
    self.cname = cname.to_s.downcase.gsub(/\Ahttps?:\/\//, "")
  end
end

Now, this isn't possible with the normalize method with what we have right now.

Designing for resilience

I thought to myself that it would be perfect if we could pass a block to the normalize method and call the block in the normalized_value method. Something like this would work perfectly.

class Account < ApplicationRecord
  normalize :cname, with: %i[downcase] do |cname|
    cname.gsub(/\Ahttps?:\/\//, "")
  end
end

In my opinion, passing in a block would be useful in many cases. Not only can we use methods like gsub, we can also use our methods for more power.

class Account < ApplicationRecord
  normalize :cname do |cname|
    some_method(cname)
  end

  def self.some_method(cname)
    # some logic
  end
end

Let's make some changes to the concern.

module Normalize
  extend ActiveSupport::Concern

  class_methods do
    def normalize(*args, &block)
      options = args.extract_options!
      normalizers = [block, options[:with]].flatten.compact

      before_validation do
        args.each { |field| send("#{field}=", normalized_value(field, normalizers)) }
      end
    end
  end

  private

  def normalized_value(field, normalizers)
    value = send(field).to_s

    normalizers.each do |normalizer|
      value = if normalizer.respond_to?(:call)
                normalizer.call(value)
              elsif value.respond_to?(normalizer)
                value.send(normalizer)
              end
    end

    value
  end
end

This is the final implementation of the normalize method. Instead of checking if the with option is an array, we now check if it's a block.

I'm pretty satisfied with the implementation and the only way to find if it fits all use cases is to use it on different code bases. I'm still on the lookout for more extractions from my existing projects and I'll try to share with you all if I find them useful.

References

Form validation in Rails

Abeid Ahmed — Sat, 14 Aug 2021 08:44:02 +0000

I've seen and implemented many ways to validate a form. Be it replacing a portion of the form with a Turbo stream or by using the more traditional approach of looping through the errors and then displaying the validation messages from the erb template itself. Although these techniques do the job, I feel that it violates common user experiences. I'll not be diving into the violations because this isn't the scope of this article. Instead, I'll be sharing my approach on how I validate forms and render server errors if any.

Tools used

Outlining the steps

When we submit a form in Rails, Turbo fires numerous events, such as turbo:submit-start, turbo:submit-end, and so on (Full list of events can be seen here). What we're interested in is the turbo:submit-end event that Turbo fires after the form submission-initiated network request is complete.
We'll tap into the event and look for any server-side errors. If there are errors, then we'll display them with the help of Stimulus.js without refreshing the page and without replacing the entire form.

Approach

Assume that we are validating a user sign-up form. We'll first set up our User model, then UsersController, then we'll move onto the form, and then lastly we'll write some Stimulus.js code.

# app/models/user.rb

class User < ApplicationRecord
  validates :name, presence: true
  validates :email, presence: true, uniqueness: true
  validates :password, presence: true, length: { minimum: 6 }
end

I know this isn't ideal for validating a user, but for the sake of this tutorial, it should work.

# app/controllers/users_controller.rb

class UsersController < ApplicationController
  def new
    @user = User.new
  end

  def create
    user = User.new(user_params)

    if user.save
      # do something
    else
      render json: ErrorSerializer.serialize(user.errors), status: :unprocessable_entity
    end
  end

  private

  def user_params
    params.require(:user).permit(:name, :email, :password)
  end
end

I'd like you all to focus on the else block of the create action. We want to send a JSON response of all the errors that are triggered in a format that can be easily consumed by our Stimulus controller.

errors = [
    {
        type: "email",
        detail: "Email can't be blank"
    },
    {
        type: "password",
        details: "Password is too short (mininum is 6 characters)"
    }
]

This is the format of the errors that we want. Let's define the ErrorSerializer module to render this format.

# app/serializers/error_serializer.rb

module ErrorSerializer
  class << self
    def serialize(errors)
      return if errors.nil?

      json = {}
      json[:errors] = errors.to_hash.map { |key, val| render_errors(errors: val, type: key) }.flatten
      json
    end

    def render_errors(errors:, type:)
      errors.map do |msg|
        normalized_type = type.to_s.humanize
        msg = "#{normalized_type} #{msg}"
        { type: type, detail: msg }
      end
    end
  end
end

Now that we've covered the backend portion, let's move onto implementing the form and the Stimulus.js controller.

<%# app/views/users/new.html.erb %>

<%= form_with model: @user, data: { controller: "input-validation", action: "turbo:submit-end->input-validation#validate" } do |f| %>
  <div>
    <%= f.label :name %>
    <%= f.text_field :name %>
    <p data-input-validation-target="errorContainer" data-error-type="name" role="alert"></p>
  </div>

  <div>
    <%= f.label :email %>
    <%= f.email_field :email %>
    <p data-input-validation-target="errorContainer" data-error-type="email" role="alert"></p>
  </div>

  <div>
    <%= f.label :password %>
    <%= f.password_field :password %>
    <p data-input-validation-target="errorContainer" data-error-type="password" role="alert"></p>
  </div>

  <%= f.submit "Sign up" %>
<% end %>

Notice the p tag. We've added the data-error-type by which we'll know where to show the errors for a particular field. Next, we'll write some javascript to insert the errors in the respective p tags.

// app/javascript/controllers/input_validation_controller.js

import { Controller } from "stimulus"

export default class extends Controller {
  static targets = ['errorContainer']

  async validate(event) {
    const formData = await event.detail.formSubmission
    const { success, fetchResponse } = formData.result
    if (success) return

    const res = await fetchResponse.responseText
    const { errors } = JSON.parse(res)

    this.errorContainerTargets.forEach((errorContainer) => {
      const errorType = errorContainer.dataset.errorType
      const errorMsg = extractError({ errors, type: errorType })

      errorContainer.innerText = errorMsg || ''
    })
  }
}

function extractError({ errors, type }) {
  if (!errors || !Array.isArray(errors)) return

  const foundError = errors.find(
    (error) => error.type.toLowerCase() === type.toLowerCase()
  )
  return foundError?.detail
}

When we submit the form, turbo:submit-end event gets fired calling in the validate function in the Stimulus.js controller. If the validation succeeds then we do an early return, else we destructure the errors and render them inside the p tag that we defined earlier in our sign-up form.

This is one of the many ways to render errors on the client-side. If you have a better implementation, please let us know in the comments. Also, if you'd like to read a particular topic, do let me know.

Advanced ViewComponent patterns in Rails

Abeid Ahmed — Fri, 23 Jul 2021 10:03:51 +0000

ViewComponents are useful if you have tons of reusable partials with a significant amount of embedded Ruby. ViewComponent lets you isolate your UI so that you can unit test them and more.

By isolation, I mean that you cannot share your instance variables without explicitly passing them to the component. For example, in a normal Rails partials you can do this.



<%=# posts/show.html.erb %>

<h1><%= @post.name %></h1>
<%= render "some_partial" %>


<%=# posts/_some_partial.html.erb %>

<p><%= @post.created_at %></p>

Notice, how the instance variables are shared without explicitly passing it.

In this article, I'll be going over some patterns that I've learned by reading through other people's codebase.

Getting started

If you haven't already, let's get started by installing the gem itself.



# Gemfile

gem "view_component", require: "view_component/engine"

After you've installed the gem, create a new file at app/components/application_component.rb.



# app/components/application_component.rb

class ApplicationComponent < ViewComponent::Base
end

We'll use this class to add reusable code so that other components can inherit from it, and ViewComponent generators will also automatically inherit from this class if you've declared it.

Advanced patterns

Building GitHub's `subhead` component

To warm-up, we'll be building a simple subhead component that GitHub utilizes heavily in their settings page.



rails g component subhead

First, we'll start with the not-so-good approach. Then we'll optimize it to fit any purpose.

Upon closely looking at the subhead component, we can notice that

It has a title (mandatory)
It can have a description (optional)
It may have other states (such as danger)



# app/components/subhead_component.rb

class SubheadComponent < ApplicationComponent
  def initialize(title:, description: nil, danger: false)
    @title = title
    @description = description
    @danger = danger
  end

  def render?
    @title.present?
  end
end



<%=# app/components/subhead_component.html.erb %>

<div>
  <h2><%= @title %></h2>

  <p class="<%= @danger ? 'subhead--danger' : 'some other class' %>">
    <%= @description %>
  </p>
</div>

And then, you can use this component in your .erb files, by calling,



<%= render SubheadComponent.new(title: "something", description: "subhead description")

At first, it may seem feasible. But problems quickly arise when you start using this component more. What if you need to pass in additional styles to the h2 or the p? What if you need to pass in data- attributes? Umm, you'll probably feel lost in multiple if-else statements. This problem could have been avoided in the first place if we made our components more susceptible to changes.

ViewComponents can be called upon. That means we can use lambda to make our components decoupled from the state.



# app/components/application_component.rb

class ApplicationComponent < ViewComponent::Base
  def initialize(tag: nil, classes: nil, **options)
    @tag = tag
    @classes = classes
    @options = options
  end

  def call
    content_tag(@tag, content, class: @classes, **@options) if @tag
  end
end

We're defining the call method so that we can use our lambda. It's all Rails, so we can probably use content_tag and other view helpers as well. Now let's change our subhead component.



# app/components/subhead_component.rb

class SubheadComponent < ApplicationComponent
  renders_one :heading, lambda { |variant: nil, **options|
    options[:tag] ||= :h2
    options[:classes] = class_names(
      options[:classes],
      "subhead-heading",
      "subhead-heading--danger": variant == "danger",
    )

    ApplicationComponent.new(**options)
  }

  renders_one :description, lambda { |**options|
    options[:tag] ||= :div
    options[:classes] = class_names(
      options[:classes],
      "subhead-description",
    )

    ApplicationComponent.new(**options)
  }

  def initialize(**options)
    @options = options

    @options[:tag] ||= :div
    @options[:classes] = class_names(
      options[:classes],
      "subhead",
    )
  end

  def render?
    heading.present?
  end
end



<%=# app/components/subhead_component.html.erb %>

<%= render ApplicationComponent.new(**@options) do %>
  <%= heading %>
  <%= description %>
<% end %>

I know it looks intimidating at first, but I promise you that you'll be blown away at how reusable the component is.

Using this component is easy, the hard part was making it work.



<%= render SubheadComponent.new(data: { controller: "subhead" }) do |c| %>
  <% c.heading(classes: "more-classes") { "Hey there!" } %>

  <% c.description(tag: :div, variant: "danger") do %>
    My description 
  <% end %>
<% end %>

Now, compare this with what we had earlier. I know right. This is way better than the previous version. Let's build another component.

Your friend, the avatar component

This time we'll be using the inline variant of the ViewComponent.



rails g component avatar --inline

After you run the command, notice that it only generates the .rb file and not the .html.erb file. For simple components, it's fine to just render it from the .rb file itself by making use of the ApplicationComponent.



class AvatarComponent < ApplicationComponent
  def initialize(src:, alt:, size: 9, **options)
    @options = options

    @options[:tag] ||= :img
    @options[:src] = src
    @options[:alt] = alt
    @options[:classes] = class_names(
      options[:classes],
      "avatar rounded-full flex items-center justify-center",
      "avatar--#{size}",
    )
  end

  def call
    render ApplicationComponent.new(**@options)
  end
end

You can now use this component.



<%= render AvatarComponent.new(src: "some url", alt: "your alt attribute", size: 10) %>

As always, you can pass in classes, data attributes, and more. In my opinion, this is a good way to build components. They are segregated from your business logic and allow unit testing, which is advantageous as compared to normal Rails partials.

Building a popover

Popovers are used to bring attention to specific user interface elements, typically to suggest an action or to guide users through a new experience - Primer CSS.

We'll be using Stimulus.js to show and hide the popover. If you haven't already, please install Stimulus.js.



// app/javascript/controllers/popover_controller.js

import { Controller } from "stimulus"

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

    initialize() {
        document.addEventListener("click", (event) => {
            if (this.element.contains(event.target)) return
            this.hide()
        })
    }

    toggle(event) {
        event.preventDefault()
        this.containerTarget.toggleAttribute("hidden")
    }

    hide() {
        this.containerTarget.setAttribute("hidden", "")
    }
}

First, let's add this to our app/components/application_component.rb, so that we can pass in other data attributes without any complexity.



# app/components/application_component.rb

def merge_attributes(*args)
  args = Array.new(2) { Hash.new } if args.compact.blank?
  hashed_args = args.map { |el| el.presence || {} }

  hashed_args.first.deep_merge(hashed_args.second) do |_key, val, other_val|
    val + " #{other_val}"
  end
end

Run rails g component popover and let's get started.



# app/components/popover_component.rb

class PopoverComponent < ApplicationComponent
  DEFAULT_POSITION = :top_left

  POSITIONS = {
    bottom: "popover-message--bottom",
    bottom_right: "popover-message--bottom-right",
    bottom_left: "popover-message--bottom-left",
    left: "popover-message--left",
    left_bottom: "popover-message--left-bottom",
    left_top: "popover-message--left-top",
    right: "popover-message--right",
    right_bottom: "popover-message--right-bottom",
    right_top: "popover-message--right-top",
    top_left: "popover-message--top-left",
    top_right: "popover-message--top-right"
  }.freeze

  renders_one :body, lambda { |caret: DEFAULT_POSITION, **options|
    options[:tag] ||= :div
    options[:classes] = class_names(
      options[:classes],
      "popover-message box p-3 shadow-lg mt-1",
      POSITIONS[caret.to_sym],
    )

    ApplicationComponent.new(**options)
  }

  def initialize(**options)
    @options = options

    @options[:tag] ||= :div
    @options[:classes] = class_names(
      options[:classes],
      "popover",
    )
    @options[:data] = merge_attributes( # we're utilizing the `merge_attributes` helper that we defined earlier.
      options[:data],
      popover_target: "container", # from stimulus controller. Compiles to "data-popover-target": "container"
    )
  end
end



<%=# app/components/popover_component.html.erb %>

<%= render ApplicationComponent.new(**@options, hidden: "") do %>
  <%= body %>
<% end %>

Note that we're hiding the popover at first. We'll use stimulus controller to remove this attribute later.

Let's test this component out by using it in our view files.



<div data-controller="popover">
    <button type="button" data-action="popover#toggle">
        Toggle popover
    </button>

    <%= render PopoverComponent.new do |c| %>
      <% c.body(caret: "bottom_right") do %>
        <p>Anything goes inside</p>
      <% end %>
    <% end %>
</div>

One thing we can all learn from this component is that, we should not make our components too coupled with other UI's. For example, we could have easily rendered out a button in the component.



<%=# app/components/popover_component.html.erb %>

<%= render ApplicationComponent.new(**@options, hidden: "") do %>
  <button type="button" data-action="popover#toggle">
      Toggle popover
  </button>

  <%= body %>
<% end %>

Ask yourself, what are we building? In this case, it's a popover. It should not know about the button or the anchor_tag or any other component that is responsible for showing and hiding the popover component.

Try to make your components as generic as possible. Obviously, there will be some very specific components. For example, if you are rendering out a list of users. You may want that list to fit a particular need, and it's OK.

Making the `render` method succint

Even if you do not agree with all the things that I've written, you'll mostly agree that render PopoverComponent.new doesn't look that good. Calling a class directly in your views, Ummm, I don't know.

So let's try to simplify it.



# app/helpers/application_helper.rb

def render_component(component_path, collection: nil, **options, &block)
  component_klass = "#{component_path.classify}Component".constantize

  if collection
    render component_klass.with_collection(collection, **options), &block
  else
    render component_klass.new(**options), &block
  end
end

Now, you can use the components like this, render_component "popover", **@options, which in my opinion looks much better and reads much better.

Conclusion

Rails is fun. I like it. If you've found or are using any other ViewComponent patterns in your codebase, please share it in the comments. We'd like to learn more about your approach.

Thank you for reading through and I hope you learned something new today.

References

Edit 1

Rename data_attributes method to merge_attributes
Make use of deep_merge method that Rails gives us within the merge_attributes method

Custom authentication in Ruby on Rails

Abeid Ahmed — Tue, 13 Jul 2021 11:11:24 +0000

When I was starting with Rails, I used to reach out to Devise every single time to handle the authentication. I thought myself to be a pro. You just need to install the gem and run a few commands and there you have it. A working authentication system!

Soon after, I decided to build an invitation system, wherein the owner of the project could invite collaborators. To my surprise, there was a gem already, and that too, it was built for applications that were already using Devise. After fiddling with the gem, I realized that I was overriding most of the methods just to get the functionality of the app that I desired. So after reading a handful of articles on authentication, I decided to build my own.

This article assumes that you have some basic understanding of how Rails works, what cookies are, and how cookie signing works.

Let's start with a fresh new rails app

rails new custom-authentication -T -d postgresql
cd custom-authentication

The -T flag tells rails that we do not want the default test framework. We'll use RSpec to test our application.

Installing the gems that we need

gem "bcrypt", "~> 3.1.7"

group :development, :test do
  gem "factory_bot_rails", "~> 6.2"
  gem "rspec-rails", "~> 5.0", ">= 5.0.1"
  gem "shoulda-matchers", "~> 4.5", ">= 4.5.1"
end

Add these gems to your Gemfile if you don't have it already. We'll not be discussing what these gems do. Try googling and I'll promise you that you'll learn more about those gems from their official documentation.

Setting up the test suite

After installing the gems, run rails g rspec:install. After successfully running the command, you should have the spec directory at the root of your application.

Create a new directory called support inside the spec directory.

Within the spec/support/factory_bot.rb, add these lines.

# spec/support/factory_bot.rb

RSpec.configure do |config|
  config.include FactoryBot::Syntax::Methods
end

Within the spec/support/shoulda_matchers, add these lines.

# spec/support/shoulda_matchers.rb

Shoulda::Matchers.configure do |config|
  config.integrate do |with|
    with.test_framework :rspec
    with.library :rails
  end
end

These are steps in setting up our test framework so that we can leverage the methods that the gems provide.

Now navigate to the spec/rails_helper.rb and uncomment the line

Dir[Rails.root.join("spec/support/**/*.rb")].each { |f| require f }

which is usually found in line 27.

That should be it for now.

Creating a user model

Create a User model so that we can store the users credentials and later use them to authenticate the user.

rails g model user email:string:uniq password:digest auth_token:string:uniq

You should have similar to these lines of code on your db/migrate/234235235_create_users.rb. Run rails db:migrate after that.

class CreateUsers < ActiveRecord::Migration[6.1]
  def change
    create_table :users do |t|
      t.string :email
      t.string :password_digest
      t.string :auth_token

      t.timestamps
    end

    add_index :users, :email, unique: true
    add_index :users, :auth_token, unique: true
  end
end

We'll use the auth_token as a signed cookie.

Now navigate to spec/factories/users.rb and let's set up the user factory. In short, factories are a superset to the Rails fixtures.

# spec/factories/users.rb

FactoryBot.define do
  factory :user do
    sequence(:email) { |n| "janethebest#{n}@example.com" }
    password { "secretpassword" }
    sequence(:auth_token) { |n| "secret_token#{n}" }
  end
end

Now, we'll write some specs so that in the future when we modify parts of code, we can be sure that our application still functions as it's supposed to.

# spec/models/users_spec.rb

require "rails_helper"

RSpec.describe User, type: :model do
  subject(:user) { build(:user) }

  describe "validations" do
    it { is_expected.to have_secure_password }

    it { is_expected.to validate_presence_of(:email) }

    it { is_expected.to validate_length_of(:email).is_at_most(255) }

    it { is_expected.to validate_uniqueness_of(:email).case_insensitive }

    it { is_expected.to allow_value("johndoe@example.com", "johjn@exa.co.in").for(:email) }

    it { is_expected.not_to allow_value("johndoeexample.com", "johjn@exa").for(:email) }

    it { is_expected.to validate_length_of(:password).is_at_least(6) }
  end

  describe "callbacks" do
    it "normalizes the email before validation" do
      email = "   hello@example.com "
      user.email = email.upcase
      user.save!

      expect(user.email).to eq("hello@example.com")
    end

    it "generates user auth_token at random" do
      user.auth_token = nil
      user.save!

      expect(user.auth_token).to be_present
    end
  end
end

Run the tests, and it should fail.

Navigate to app/models/user.rb and paste in those lines

class User < ApplicationRecord
  VALID_EMAIL_REGEX = /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i

  has_secure_password
  has_secure_token :auth_token

  before_validation :normalize_email

  validates :email, presence: true, length: { maximum: 255 }, uniqueness: { case_sensitive: false }, format: { with: VALID_EMAIL_REGEX }
  validates :password, presence: true, length: { minimum: 6 }, allow_blank: true

  private

  def normalize_email
    self.email = email.to_s.strip.downcase
  end
end

Run the tests again, and it should all pass. In short, what we're doing is that:

We want to have a unique email address for every user and they should not be able to enter an invalid email address.
We want to validate that the length of the password should at least be 6.
We will be stripping out the whitespaces from the email address that the user enters through the form, and we will also be lowercasing it.

Note: If you notice that we are passing allow_blank: true on the password validation. If you are worrying that the user signing up will be able to set in nil or an empty string as their password, then do not. bcrypt will automatically throw an error when this happens.

The reason why we're doing that is to let the users not specify their password every single time they update their email address or their name.

I guess this is pretty much it for the user model. Now let's move on to the users_controller.

Creating a `UsersController`

Run rails g controller users and navigate to the routes.rb file.

Add,

resources :users, only: %i[create]

First, let's add some specs for the users_controller.

# spec/requests/users_spec.rb

require "rails_helper"

RSpec.describe "Users", type: :request do
  let(:valid_attributes) { { email: "john@example.com", password: "secretpass" } }
  let(:invalid_attributes) { { email: "john@example.com", password: "" } }

  describe "#create" do
    context "when the request is valid" do
      it "creates the user" do
        expect do
          post users_path, params: { user: valid_attributes }
        end.to change(User, :count).by(1)
      end

      it "stores the auth_token in the cookie" do
        post users_path, params: { user: valid_attributes }

        expect(signed_cookie[:auth_token]).to eq(User.first.auth_token) # You probably do not have the `signed_cookie` method
      end
    end

    context "when the request is invalid" do
      it "returns an error" do
        post users_path, params: { user: invalid_attributes }

        expect(json.dig(:errors, :password)).to be_present # You also do not have the `json` method. Let's add them first
        expect(response).to have_http_status(:unprocessable_entity)
      end
    end
  end
end

Run the tests, and you'll probably get an error saying that you do not have the signed_cookie and the json method defined. Let's add them first.

# spec/support/requests/sessions_helper.rb

module Requests
  module SessionsHelper
    def signed_cookie
      ActionDispatch::Cookies::CookieJar.build(request, cookies.to_hash).signed
    end
  end
end

# spec/support/json_helper.rb

module JsonHelper
  def json
    JSON.parse(response.body, symbolize_names: true)
  end
end

Let's go to the rails_helper.rb file and include these modules

# spec/rails_helper.rb

RSpec.configure do |config|
  config.include JsonHelper
  config.include Requests::SessionsHelper, type: :request
end

After including the modules, run the tests again and it should fail without complaining about the method not defined errors.

Navigate to the app/controllers/users_controller.rb

# app/controllers/users_controller.rb

class UsersController < ApplicationController
  def create
    user = User.new(user_params)

    if user.save
      cookies.signed.permanent[:auth_token] = user.auth_token # you could also set an expiring cookie that would expire after a certain time.
      # do your thing. Redirect?
    else
      render json: { errors: user.errors }, status: :unprocessable_entity
    end
  end

  private

  def user_params
    params.require(:user).permit(:email, :password)
  end
end

Now, run the tests again and it should pass. We're done with signing up the user. Now let's focus on signing in the user.

Signing in the user

We'll be creating a Plain Old Ruby Object (PORO) to handle the core logic of the authentication, like finding the user record and verifying if the password entered is correct or not.

Create a new file authentication.rb under the app/models/ directory.

# app/models/authentication.rb

class Authentication
  def initialize(params)
    @email = params[:email].to_s.downcase
    @password = params[:password]
  end

  def user
    @user ||= User.find_by(email: @email)
    return unless @user

    @user.authenticate(@password) ? @user : nil
  end

  def authenticated?
    user.present?
  end
end

Let's unit test this class

# spec/models/authentication_spec.rb

require "rails_helper"

RSpec.describe Authentication do
  describe "#user" do
    it "returns the user if present" do
      user = create(:user)
      auth = described_class.new(email: user.email, password: user.password)

      expect(auth.user).to eq(user)
    end

    it "returns the user for case insensitive email" do
      user = create(:user)
      auth = described_class.new(email: user.email.upcase, password: user.password)

      expect(auth.user).to eq(user)
    end

    it "returns nil if user is not found" do
      auth = described_class.new(email: "invalid@email.com", password: "password")

      expect(auth.user).to be_nil
    end

    it "returns nil if user's credentials do not match" do
      user = create(:user)
      auth = described_class.new(email: user.email, password: "invalidpassword")

      expect(auth.user).to be_nil
    end
  end

  describe "#authenticated?" do
    it "returns true if user is found" do
      user = create(:user)
      auth = described_class.new(email: user.email, password: user.password)

      expect(auth).to be_authenticated
    end

    it "returns false if user is not found" do
      auth = described_class.new(email: "invalid@email.com", password: "password")

      expect(auth).not_to be_authenticated
    end
  end
end

Generating the `SessionsController`

Run rails g controller sessions and navigate to the routes.rb file.

resources :sessions, only: %i[create]

Navigate to the spec/requests/sessions_spec.rb and let's write some specs.

# spec/requests/sessions_spec.rb

require "rails_helper"

RSpec.describe "Sessions", type: :request do
  describe "#create" do
    context "when the request is valid" do
      it "signs the user" do
        user = create(:user)
        post sessions_path, params: { email: user.email, password: user.password }

        expect(signed_cookie[:auth_token]).to eq(user.auth_token)
      end
    end

    context "when the request is invalid" do
      it "does not sign the user" do
        post sessions_path, params: { email: "invalid@example.com", password: "helloworld" }

        expect(signed_cookie[:auth_token]).to be_nil
        expect(json.dig(:errors, :invalid)).to be_present
        expect(response).to have_http_status(:unprocessable_entity)
      end
    end
  end
end

Run the tests and it should fail. Let's get those specs passing!

# app/controllers/sessions_controller.rb

class SessionsController < ApplicationController
  def create
    auth = Authentication.new(params) # remember this class?

    if auth.authenticated?
      cookies.signed.permanent[:auth_token] = auth.user.auth_token
      # do your thing. Redirect to some page?
    else
      render json: { errors: { invalid: ["credentials"] } }, status: :unprocessable_entity
    end
  end
end

Run the tests again and it should all pass.

How the heck do we define the `current_user` method now?

Devise and other libraries provide us a handful of helper methods such as current_user, authenticate_user, etc.

We'll do this the new way. We'll be leveraging the ActiveSupport::CurrentAttributes class to make the authenticated user available globally. I know globals are controversial, but hey, why not for the sake of the tutorial.

Create a file current.rb within the app/models/ directory.

# app/models/current.rb

class Current < ActiveSupport::CurrentAttributes
  attribute :user
end

Now navigate to the application_controller.rb file and add these lines.

# app/controllers/application_controller.rb

before_action :set_current_user

private

def set_current_user
  Current.user = User.find_by(auth_token: cookies.signed[:auth_token]) 
end

Now, after every single request, the set_current_user method will fire up and will try to set the Current.user.

For example:

User signs up
The cookie gets stored.
The user gets redirected to another page.
The set_current_user fires up and sets the Current.user for you to be used in your app.

A quick note

Since Current.user fires up in each request, please do not use it within your background jobs.

Conclusion

So there you have it. A fully working authentication system that you can customize to your needs. Although we did not write the views, I assure you that it's pretty simple. Try fiddling with the system and you can come up with even better solutions.

That's it for now. Thank you for taking the time to read through. You rock!

The process behind creating a ruby gem

Abeid Ahmed — Tue, 16 Mar 2021 09:39:57 +0000

Lately, especially in the rails community, we've been witnessing lots of new stuff like the hotwire, and the new encryption system.

Jorge Manrubia

@jorgemanru

Excited about finally sharing the encryption system we cooked for HEY. Will happen this week.

23:19 PM - 10 Mar 2021

If you notice carefully, all of these have been extracted from pre-existing applications.

So you might be wondering, what's the deal with extractions? Why can't I just start writing the gem?

The most obvious answer that I can give you is that it is difficult to visualize the usage of the gem itself. For example, say you're building an authorization library gem. You would probably need some method that would run before the controller actions and pass in some attributes like the current_user, role, action name, etc to the policy. Also, should the policies be scoped to the model? But if you do that, how would you deal with policies that do not have a model?

In order to answer all of these questions, it would be much easier to first implement the functionality into your existing rails application and then extract it if you wish to do so.

The story behind

Recently, I was working on a project that had the traditional dashboard design; plenty of SVG icons, user avatar, unnecessary graphs, and charts, etc. The Figma wireframes used icons from heroicons, and naturally, the first thought that came to my mind was to look for a gem that provided a views helper method for rendering out the icons.

I found a couple of gems that did this, and I quickly installed one of them and started using it. After some time, I realized the gem that I installed wasn't extensible. I wasn't able to pass other HTML attributes other than the ones supported by the gem. So the only thought that came into my mind was to create a helper method that would take in any HTML attribute like the styles, class, aria, data, etc.

The first thing that I did was to look for other ruby gems that did something like this. I came across octicons by GitHub and liked how they implemented the gem.

Step 1 - Figuring out the syntax of the helper method

<%= heroicon "user", class: "custom-class", aria: { label: "user icon" } %>

The first argument is the icon name, and the rest of the options are HTML attributes. Rails already provides a neat helper method called the content_tag, so it was a no-brainer for me to utilize it.

Step 2 - Setting up the defaults

Each icon library has some defaults, like stroke-width, viewBox, etc. In the case of heroicon, they had two variants, namely: outline and solid. So I came up with the following syntax:

<%= heroicon "user", variant: "solid" %>

or, just

<%= heroicon "user" %>

for rendering the outline version of the icon.

Step 3 - Implementing the logic

After you come with a syntax that you like, the next step would be to test out the helper method and write the logic for it. You're pretty much done now.

Step 4 - Bundling into a gem

What's on this step? Initialize the gem repo, copy and paste all the logic and the tests, write your gem's description, and publish it to the world.

Self-promotion

This is the gem (rails_heroicon) that I implemented following this process. Be sure to stargaze it and use it in your next project if you feel the need to use SVG icons.

I was so satisfied with this process that I created another gem for feathericons. The gem is called rails_feather.

Conclusion

I agree that there isn't one way of doing the right thing. Especially in software engineering, it's all about trial and error. I found this process quite productive and useful and thought I would share it with you all.
I hope you find it useful.

Understanding proc objects

Abeid Ahmed — Wed, 01 Jul 2020 06:42:47 +0000

What is a proc?

Proc objects are blocks of code that have been bound to a set of local variables. That means we can pass them as method arguments, push them inside an array, and do any other things that we normally do to objects.

Before moving on, I would like to clarify that Proc will denote the class and proc will denote the instance of the Proc class.

Calling a proc

pr = Proc.new { puts "hello world, once" }
pr.call

# hello world, once

Proc.new is an alias for the Kernel#proc method.

pr = Kernel.proc { puts "hello world, twice" }
pr.call

# hello world, twice

We can also write like this.

pr = proc { puts "hello world, thrice" }
pr.call

# hello world, thrice

Capturing a code block

A method can capture a block and objectify it using the special & operator. Without the & operator, ruby has no way of understanding that you want to perform a block to proc conversion, rather than passing a regular argument.

def call_a_proc(&block)
    block.call
end

call_a_proc { puts "Hello world" }

# Hello world

Similar to this we can also place a Proc.new to serve in place of the code block.

p = Proc.new { |x| puts x.upcase }
%w(abeid ahmed).each(&p)

It outputs to:

ABEID
AHMED
=> ["abeid", "ahmed"]

Here p is an instance of the Proc class. You can verify this using the p.class in your terminal.

A Proc.new takes in a code block that tells what to do when a proc is called. Now that is exactly what we are doing in the above code.

If you are writing ruby for sometime, you must be familiar with the each keyword. each method, takes in a block of some kind with an argument. The &p convinces each that it doesn't need an actual block and to receive a proc object.
The above code is same as saying:

%w(abeid ahmed).each { |x| puts x.upcase }

Block-proc conversion

def capture_block(&block)
    block.call
end

capture_block { puts "Beautiful day" }

We've seen this type of code in one of the examples above. So, here's how this method gets called.

Step 1

The capture_block method with the code block is called first.

capture_block { puts "Beautiful day" }

Step 2

A new proc object is created using the Proc.new.

Proc.new { puts "Beautiful day" }

Step 3

The proc created in step 2, is captured or bound to the block argument in the capture_block method.

capture_block(&block)

So, these are the three steps that are completed to call the capture_block method.

Wait, there's more to this proc. Keen readers would be able to identify it and even if you didn't it is completely fine.

Remember the each example that we talked about? We passed in a Proc.new, like,

%w(abeid ahmed).each(&p)

We can do the same with the capture_block method. Instead of calling the block like,

capture_block { puts "hello world" }

we can do exactly the same as the each method. First we create a new Proc.new and we pass it on.

my_proc = Proc.new { puts "Another way" }
capture_block(&my_proc)

# Another way

Conclusion

In this article we have accomplished quite a lot. We learned how to create proc objects, how to capture them, and how the conversion from block to proc takes place. If you are interested in learning more about Proc head over to the official ruby docs.

This is my first article on this platform, so go easy on me 😄. If you found this article helpful, you know the drill and if there's any typo or general errors let me know in the comments. Good day and happy learning!

Credits: The Well Grounded Rubyist

DEV Community: Abeid Ahmed

New way of bundling JS/CSS in Rails

Normalizing ActiveRecord attributes with a custom DSL

The normalize method

Designing for resilience

References

Form validation in Rails

Tools used

Outlining the steps

Approach

Advanced ViewComponent patterns in Rails

Getting started

Advanced patterns

Building GitHub's subhead component

Your friend, the avatar component

Building a popover

Making the render method succint

Conclusion

References

Edit 1

Custom authentication in Ruby on Rails

Let's start with a fresh new rails app

Installing the gems that we need

Setting up the test suite

Creating a user model

Creating a UsersController

Signing in the user

Generating the SessionsController

How the heck do we define the current_user method now?

A quick note

Conclusion

The process behind creating a ruby gem

The story behind

Step 1 - Figuring out the syntax of the helper method

Step 2 - Setting up the defaults

Step 3 - Implementing the logic

Step 4 - Bundling into a gem

Self-promotion

Conclusion

Understanding proc objects

What is a proc?

Calling a proc

Capturing a code block

Block-proc conversion

Step 1

Step 2

Step 3

Conclusion

The `normalize` method

Building GitHub's `subhead` component

Making the `render` method succint

Creating a `UsersController`

Generating the `SessionsController`

How the heck do we define the `current_user` method now?