DEV Community: Alessandro Rodi

Rails Blog with DatoCMS

Alessandro Rodi — Sat, 25 Jan 2025 22:30:11 +0000

DatoCMS is an amazing Headless CMS. I wrote already in the past how to integrate it into your Ruby On Rails application, and today I want to show you how to implement a real blog mimicking what is already done for other frameworks, for example nextjs.

Create a Dato project

You can clone the existing template for this tutorial. This template will setup all the models you need on Dato and create some blog posts.

Head to the Project Settings and save your GraphQL API Token for later.

Setup Rails App

Our Rails 8 application is set up using a simple rails new dato-blog command. In a few seconds you'll have your Rails 8 app ready and you can start it with bin/dev.

You can now include the dato-rails gem in your Gemfile and set the API token in your credentials as dato.api_token.

You can finally write a simple test to verify that the installation is successful:

# test/models/dato_queries_test.rb

require 'test_helper'

class DatoQueriesTest < ActiveSupport::TestCase
  def test_homepage_query
    homepage_query =
      GQLi::DSL.query do
        allPosts {
          title
        }
      end

    client = Dato::Client.new
    response = client.execute(homepage_query)
    assert_not_empty response.data.allPosts
  end
end

What this test does, is to run a GraphQL Query and test the connection to DatoCMS.

You can always head to the CDA Playground in DatoCMS to create new queries.

Simple styling

Let's also set up Bootstrap for some simple, default styles. The Dato Rails integration does not provide any CSS, so you can easily integrate your favorite CSS Framework.

You can add Bootstrap in your application.html.erb to have some styling:

# app/views/layouts/application.html.erb

<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet">


<body>
  <div class="container">
    <%= yield %>
  </div>
</body>

Blog Post Page

Head to the Blog Example to see a Preview of the website we want to build. We will start with the single Blog Post page and then we will implement the Homepage.

The first thing you need is the query to fetch a single blog post.

You can create a models/dato_queries.rb file to include your queries.

# models/dato_queries.rb

module DatoQueries
  def homepage_query
    GQLi::DSL.query do
      allPosts {
        title        
      }
    end
  end

  def blog_post_query(slug)
    GQLi::DSL.query do
      post(filter: { slug: { eq: slug } }) {
        title
        slug
        date
        author {
          name
        }
      }
    end  
  end
end

Before digging further, let's test it:

# test/models/dato_queries_test.rb

require 'test_helper'

class DatoQueriesTest < ActiveSupport::TestCase
  include DatoQueries

  def test_homepage_query
    client = Dato::Client.new
    response = client.execute(homepage_query)
    assert_not_empty response.data.allPosts
  end

  def test_blog_post_query
    client = Dato::Client.new
    response = client.execute(blog_post_query('mistakes-tourists-make-on-their-first-trip-abroad'))
    assert_not_empty response.data.post.title
  end
end

Now that we have the queries, we need to implement the page.

Head to your routes.rb and add

resources :blog_posts, only: [:show], param: :slug

and our controller will look like this:

# app/controllers/blog_posts_controller.rb

class BlogPostsController < ApplicationController
  include DatoQueries

  def show
    response = blog_post_query(params[:slug])
    render BlogPostComponent.new(response.data)
  end
end

here is a simple implementation of the BlogPostComponent that renders the blog post.

# app/components/blog_post_component.rb

class BlogPostComponent < Dato::BaseComponent
end

# app/components/blog_post_component.html.erb

<h1><%= data.post.title %></h1>

You can now head to http://localhost:3000/blog_posts/mistakes-tourists-make-on-their-first-trip-abroad to see your post title.

You now rendered content from DatoCMS into your Rails Application. Let's add the header image now.

The first thing we need to do is to fetch the image from Dato. Our query will become:

def blog_post_query(slug)
  GQLi::DSL.query do
    post(filter: { slug: { eq: slug } }) {
      title
      slug
      date
      author {
        name
      }
      coverImage {
        responsiveImage(imgixParams: { fm: :jpg, fit: :crop, w: 2000, h: 1000 }) {
          ___ Dato::Fragments::ResponsiveImage
        }
      }
    }
  end
end

dato-rails offers a GraphQL fragment to fetch images from DatoCMS in the right format to be displayed. Read more about it on DatoCMS. We are fetching the coverImage and using the existing ResponsiveImage fragment provided by dato-rails to get all the data we need.

With this updated query, we can now display the header image.

# app/components/blog_post_component.html.erb

<h1><%= data.post.title %></h1>

<div class="d-flex">
  <span class="mr-auto"><%= data.post.author.name %></span>
</div>

<%= render Dato::ResponsiveImage.new(data.post.coverImage.responsiveImage) %>

From now on, you can look at the component code and the query code on the Github Repository to see the final version.

Homepage

Rendering the Homepage has nothing special at this point. You can check the Github Repo for the final code, but you basically need a root in your routes.rb, a controller, a new component, and a query.

# app/config/routes.rb

root "homepage#show"

# app/controllers/homepage_controller.rb

class HomepageController < ApplicationController
  include DatoQueries

  def show
    render HomepageComponent.new(homepage_query)
  end
end

Preview mode

We have the following concepts:

graphQL Query: logic to fetch data
controller: responsible for choosing a query and using it to renderer a component
component: responsible for the view logic.

DatoCMS offers a preview mode. You are responsible of deciding how and when a preview is displayed, this can be enabled for specific users of your application, or with a secret token in the URL. In our example we will use the preview parameter of the URL.

You can change the BlogPostsController as follows:

render Dato::Wrapper.new(BlogPostComponent, blog_post_query(params[:slug]), preview: params[:preview])

to enable preview rendering when the preview parameter is passed.

Head to http://localhost:3000/blog_posts/mistakes-tourists-make-on-their-first-trip-abroad?preview=true

and you will see the Draft version of your Blog Post. You can edit it on DatoCMS and see the new version until you publish it.

Live mode

The second, interesting feature is live mode so you don't need to manually refresh your Browser window anymore. Similar to what we did before change your controller in:

render Dato::Wrapper.new(BlogPostComponent, blog_post_query(params[:slug]), preview: params[:preview], live: params[:live])

to enable preview rendering when the preview parameter is passed.

Head to http://localhost:3000/blog_posts/mistakes-tourists-make-on-their-first-trip-abroad?preview=true&live=true

Caching

This is a very important topic since we don't want to hit DatoCMS every time we render a Blog Post page. The Dato::Wrapper component that you used previously will take care also of this and will cache the entire rendered component so that subsequent calls to the same page will be instant and will not require invoking DatoCMS again.

There are cases where you might not be using Dato::Wrapper, for such cases you can use the method data = execute_dato_query(your_query) to cache your query results automatically or directly Dato::Cache.fetch { ... } method similar to how you would use the Rails cache.

You should then configure Dato to automatically expire the cache when you publish your changes. Read more about it the README.

The Full-Stack development experience

Alessandro Rodi — Thu, 12 Oct 2023 12:48:13 +0000

Rails World 2023 closes many doors that have been opened recently and marks a turning point for Ruby On Rails. That is why this year's motto can be summarized as "The One Person Framework".

The Web has certainly been a complex environment in recent years. This complexity was necessary to push browsers to the limit and use the most advanced features.

But in 2023, this is no longer necessary!

Assets distribution

Let's think about CSS. For years, we used SASS to take advantage of variables and nested rules. Well, that is no longer necessary. These are both features made available directly by CSS now.

So we can say goodbye to compiling SASS into CSS and enjoy the pleasure of writing directly in CSS. This makes us much faster in development and requires one less knowledge (SASS) for each Full-stack developer.

A full-Stack developer is precisely what our profession provided for before the advent of powerful javascript frameworks for creating truly fluid web interfaces! However, it is time to simplify! It is time to stop being Partial-stack developers and focus on productivity again.

Let's talk about JavaScript. The language has matured so much in the last few years, and it is (almost) a joy to write in JavaScript. The consolidation of import maps for the distribution of JavaScript and CSS assets finally allows us to remove another element from our stack: bundling.

In 2023, thanks to importmaps, providing the browser with dozens of separate JavaScript files instead of a single file makes no difference! No more bundling! It is not only unnecessary but even harmful! If we modify just one of our files, we can serve the browser a new version of that one file instead of the entire bundle. Long live simplicity!

An additional element that we can finally remove from our stack is the minification of JavaScript and CSS files. Thanks to algorithms like brotli (with a very Swiss flavour) we no longer need to minify and compress our files before distributing them. Cloudflare, Nginx, or Apache will take care of everything for us.

And there goes our stack thinning, and with that, our Full-stack developers can focus again on productivity instead of technicalities about how to distribute their work to Browsers.

Ruby On Rails, thanks to propshaft, closes a chapter. Welcome to 2023, where deploying JavaScript and CSS is a breeze. Welcome to the no-build era.

Hard drives are cool

Another element that has radically changed in recent years is the speed of drives. With the advent of NVMe disks, the speed is ten times what we had ten years ago. That is why our stack can be further streamlined. To start with a new web application, we can use the disk for databases (SQLite), caches, WebSockets, and background jobs.

Great! It means you can have a web app with all the latest and most complex features...and zero dependencies.

When your application is used by millions of users worldwide, you can think about further optimizations, a better-performing database, or gain performance with more efficient caching systems. Until then, productivity is the key word. No frills and no dependencies. You can eliminate SQL and NoSQL databases from your stack and focus on development.

HTML-First architecture

Let's get to the last chapter. The most controversial one, the one most discussed. The Hotwire architecture: HTML Over The Wire. Ruby On Rails started down this path in 2015 with Turbolinks, but it was not until 2021, with the arrival of Turbo, that years of work was consolidated.

Today, we can confidently say that HTML Over The Wire is the right technology for maximizing productivity. When we maximize productivity, this is always at the expense of performance. With this technology, we will never have the performance of a JavaScript-First architecture. But what is it all about?

When discussing JavaScript-First Architecture, I have in mind applications where the backend and frontend, properly separated, communicate via JSON. The frontend uses JavaScript, and the backend also, possibly. The server and client communicate via JSON. The server is "dumb", it provides data to the client, which, thanks to the Frontend Framework from screaming, "builds" the entire web interface.

The client then has the entire responsibility of building web pages.

A truly efficient architecture that takes full advantage of all the capacity of modern devices, which have no difficulty in taking on the "onerous task." An architecture that maximizes performance...at the expense of productivity, of course. Not coincidentally, the first frameworks in this universe, Angular and React, were deployed by Google and Facebook, which have their main focus on performance. And we could do with more!

GitHub itself, which is based on Ruby On Rails, now adopts React in many parts of their frontend to be able to offer the best experience to its customers.

When I discuss HTML-First Architecture, however, I have in mind the Web of twenty years ago. The server, "intelligent", no longer solely transmits data to clients but directly HTML pages.

The client/server communication protocol is based on HTML, and the client goes back to being "stupid."

What changes today is that the client and server can communicate via HTML but update individual page elements instead of simply navigating to the next one.

This concept of partial updates allows us to rethink very complex pages into smaller elements (just as React taught us!) and update only the parts we care about.

The implementation offered by Ruby On Rails is called Turbo, and it allows for SPA-like user interfaces and experiences without having to learn a new framework.

Your browser does not support the video tag.

This element allows a Full-Stack developer to build applications with a modern flavour within a majestic monolith, while continuing to work only with HTML at all times. No more client/server separation and complex synchronization to achieve modern, fluid interfaces. Just one application, the stack of which can fit entirely in one person's head.

When they tell you about Multiple Page Apps vs. Single Page Apps, you will know this comparison no longer makes sense. There are JavaScript-First Frameworks that can safely create MPA's via Server-side rendering, and there are HTML-First Frameworks which can provide the same experience as an SPA.

HTML-First vs Javacript-First architecture is the distinction that needs to be made today.

App Store, Android Store

Having come to this point, to think that one person can manage the entire stack for Web application development is not only likely, it is reality! One person can develop a feature from start to finish: from database design, background processes, business logic, to frontend design. The Web stack was complex, but we finally simplified it!

Yes, a Full-Stack developer in 2023 has the tools to build a feature from start to finish, without waiting for his colleague to "expose" the API.

But there is a world that has always been quite obscure to us web developers: native iOS and Android app development. Native apps do not allow us all the simplifications we discussed above. Native app development follows other rules, and here I throw up my hands and give up.

But Ruby On Rails, since a couple of weeks ago, has released the missing piece of the stack for creating hybrid applications: Strada.

Thanks to Turbo and Strada, even our Full-Stack developer can make something that will be approved within the App Store. A hybrid app allows you to start from your existing Web application and release it as a native App once it is properly "wrapped" in a WebView. Turbo-ios and turbo-android, together with Strada, make it very easy to add all the native elements needed to optimize the user experience.

To date, dozens of apps are already made with this technology in the App Store, and I challenge anyone to distinguish them from a native app. Web View indeed means Browser, and Browsers are really powerful today! With good design and good animations, they are indistinguishable from fully native apps. And the beauty is that it is still your Web app. You don't need to expose APIs, and rebuild your iOS and Android interfaces. Just reuse your existing ones! This is an incredible boost to productivity!

What's next?

At the beginning of the article, I wrote that this is a turning point, but what's next? The next few years will be focused on this simplification of the stack and on improving these new tools at our disposal. Improving productivity is also done through developer tools. We need time to improve the whole ecosystem around these technologies. There are many new things, and it takes time to absorb and digest them.

Ruby On Rails continues to point the way, often independently and controversially, and we, after our recent membership in the Rails Foundation, are intent on following it.

Check the Keynote of Rails World 2023, to hear from the creator of Ruby On Rails, the concepts I took inspiration from, to write this blog post.

Rubyday 2023 - A great comeback!

Alessandro Rodi — Sat, 17 Jun 2023 11:03:07 +0000

The Rubyday 2023 has just concluded, and it was as amazing as I remembered it from 2019. Yes, sure, we had 2020 and 2021 online editions, but they don't really count to me.
The conferences are grand, especially for everything that happens between the official talks.
And Rubyday has something even more special: it may be the wonderful location, Verona, or perhaps it's the fact that you hear so many people speaking Italian, which gives a stronger sense of community and a desire to meet, or perhaps it's the small size, which allows you to approach so many people and spend many informal moments together.

The organizers have succeeded in a very difficult feat: organizing a conference with a new flavor, with many different insights, a great mix of technical and non-technical talks, speakers with various backgrounds from all over the world, but also, and above all, many who live and work in Italy, thus contributing to making this event unique and special.

The ruby community once again proves to be very close-knit, and I can't wait to see many people again, and meet new ones, at the numerous conferences we will have in Europe this year.
I go home with so many inputs and ideas to work on in the coming months.
Let's see which ones:

Paolo Perrotta explained to us how chatGPT works. Paolo has an innate ability to explain complex technologies in simple words. There couldn't have been a better keynote in my opinion: Welcome to Rubyday! An Italian rubyist will explain the secrets behind one of the most fascinating technologies of recent years, and it doesn't matter if it's not strictly related to ruby, because the insights for our work are immense. As developers, how will we be able to take full advantage of this technology in the coming years? Will Cucumber become relevant again? Or will we just end up writing tickets on Jira? The topic was so interesting that the discussion continued even after dinner.

Right after, here's a talk strictly related to ruby: Alessandro Rizzo showed us how to implement custom cops in rubocop and how Treatwell approaches the problem at the company level. Personally, it was really interesting to see that other companies, besides ours, Renuo, follow the same approach. Treatwell has released rubocop-treatwell, while Renuo uses renuocop. Each company creates its own set of rules to "maximize the happiness" of its developers.

And this connects to Bozhidar Batsov's talk, who with his sharp humor, made a beautiful journey through the latest versions of ruby and the many, new, features that have been released in the last four years, since 2019, which was the last Rubyday he spoke at.
A talk with many personal perspectives and quite philosophical, that tries to understand and reason around the motto of ruby: a programming language optimized for programmer happiness. Ruby has a really varied syntax, and that's why each work group has the opportunity, thanks to Rubocop, to configure the rules to its own liking.
A heartfelt thanks to Bug, who spends much of his time receiving insults on github 😀

And then another non-technical but highly effective talk, on how to handle one-on-one, Giulia Mialich, Engineering Manager at Nebulab, had a brilliant idea: to bring the point of view of a manager, to an audience predominantly of developers, on why one-on-one are organized in the company, why they are so important, and why they are completely in favor of the employees. The fact that a company does one-on-one should be considered a benefit. It's the most effective tool in the company to grow in your role, and an opportunity to have help and guidance in that sense. Take home message: being a manager means being a servant.

The next talk is from Frederick Cheung, who courageously brought many slides with Typescript code to a Rubyist audience 😂
This says a lot about the confidence you must have on stage to do something like that! 😆
We learned, if we didn't already know, JSON Schema and how to use it to reduce the possibility of errors when implementing our APIs and communicating with them from our frontend. JSON Schema can be used to test and validate what is returned from our Ruby-written APIs, but at the same time allows us to automatically generate Type Definitions in Typescript. In this way, if our APIs change, we will have errors already at compile-time on our frontend. 🤯
I can't wait to use this strategy in the future to have even more stable APIs and even safer integration with the frontend.

A brief lightning talk from Sergey Sergyenko to invite us to Euruko 2023 and then another technical talk from Ju Liu. His talks are always very fun and he's one of the few I know who still has the courage to do live-coding at a conference. His talk made us think and remember that the functional approach to programming exists and is often a much more elegant and readable solution than the imperative approach.
Take home message: functional programming is about structure transformation. When you program in a functional way, you have to think in terms of "how do I need to transform my data structure in order to achieve my goal?".
Thank you Ju!

And if the conference was not technical enough until now, here's another interesting talk from Ridhwana Khan on the caching techniques adopted by dev.to, the same platform on which you are reading this article. Did this article load instantly? Well, it's largely thanks to the work done by Ridhwana and other developers at dev.to. The techniques they use are truly cutting-edge and it's wonderful to see the myth that Rails=slow debunked once again. I love having insights on globally reaching software with millions of users. It's really interesting to see how the challenges I face every day can have a much wider scale and how Rails offers all the tools to do it. It's also very interesting to have small sneak peaks from the Network Inspector to understand how Response Headers are used to manage the cache at the browser level.

And to conclude, Hana Harencarova, with her talk, finally gave many useful tips on how to onboard Junior figures within a company, what our role as senior developers and CTOs is. It was wonderful to see how this talk met the needs of many companies present at the conference, looking for Ruby On Rails developers. I heard more than one person leave saying "maybe we could revise that job offer for Senior Developer, and open up to the possibility of Junior figures". With the advice that Hana gave us during this talk, hiring Juniors is no longer so scary, and also has the advantage of allowing our community to grow further.

Finally, grazie a Monica Giambitto, who it was really nice to see again after so many years and to the entire Grusp staff 👏. Thanks also to Renuo for giving me the opportunity to attend.

See you at the next conference!

Preloading associations on an Array of Objects

Alessandro Rodi — Wed, 04 Jan 2023 14:43:49 +0000

It might happen that your initial array of objects is not an ActiveRecord Relation.
You cannot use preload on an array of objects and therefore you suffer of N+1 queries.

Imagine we have a Restaurants list. The Restaurants are fetched from a remote Service and therefore we have a simple array of objects.

In our system we have Customers and they reference the Restaurant by external_restaurant_id.

This is the setup. There might be a lot of reasons why you cannot cache the restaurants locally of course.

class Restaurant
  def initialize(json)
    @json = json
  end

  def code = @json[:code]
  def name = @json[:name]
end

class Customer < ApplicationRecord

end

This is the partial that renders our restaurants:

<% @restaurants.each do |restaurant| %>
  <div class="card">
    <h5><%= restaurant.name %></h5>
    <hr>
    <h4>Customers list</h4>
    <% Customer.where(external_restaurant_code: restaurant.code).each do |customer| %>
      <%= customer.name %>
    <% end %>
  </div>
<% end %>

This causes clearly N+1 queries (more correctly just N, because there's no +1, since the restaurants are fetched remotely)

Customer Load (0.1ms)  SELECT "customers".* FROM "customers" WHERE "customers"."external_restaurant_code" = ?  [["external_restaurant_code", 1]]
  ↳ app/views/restaurants/index.html.erb:7
Customer Load (0.0ms)  SELECT "customers".* FROM "customers" WHERE "customers"."external_restaurant_code" = ?  [["external_restaurant_code", 2]]
  ↳ app/views/restaurants/index.html.erb:7
Customer Load (0.0ms)  SELECT "customers".* FROM "customers" WHERE "customers"."external_restaurant_code" = ?  [["external_restaurant_code", 3]]
  ↳ app/views/restaurants/index.html.erb:7
...

How can we avoid performing multiple queries? The Restaurant is not an ActiveRecord model, therefore we cannot do something like Restaurant.includes(:customers).each.

Our first approach was to just reimplement the preloading and do the following in the controller:

@restaurants = Restaurant.from_api
@customers = Customer.where(external_restaurant_code: @restaurants.map(&:code)).group_by(&:external_restaurant_code)

This solves already our problem and removes the repeated queries:

Customer Load (0.7ms)  SELECT "customers".* FROM "customers" WHERE "customers"."external_restaurant_code" IN (?, ?, ?)  [["external_restaurant_code", 1], ["external_restaurant_code", 2], ["external_restaurant_code", 3]]

but the code smells quite a bit: we are basically re-implementing eager loading ourselves and we are moving in the controller a lot of business logic. The example is rather easy, but it might get much more complex very fast.

Our solution consists of making the Restaurant an ActiveRecord object. Here is an example:

class WrappedRestaurant < ApplicationRecord
  attr_reader :restaurant

  has_many :customers, foreign_key: :external_restaurant_code, primary_key: :code

  def initialize(restaurant)
    @restaurant = restaurant
    super(code: restaurant.code)
  end

  def readonly? = true
end

We can now do the following:

@restaurants = Restaurant.from_api.map { |r| WrappedRestaurant.new(r) }

and render our view like this:

<% @restaurants.each do |restaurant| %>
  <article>
    <h2><%= restaurant.name %></h2>
    <hr>
    <h5>Customers list</h5>
    <ul>
    <% restaurant.customers.each do |customer| %>
      <li><%= customer.name %></li>
    <% end %>
    </ul>
  </article>
<% end %>

Which is much more Rails-alike, but we are back to the initial issue:

Customer Load (0.1ms)  SELECT "customers".* FROM "customers" WHERE "customers"."external_restaurant_code" = ?  [["external_restaurant_code", 1]]
  ↳ app/views/restaurants/index.html.erb:7
Customer Load (0.0ms)  SELECT "customers".* FROM "customers" WHERE "customers"."external_restaurant_code" = ?  [["external_restaurant_code", 2]]
  ↳ app/views/restaurants/index.html.erb:7
Customer Load (0.0ms)  SELECT "customers".* FROM "customers" WHERE "customers"."external_restaurant_code" = ?  [["external_restaurant_code", 3]]
  ↳ app/views/restaurants/index.html.erb:7
...

The final step is to use the Rails preloader. This luckily accepts an array, so we can write the following:

ActiveRecord::Associations::Preloader.new(records: @restaurants, associations: [:customers]).call

and our customers association will be preloaded. 🪄

We like to wrap-up everything in a nice method in the wrapper class:

# wrapped_restaurant.rb
def self.wrap(restaurants, preload: [])
    restaurants.map { |restaurant| WrappedRestaurant.new(restaurant) }.tap do |wrapped_restaurants|
      ActiveRecord::Associations::Preloader.new(records: wrapped_restaurants, associations: preload).call if preload.any?
  end
end

You can now preload associations on your Restaurant and keep the logic within the WrappedRestaurant model. The only cons is that you need a "fake" table on the database, nothing that a good old comment cannot solve 😉.

Find the whole code at https://github.com/coorasse/array_preloading_example

DatoCMS with Ruby on Rails ️

Alessandro Rodi — Mon, 04 Apr 2022 19:42:50 +0000

At Renuo we often need an HeadlessCMS in our Ruby On Rails projects, and in the last years, we had a great experience using Dato CMS.

So we decided to release our DatoCMS client open source.

We extracted and isolated the features that we considered most useful and this tutorial will explain you, step-by-step, how to start using it.

DatoCMS setup

We provide a template for a dato backend that you can use for this tutorial:

Use the button above to setup a first DatoCMS project, proceed to the Settings->API Tokens and fetch your ReadOnly API token that we'll use afterwards.

Project setup

The gem expects you to have the following:

a Rails app 😄
turbo
ViewComponents

Only Rails is an actual requirement, but to use 100% of the features provided by the gem, you'll need also view_components and turbo.

Given that you are using Rails >= 7, you can follow these commands

rails new dato-rails-demo --skip-active-record
cd dato-rails-demo

Add to your Gemfile:

gem 'dotenv-rails', groups: [:development, :test]
gem 'view_component'
gem 'dato-rails', require: 'dato'

then run again:

bundle install
echo "DATO_API_TOKEN=<YOUR_DATO_API_TOKEN>" > .env

to install the new libraries and set your Api Token.

Well done. You should be able to simply run bin/rails s and access your application.

Your first query

The provided project contains Homepage. We'll try to fetch it. DatoCMS provides a GraphQL API Explorer that is very useful to generate queries.

We'll start simple with:

# app/services/dato/queries.rb

module Dato
  module Queries
    def homepage_query
      GQLi::DSL.query {
        homepage {
          id
        }
      }
    end
  end
end

where we define a query to fetch the homepage id.

You need to restart your server here, since we added a new services folder.

We should always have tests for our queries. Such a test looks like this:

# test/services/dato/queries_test.rb

require "test_helper"

class DatoQueriesTest < ActiveSupport::TestCase
  include Dato::Queries

  test 'homepage_query' do
    client = Dato::Client.new
    response = client.execute(homepage_query)
    assert_not_nil response.data.homepage.id
  end
end

If you have a green test, it means your are already successfully fetching your homepage from DatoCMS.

Render fetched data

We can now generate a controller and a component and we'll render the data that we just fetched.

rails g controller HomepageController
rails g component Homepage

A component is not mandatory, you can also use standard partials, but it will be necessary to benefit of more advanced features like live reloading afterwards.

# app/components/homepage_component.rb

class HomepageComponent < ViewComponent::Base
  def initialize(data)
    super
    @data = data
  end
end

# app/components/homepage_component.html.erb

<div>This is the homepage id: <%= @data.homepage.id %></div>

# app/controllers/homepage_controller.rb
class HomepageController < ApplicationController
  include Dato::Queries

  def show
    client = Dato::Client.new
    response = client.execute(homepage_query)
    render HomepageComponent.new(response.data)
  end
end

# config/routes.rb

Rails.application.routes.draw do
  root "homepage#show"
end

Structured Text

One of the most important fields that you are going to use on DatoCMS is the Structured Text.
You can easily fetch and render it using dato-rails.

Update your homepage query:

def homepage_query
  GQLi::DSL.query {
    homepage {
      id
      content {
        value
        blocks {
          __typename
          id
          image {
            responsiveImage(imgixParams: {fm: __enum("png")}) {
              ___ Dato::Fragments::ResponsiveImage
            }
          }
        }
      }
    }
  }
end

the code above fetches also the content field that we use in the homepage and we pre-filled in the example.

Here is how you render a Structured Text field:

<div>This is the homepage id: <%=@data.homepage.id %></div>
<%= render Dato::StructuredText.new(@data.homepage.content)  %>

The library provides you a component that you can use to render already everything. You will now see the following:

Custom blocks

In the example above, you see that a block was defined in the blocks library of the example. Such blocks are created by you, so the library cannot provide a component to render them, but you need to create one yourself, with the information available. Read the output of the page for more information and instructions on how to define your component.

We will have:

# app/components/dato/image_block_record.html.erb

<%= render Dato::ResponsiveImage.new(@node.image.responsiveImage)  %>

# app/components/dato/image_block_record.rb

module Dato
  class ImageBlockRecord < Dato::Node
  end
end

you can now simply reload the page, and your block will be rendered correctly with a responsive image.

Customizations

Let's start by adding simple.css to our application.html.erb header so that it looks better:

<link rel="stylesheet" href="https://cdn.simplecss.org/simple.min.css">

If you want to override how a Structured Text node is rendered you have two possibilities:

CSS only
The nodes contain HTML classes that you can use to customize the look and feel of each node by working only with CSS.

.dato-cms-paragraph {
  margin-top: 30px;
}

will add 30px margin top to all the paragraphs nodes.

Override the component
We cannot unfortunately override only the template at the moment. So if you want to customize your node further, you'll need to do the following:

Define a new component. Let's define a new component for the cite block

# app/components/dato/fancy_cite.rb
class Dato::FancyCite < Dato::DastNode
  def initialize(node, root)
    super(node, "blockquote", root)
  end
end

# app/components/dato/fancy_cite.html.erb
<blockquote>
  <% @node.children&.each do |node| %>
    <%= render_node(node) %>
  <% end %>
  <p>
    <cite>– <%= @node.attribution %></cite>
  </p>
</blockquote>

# config/initializers/dato.rb
Dato::Config.overrides = {
  blockquote: 'Dato::FancyCite'
}.with_indifferent_access

Since we added an initializer, restart the server.
This is how you override completely a node.

Preview mode

When using the draft/published feature of Dato CMS, you can fetch the draft version of your model when using the client. We will change the controller as follow:

client = Dato::Client.new(preview: params[:preview].present?)

and enable Draft/Preview for our Homepage model.

Proceed to the Settings of the project, and then models, select the Homepage model, and click Edit Model.

Now you can check how the page looks like when passing the preview parameter in the URL and you perform changes on the Homepage. Head to http://localhost:3000?preview=true.

Real Time Mode

Working on DatoCMS to edit your homepage and going back and forth to your website and hit "refresh" every time, might be tedious and time consuming. Real Time Mode is one of the most interesting features of Dato and you can benefit from it also when using Rails.

The only thing you need to do is to wrap your component into a Dato::Live component and mount the routes.

We'll change the controller action as follows:

def show
  render Dato::Live.new(HomepageComponent, 
                        homepage_query, 
                        preview: params[:preview].present?,
                        live: params[:live].present?)
end

And mount the engine routes:

# config/routes.rb

Rails.application.routes.draw do
  root "homepage#show"

  mount Dato::Engine => '/dato'
end

Head to your page and add the parameters ?live=true&preview=true to the URL and enjoy live reloading.

Rails 7, Bootstrap 5 and importmaps without nodejs

Alessandro Rodi — Wed, 12 Jan 2022 20:01:48 +0000

Our goal: remove nodejs

As many other people in the Rails community, I started setting up brand new Rails 7 projects, and I need to re-learn, at least partially, how to bundle the assets and distribute them.

I never fell in love with TailwindCSS, and therefore I usually setup my Rails apps to use Bootstrap as default.

But what I really like about Rails 7, is the idea of being able to get rid of not only webpack, but of nodejs entirely. The new importmaps feature is really appealing to me and I'd like to use it as long as I don't need to bundle my javascript.

I have to say that esbuild does already a pretty cool job compared to webpack to simplify our lives, and make the process faster, but as long as I don't need bundling, I'd like to not have a package.json file and being dependent on nodejs for my Rails app.

A pure and simple sprockets + importmaps app with no Foreman, no bin/dev, no yarn build --watch stuff.

Bootstrap is made of two parts: CSS and javascript. So I want to use importmaps for the javascript part and rely on sprockets for the CSS compilation from SCSS.

Rails default

By default, Rails 7 provides a new option --css=bootstrap,
but with my great surprise, this option adds both jsbundling-rails, cssbundling-rails, a package.json and esbuild.

Not as expected. Not what I want.

How to configure Rails and Bootstrap without nodejs

Default is not what I want, but I can still reach the goal and here I'll explain how:

Stick with just rails new myapp
This will setup exactly the tools I want: sprockets and importmaps. It will also setup automatically for me stimulus and turbo, which is great because I use them most of the time anyway.

Add bootstrap gem and enable the gem sassc-rails in the Gemfile. This will allow us to compile bootstrap from SCSS without node.

You can simply import Bootstrap styles in app/assets/stylesheets/application.scss:

// here your custom bootstrap variables...
@import "bootstrap";

That's it for the CSS part. Running rails assets:precompile will generate what you want.

For the javascript part we need to do three things:

Precompile the bootstrap.min.js that comes with the gem, by adding to config/initializers/assets.rb

Rails.application.config.assets.precompile += %w( bootstrap.min.js popper.js )

pin the compiled asset in config/importmap.rb:

pin "popper", to: 'popper.js', preload: true
pin "bootstrap", to: 'bootstrap.min.js', preload: true

Include bootstrap in your app/javascript/application.js:

import "popper"
import "bootstrap"

I prefer this approach rather than pinning a CDN because we avoid diverging versions of Bootstrap.

Conclusion

This is all you need to have Bootstrap fully working on Rails 7 without using node.

If you like this guide you can follow me on Twitter.

Mugshot Bot Acquisition: our side of the story

Alessandro Rodi — Wed, 12 Jan 2022 12:56:29 +0000

What an amazing story the one from Joe where he tells us how he built, scaled, and sold MugShotBot in 14 months!

Well, I thought it might be interesting as well how it happened that we decided to buy it :)

So here is our side of the story.

It all starts with Rails

I have worked on Ruby On Rails for 10 years now, and I also became the maintainer of one of the most historical gems, CanCanCan. Ruby On Rails was my bet ten years ago, when I quit my previous job, to switch from Java to Ruby, and to move from Italy to Switzerland at the same time.

Here in Switzerland 🇨🇭 I started working at Renuo, exactly because it was a Web Agency and it was working mainly with Ruby On Rails.

A few years later I bought shares of the company and became one of the three shareholders.

At Renuo we have worked with Rails for 10 years now, it's our main framework to bring our customers' ideas to life.

Meet Joe

And along this journey, I of course started following the Hotwired Dev Newsletter from Joe Masilotti and started following him on Twitter.

As a big fan of Hotwire, I also started creating the Turbo Showcase, where we train ourselves on Turbo and collect all possible components and ideas (by the way, it is open-source, so contributions are welcome!)

I already knew MugShotBot and when Joe decided to sell it, I immediately contacted him to ask a few questions.

The quick decision

The nice thing about being a 20 people company with just three partners, is that you can make decisions very fast. I wrote to my partners right away and organised a meeting a few days later to discuss if we wanted to acquire MugShotBot. I sent them all the necessary information: estimated number of customers, monthly revenues, estimated price on Microacquire, technology stack. Each one of us had to answer the following questions (copy-pasted from our internal slack):

each one of us looks into it and makes a list of possible questions
each one of us also estimates “if I’d buy, I much would I pay for it”
we sit together 1h and compare what we have and get back to him with questions, offers, or a no

A few days later we had the meeting, which lasted way less than one hour. Main points that lead to the decision to make Joe an offer were:

It’s a lovely tool and a smart idea
We can perfectly sell this to our existing Web Agency customers. Many of them will benefit from it
It’s in Ruby On Rails, so we can easily maintain it and improve it. The company costs are at zero for the acquisition of a Ruby On Rails platform
We never acquired a SaaS before so this is going to be a very good chance to learn something

Let’s make him an offer!

The offer

I prepared a single-page offer for Joe, that was following the “no bullshit” principle that usually drives us at our daily work at Renuo. It consisted of the following parts:

What we offer: the price. Right up here. First information. The most important.
Why we want to buy: we know that selling a product is like saying goodbye to your child, so it’s important for Joe to know why we want to acquire the platform
What’s our plan: same as above, explain to him our plans
Who are we: if all the above look good, here is who we are, and what we do

We also highlighted some points that I felt could have been important, like:

10% of our earnings goes to all employees
10% of our earnings goes to charities and open source
We work and invest daily in Ruby On Rails and Open Source and sponsor different projects like cancancan or rubocop

The sale

Joe accepted our offer! It was an amazing day, on the same day I acquired MugShotBot my second child, Pietro, was born! What a day! 🤣

In a few days, we had a one-page contract ready, performed the payment to Joe, and started transferring ownership.

The process was very smooth, Joe was very professional and willing to help us in the process. The whole coordination happened through a single Google Drive document and a few Github issues.

The migration happened in just a few days, and MugShotBot had a new maintainer!

The future of MugShotBot

What will happen now? We started with very simple changes on the platform, where we updated references, email addresses, and logos to point to Renuo.

During these days we are also taking care of updating ruby, rails, and all dependencies, to their latest version. The project was already in very good shape, so this won’t take us long.

We plan to also replace turbolinks with turbo, and webpacker with esbuild. But this is all about the technical part.

We already started reaching out to our existing customers to show them the tool and make proposals about how they can use it. We plan to expand beyond blogs and aim to a wider variety of customers. Some examples?

E-commerce: we believe that an e-commerce platform will benefit a lot from being able to share rich previews of their products, including prices and discounts.

Online courses platforms: the customer likes the idea that when a course is shared, there is a full title, a small description, and the school logo.

Auction Houses: and what about sharing an item in an auction, with a nice picture and the start bidding price and the actual offer?

Escape Rooms, textures, second-hand shops, newspapers, and plugins for existing platforms! We have so many ideas! Let’s see where this will bring us.

If you are interested, have ideas or know anyone who would be interested in the upcoming changes and would like to test it out reach us at info@mugshotbot.com or over Twitter @TheMugShotBot.

Aaaand...to celebrate the acquisition, and since you read until here, we are offering the first month for free to new subscribers until the end of January! 🎉 Use the discount code JANUARY2022ONEOFF during the checkout.

The Turbo Showcase 🚀

Alessandro Rodi — Mon, 08 Mar 2021 08:46:51 +0000

I was getting a bit lost in the documentation of Turbo, so I thought "Why not creating a showcase of what you can actually do with it?"

So here it is: https://turbo-showcase.herokuapp.com/

Currently, we have some examples of Turbo Drive, Turbo Frame and Turbo Stream, and a first combination of what you can achieve with ViewComponent + Turbo + Stimulus.

The Application is fully inspectable and you can enjoy the beautiful Source Code directly in the Browser or on the GitHub repository.

Please feel free to contribute or make requests! At Renuo we will keep adding more and more examples while exploring the possibilities of this new Framework.

Log API requests in Rails

Alessandro Rodi — Wed, 24 Feb 2021 09:39:19 +0000

When exposing or consuming APIs, one of the most important things to remember is to log the calls you perform.

It will not take long until you will have to answer the question "What happened? And why?".

Having a proper log of the API requests you performed or received is the only way to answer these questions.

That's why at Renuo, we extracted rails_api_logger from our projects and made it open source.

rails_api_logger is a library that can be used for logging both inbound requests and outbound requests.

Please read the README file for a full documentation. Here I will sum it up quickly.

Log Inbound Requests

If you are exposing APIs you can log the requests you receive. Use the following Middleware:

config.middleware.insert_before Rails::Rack::Logger, InboundRequestLoggerMiddleware

Check the README for further options.

Log Outbound Requests

Given the following outbound request:

uri = URI('http://example.com/some_path?query=string')
http = Net::HTTP.start(uri.host, uri.port)
request = Net::HTTP::Get.new(uri)
response = http.request(request)

you can log it by doing the following:

uri = URI('http://example.com/some_path?query=string')
http = Net::HTTP.start(uri.host, uri.port)
request = Net::HTTP::Get.new(uri)
response = RailsApiLogger.call(uri, http, request)

The gem comes with a first code example to integrate these logs in RailsAdmin. It the future we will release more and more features.

Head to rails_api_logger on GitHub and give it a ⭐️!

From Turbolinks to Turbo

Alessandro Rodi — Thu, 24 Dec 2020 17:32:22 +0000

I was eager to start using Hotwire in a project that I thought was a perfect fit. Here I will show you what I had to do, to migrate from Turbolinks to Turbo, and keep using Webpacker as main assets bundler.

Remove turbolinks. Add turbo.

Turbo is basically the new version of Turbolinks, so we need to remove the old npm package and add the new one:

yarn remove turbolinks
yarn add @hotwired/turbo

This will replace the package with the new one.

Turbo Drive

Turbo Drive is that part of Turbo that replaces the functionalities provided before by Turbolinks.

We need to remove the previous initialization of turbolinks and initialize turbo instead.
In your application.js (or wherever you initialized Turbolinks), replace

require('turbolinks').start();

with

import Turbo from "@hotwired/turbo"

With this, you will already have Turbo up and running.

Replace old Turbolinks code.

The event turbolinks:load is now called turbo:load. Replace them wherever you are using them.

If you were using data-turbolinks attributes, they are now called data-turbo. You can replace them as well.

Basically you can search for turbolinks within your project and replace it with turbo.

That's it

I started writing this post thinking "This is going to take a while. Such a guide will be useful for sure!". But it ended up being way easier than I thought 😅
In the next posts, I will show you my experiments with Hotwire and Turbo and show how I refactored the code to use the new framework. As of now, Turbo is up and running! 🥳

CanCanCan 3.2.0

Alessandro Rodi — Sat, 12 Dec 2020 21:25:12 +0000

Hi all 👋,
a new version of CanCanCan is out!

Again, we have a minor release but it includes a bunch of very important features, next to support for Rails 6.1.0.

I have opened a sponsorship program, please consider supporting the project if you use CanCanCan. It really helps!

Switching query strategy

Since version 3.0.0 we started changing the way we perform the queries when using accessible_by, in order to be more performant and reliable.

As expected, this new way of performing the queries didn't fit everyone, so in version 3.1.0 we switched from left_joins to subqueries (see relevant PR).

This again didn't make everyone happy 😃 , so we decided, in the version 3.2.0 to allow to configure the preferred query mechanism: left joins or inner queries.

You can now setup:

CanCan.accessible_by_strategy = :subquery # or :left_join

to change it.

Support for Single Table Inheritance

Single Table Inheritance is now supported. Given the following:

class Vehicle < ApplicationRecord

class Car < Vehicle

class Motorbike < Vehicle

You can play with rules by defining:

can :read, Vehicle

and query for:

Vehicle.accessible_by
# or
Motorbike.accessible_by

Here is an example:

can :read, Motorbike

Vehicle.accessible_by(...) # => returns only motorbikes

Check the relevant PR for more examples and note that there are currently some minor issues

Support for associations in rules definition

When using associations in rules definition you always had to use column names. Now, thanks to this PR you can also use the association name.

# previously you had to define:
can :edit, Book, author_id: user.id

# now you can also write:
can :edit, Book, author: user

Enjoy! And to the next one...

Rails API: be nice to your clients

Alessandro Rodi — Tue, 20 Oct 2020 15:49:29 +0000

Since at Renuo we recently worked a lot on implementing APIs for third parties and we received strong compliments and comments like

Oh! Thank god! Finally a well-made API!

I decided to share with you the decisions we took and re-used and refined among three different projects, so you can also be nice to your clients ❤️

Errors

ActiveRecord errors

We read through the jsonapi standard and took out what we consider are the good parts, and removed everything that we didn't need.

That's the structure of our errors when we return them:

{
  "errors": [
    {
      "pointer": "first_name",
      "code": "blank",
      "detail": "First Name can't be blank"
    },
    {
      "pointer": "last_name",
      "code": "blank",
      "detail": "Last Name can't be blank"
    }
  ]
}

This structure has the following advantages:

Gives you the possibility to define multiple errors, and not a single one.
Each error is structured separately and contains:
- a pointer to the place where the error happened,
- a code, readable by a machine, that defines a unique kind of error,
- a detail, that contains text, easy to read by humans, to understand what is wrong.

These errors have all the characteristics necessary to be easily understood, debugged and solved by your clients.

We even return such errors:

{ "pointer": "gender",
  "code": "inclusion",
  "detail": "Gender is not included in the list. Allowed values: male, female, company, other" }

by giving a hint on how to solve the problem in the detail itself.

The controller implementation is as easy as

def create
  if @model.save
    # ...
  else
    render json: { errors: ErrorsMapper.call(@model) }, status: :unprocessable_entity
  end
end

You can find the implementation of the ErrorsMapper in this gist:

Generic errors

How do we keep the same structure when an unexpected error happens? We use a custom middleware that is configured as exceptions_app in application.rb as follows:

# config/application.rb

config.exceptions_app = ->(env) { ActionDispatch::JsonApiPublicExceptions.new(Rails.public_path).call(env) }

here is an example implementation of such middleware:

it has two characteristics:

It hides details in case of 500
It shows the content of the attribute reason in the Exception, if present, allowing us to define custom errors and returning custom messages.
It re-uses the ErrorsMapper seen above to keep the same errors structure.

This is an example of error:

{
  "errors": [
    {
      "status": 500,
      "code": "internal_server_error",
      "detail": "An internal error occurred. We have been notified and we will tackle the problem as soon as possible."
    }
  ]
}

Custom errors

When we need to display a custom error, we can now rely on Rails exceptions_app configuration. If, for example, we want to show an error when the provided api key is missing or wrong we define our custom Exception:

class UnauthorizedError < StandardError
  attr_accessor :reason

  def initialize(reason = nil)
    @reason = reason
  end
end

and we instruct Rails on how to treat this exception:

# config/application.rb

config.action_dispatch.rescue_responses.merge!(
      'UnauthorizedError' => :unauthorized
)

we can then raise an Exception and specify also the reason why we raised it:

raise UnauthorizedError, :missing_api_key if api_key.blank?

raise UnauthorizedError, :wrong_api_key if request.headers['Api-Key'] != ENV['API_KEY']

That's all regarding the errors part. Let's now save some of our clients time 😉

fresh_when

I won't go deep in this blog post regarding the usage of fresh_when, since you can read everything about it in the documentation

I encourage you to use it when possible but do not abuse it and be careful. If, for example, in the response, you return nested resources, you should keep this in consideration when implementing the fresh_when. As always: caching is hard and adds complexity to the system. Do it wisely and document it.

Swagger

Provide a nice and up-to-date swagger documentation of your APIs. The gem rswag is able to publish a nice, clickable, documentation, generated from the swagger, and also to generate the documentation directly from your tests. Give it a try!

Strong Parameters

Last suggestion, with also another bit of code that you might re-use. How do you behave when a client sends an unknown parameter? By using StrongParameters you have, in general, two choices:

You raise an exception

You can configure:

config.action_controller.action_on_unpermitted_parameters = :raise

and every time you receive an unknown parameter, your application will raise an exception. This is an ok behaviour, but it might not suite all the situations, that's also why the default is the next one:

You ignore them

By default, unpermitted_parameters are simply ignored and skipped, but this might lead to a problem when the client sends a non-mandatory field and commits a typo. ouch!
You defined the optional field as zip_code and they sent zip. Since is not mandatory, your API will simply ignore the field and return a nice 201 to the clients, informing them that the record has been saved.

You can be nice to your clients and still return a 201 but also giving them an hint that something might be wrong. We implemented and use the following concern in our controllers:

This concern will add a {"meta": {"hints": [...]}} part to your response, with the list of attributes sent in the request and not accepted by the API. By default, simply including this concern, you will obtain a response like:

{
 "meta": {
  "hints": ["zip is not a valid parameter"]
 }
}

but you can also do one step more and set the list of allowed attributes with:


def create
  model.create(model_params)
end

def model_params
 self.permitted_action_params = %i[zip_code first_name last_name]
 params.require(:model_name).permit(permitted_action_params)
end

and the error will magically be even more detailed. for the customer:

{
 "meta": {
  "hints": ["zip is not a valid parameter. Did you mean zip_code?"]
 }
}

Versioning

There are different ways how you can version your APIs for breaking changes. The solution we adopt at Renuo is the Api-Version header. We went through all other possibilities before deciding that a version header is our first choice. Shortly:

URL versioning sucks, you need to define all new routes every time you need to release a new version, and do weird customizations to redirect v2 endpoints to v1 controllers if they don't have a v2 implementation. Also, your clients will need to invoke new endpoints 🤮.
Versioning via query parameter might work but you don't want to mix "meta" parameters with your actual ones.

We usually implement a very easy method that fetches the current wished version by the client:

def api_version
  request.headers['Api-Version']&.to_i || 1
end

and what might sound weird but is actually really effective, is that at the very beginning, you can simply write something like:

def do_something
  if api_version > 1
    do_something_new
  else
   do_something_old
  end
end

and you will cover already 80% of your needs.

Conclusions

I hope the tips above will help you with your work and to implement better APIs. Since it will happen that I am on the client-side, I hope that the developer on the server-side read this blog post.

If you need to implement APIs or need help with your Rails app get in touch with us at Renuo. We will be happy to help!