DEV Community: Luiz Cezer

Spice up your LiveView app with a cool loading spinner!

Luiz Cezer — Fri, 15 Dec 2023 15:31:30 +0000

When developing applications, it's common to encounter scenarios where a user's request takes longer than expected. This delay can result from various factors like data transformation, external API calls, or slow database queries.

Fortunately, when constructing a Phoenix app that leverages the capabilities of LiveView, enhancing the user experience by incorporating spinners for such extended requests is a breeze.

The behavior I aim to illustrate is as follows:

The user encounters the "Load Data" button on the interface.
Upon clicking, we simulate an extended request by introducing a :timer.sleep(2000).
While the request loads the necessary data, a spinner becomes visible.

It might seem trivial, but from a user perspective, this serves as valuable feedback, helping them understand that the request might take a couple of seconds to complete.

⚠️ I will not cover the steps to start a new Phoenix LiveView project and setup aspects.

So let's start the coding.

The first step is to implement our LiveView module with the mount/3 function. This mount function will assign values to two variables in the socket posts, which will contain fake data for demonstration purposes, and loading, which will control the state of the loading spinner on the interface.

# lib/spinner_web/live/spinner_live.ex

defmodule SpinnerWeb.SpinnerLive do
  use SpinnerWeb, :live_view

  def mount(_params, _session, socket) do
    socket =
      socket
      |> assign(:posts, [])
      |> assign(:loading, false)

    {:ok, socket}
  end
end

For rendering, I've created an html.heex template at the same directory level.

<!-- lib/spinner_web/live/spinner_live.html.heex -->

<div>
  <button
    phx-click="load-posts"
    class="px-4 py-2 bg-blue-500 text-white rounded-md hover:bg-blue-600 focus:outline-none focus:ring focus:border-blue-300"
  >
    Load Posts
  </button>
</div>
<br /><br />
<%= if @loading do %>
  <svg
    class="animate-spin h-10 w-10 text-blue-500"
    xmlns="http://www.w3.org/2000/svg"
    fill="none"
    viewBox="0 0 24 24"
  >
    <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4">
    </circle>
    <path
      class="opacity-75"
      fill="currentColor"
      d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 6.627 5.373 12 12 12v-4a7.946 7.946 0 01-6-2.709z"
    >
    </path>
  </svg>
<% end %>

In the HTML, the crucial components are:

the button with a phx-click="load-posts" event assigned
the condition using the loading variable; this condition, along with the variable, will control when the spinner must appear.

Well, since I've set a phx-click="load-posts" event on the button, I need to implement that on the backend.

def handle_event("load-posts", _params, socket) do
  socket = assign(socket, :loading, true)

  send(self(), :load_posts)

  {:noreply, socket}
end

Here is where the trick happens, In the first line of the function we set the loading assigned in the socket to be true and spawn a new message by using the function send/3. This function will receive an internal PID and a message, in this case :load_posts. Last but not least we return the {:noreply, socket} with assigns updated, in this case only the loading as true. At this point, the spinner will appear on the interface.

Since we are sending an internal message using send/3 in the handle_event/3 callback, we need to capture that in the LiveView module using a new callback, handle_info/2.

The new callback will primarily handle three steps:

Load the data we are expecting (in this case, a fake list of posts)
Set loading as false to remove the spinner from the interface
Return the new socket data with {:noreply, socket}

def handle_info(:load_posts, socket) do
    # Just to emulate the long-time request
    :timer.sleep(2000)

    socket =
      socket
      |> assign(:posts, get_posts())
      |> assign(:loading, false)

    {:noreply, socket}
  end

  defp get_posts do
    [
      %Spinner.Post{title: "First Title", description: "First Description"},
      %Spinner.Post{title: "Second Title", description: "Second Description"}
    ]
  end

To simulate a case where the request takes a long time to run, I manually add a :timer.sleep/1 that takes 2 seconds to complete.

After these 2 seconds, the spinner will hide, and the list with loaded posts will appear on the interface. Just need to build the code for that on the HTML page.

<%= unless Enum.empty?(@posts) do %>
  <ul class="mt-4">
    <li :for={post <- @posts}>
      <h2 class="text-lg font-bold"><%= post.title %></h2>
      <p class="text-gray-600"><%= post.description %></p>
    </li>
  </ul>
<% end %>

Hope that was helpful!

The whole example can be found here: https://github.com/lcezermf/elixir-playground/tree/master/spinner

Começando com testes unitários nos módulos LiveView

Luiz Cezer — Thu, 26 Oct 2023 16:46:34 +0000

Nos últimos 18 meses, tenho trabalhado integralmente com Elixir & Phoenix, e mais recentemente, tenho tido a chance de trabalhar também com LiveView para algumas interfaces que minha equipe tem desenvolvido.

No início, não estava muito seguro sobre o que estava fazendo ou se meu código estava no lugar apropriado dentro dos módulos LiveView. "Será que deveria manter essa lógica aqui?", "Devo criar funções utilitárias dentro do mesmo módulo LiveView ou devo criar um módulo separado?".

Depois de alguns meses, tenho usado uma regra: tento lidar com os módulos LiveView da mesma forma como lido com os Controllers.

Isso significa que tento manter os módulos o mais limpos possível, apenas com os callbacks necessários, como mount, handle_event, e os assigns de dados para o socket, além de poucas funções privadas.

Prefiro evitar adicionar lógica de negócio do produto dentro desses módulos, pois essa lógica geralmente precisa de mais testes, e testar todos os cenários possíveis diretamente com LiveView pode ser desnecessariamente trabalhoso e não considerar todos os cenários.

Adotando essa abordagem, conseguimos simplificar e tornar mais diretos tanto o código quanto os testes nos módulos LiveView.

Idealmente, ao examinar os testes LiveView, eles devem ser interpretados como se estivessem descrevendo o fluxo que o usuário seguirá ao acessar e interagir com a interface.

Vamos começar com um exemplo simples:

defmodule UrlShortenerWeb.ExampleLive.Index do
  use UrlShortenerWeb, :live_view

  def mount(_params, _session, socket) do
    {:ok, socket}
  end
end

Nesse exemplo de módulo, não há nada de particularmente complexo. Apenas a função mount é utilizada, e na estrutura inicial do projeto, já existem os arquivos example_live/index.ex e example_live/index.html.heex. Dessa forma, não é necessário implementar a função render.

A página HTML contém apenas um texto simples.

<p>Hello Live View</p>

O retorno será esse quando rodar o projeto

Com base nesse código, um jeito simples de testar a funcionalidade seria:

defmodule UrlShortenerWeb.ExampleLive.IndexTest do
  use UrlShortenerWeb.ConnCase, async: true
  import Phoenix.LiveViewTest

  test "must access page and see the initial message", %{conn: conn} do
    {:ok, _view, html} =
      conn
      |> get(Routes.example_index_path(conn, :index))
      |> live()

    assert html =~ "Hello Live View"
  end
end

Neste exemplo, não há necessidade de testar a variável view, portanto, ela foi omitida. Neste caso, o objetivo não é testar a view conectada, que contém o socket e desencadeia alguns comportamentos na página, mas sim o HTML puro.

Rodando isso, esse é o resultado:

Agora irei adicionar um botão na página que ao ser clicado irá remover a mensagem anterior e adicionar uma nova mensagem.

O que eu quero testar agora é o seguinte cenário:

Eu vejo a mensagem padrão
Quero clicar no botão
A mensagem antiga deve desaparecer
O botão deve desaparecer
Uma nova mensagem deve aparecer

Então, como posso testar isso? Uma maneira simples seria a seguinte:

test "must update the message when click the button, hide the old message and button", %{
    conn: conn
  } do
    {:ok, view, html} =
      conn
      |> get(Routes.example_index_path(conn, :index))
      |> live()

    assert html =~ "Hello Live View"
    assert html =~ "Click me"

    view
    |> element("#button-click-me")
    |> render_click()

    assert has_element?(view, "p", "New message")
    refute has_element?(view, "p", "Hello Live View")
    refute has_element?(view, "button", "Click me")
  end

O resultado:

Neste exemplo, acessamos a página da mesma forma que fizemos no exemplo anterior e verificamos o HTML bruto para verificar a existência do botão e do texto padrão (lembre-se de que este teste é baseado no texto da página e não no elemento; portanto, retornará verdadeiro se encontrar esse texto em qualquer lugar da página, portanto, preste atenção ao usá-lo).

Após esta primeira verificação, simulamos o clique no botão direcionando o elemento usando a função element/3 (https://hexdocs.pm/phoenix_live_view/Phoenix.LiveViewTest.html#element/3) e, após selecioná-lo, acionamos o render_click/2 (https://hexdocs.pm/phoenix_live_view/Phoenix.LiveViewTest.html#render_click/2) da mesma forma que um usuário faria, apontando para o botão e clicando.

No final, desejo usar a versão atualizada da página e não a estática inicial. Não utilizo html, em vez disso, utilizo view. Se desejar obter mais detalhes sobre a tupla retornada pela chamada live/2, consulte a documentação.

Bem, este é um exemplo muito simples, mas é o cerne de como testar e gerenciar testes com módulos LiveView. Deve ser simples e basear-se nas ações reais do usuário.

Se você perceber que está fazendo muitas verificações para testar o LiveView, como verificações de lógica de negócios intensas e verificações de socket, talvez deva considerar a possibilidade de estar fazendo algo errado ou adicionando muita lógica dentro do módulo LiveView.

O exemplo completo:

HTML

<%= if @update_messages do %>
  <p>New message</p>
<% else %>
  <p>Hello Live View</p>
<% end %>

<%= unless @update_messages do %>
  <button phx-click="update-messages" id="button-click-me">Click me</button>
<% end %>

LiveView:

defmodule UrlShortenerWeb.ExampleLive.Index do
  use UrlShortenerWeb, :live_view

  def mount(_params, _session, socket) do
    socket = assign(socket, :update_messages, false)

    {:ok, socket}
  end

  def handle_event("update-messages", _params, socket) do
    socket = assign(socket, :update_messages, true)

    {:noreply, socket}
  end
end

Testing:

defmodule UrlShortenerWeb.ExampleLive.IndexTest do
  use UrlShortenerWeb.ConnCase, async: true
  import Phoenix.LiveViewTest

  test "must access page and see the initial message and a button", %{conn: conn} do
    {:ok, _view, html} =
      conn
      |> get(Routes.example_index_path(conn, :index))
      |> live()

    assert html =~ "Hello Live View"
    assert html =~ "Click me"
  end

  test "must update the message when click the button, hide the old message and button", %{
    conn: conn
  } do
    {:ok, view, html} =
      conn
      |> get(Routes.example_index_path(conn, :index))
      |> live()

    assert html =~ "Hello Live View"
    assert html =~ "Click me"

    view
    |> element("#button-click-me")
    |> render_click()

    assert has_element?(view, "p", "New message")
    refute has_element?(view, "p", "Hello Live View")
    refute has_element?(view, "button", "Click me")
  end
end

Start with unit tests on LiveView modules

Luiz Cezer — Wed, 11 Oct 2023 02:32:33 +0000

I have been working with Phoenix and LiveView in a full-time position for around 18 months now, and most recently LiveView started to become something that I do often.

At the beginning I was unsure about my coding and whether I was doing it correctly on the LiveView modules. Should I keep logic there? Should I create utility functions on the LiveView module? Should I make an external module to handle that?

After these months what use as a rule of thumb is: to deal with the LiveView module the same way I deal with a controller. That means I try to keep the module as clean as possible and only with the needed actions, such as mounting, handling callbacks, and assigning data to the socket.

I try to avoid adding business logic related to product on these modules cause this logics usually require more testing and testing it using LiveView can be tricky and not consider all scenarios.

This will make not only the code simple but also the effort to test tend to be very straightforward.

When checking the LiveView module test, your tests should be readable in a way that basically tells you how the user interacts with the page flow.

Let me start with a very simple and basic example:

defmodule UrlShortenerWeb.ExampleLive.Index do
  use UrlShortenerWeb, :live_view

  def mount(_params, _session, socket) do
    {:ok, socket}
  end
end

In this live view module, there is nothing but the mount function and in the project structure, there is the example_live/index.ex and the example_live/index.html.heex so this way I will not need to use the render function.

The HTML has only a message

<p>Hello Live View</p>

Which will return the following when running the project

So, a simple way to test this basic render would be doing a test like this:

defmodule UrlShortenerWeb.ExampleLive.IndexTest do
  use UrlShortenerWeb.ConnCase, async: true
  import Phoenix.LiveViewTest

  test "must access page and see the initial message", %{conn: conn} do
    {:ok, _view, html} =
      conn
      |> get(Routes.example_index_path(conn, :index))
      |> live()

    assert html =~ "Hello Live View"
  end
end

Here I have nothing to do with the view which is why I ignore it, in this case, I do not wanna test the connected view that has the socket and trigger some page behaviors but only the raw HTML generated.

By running it I got:

Now I will add a button on the page that, once clicked will hide the previous message and add a new one.

I would like to test the following scenario

I see the default message
I wanna click on the button
The old message must disappear
The button must disappear
A new message must appear

So how can I test this? A simple way would be like this:

test "must update the message when click the button, hide the old message and button", %{
    conn: conn
  } do
    {:ok, view, html} =
      conn
      |> get(Routes.example_index_path(conn, :index))
      |> live()

    assert html =~ "Hello Live View"
    assert html =~ "Click me"

    view
    |> element("#button-click-me")
    |> render_click()

    assert has_element?(view, "p", "New message")
    refute has_element?(view, "p", "Hello Live View")
    refute has_element?(view, "button", "Click me")
  end

The running result:

In this example we access the page the same way we did in the previous one and check the raw HTML to assert over the button and default text (keep in mind this test is over the text on the page and not the element, so it will return true if finds this text in any place of the page, so pay attention when using it).

After this first check, we simulate the button being clicked by targeting the element using the element/3 https://hexdocs.pm/phoenix_live_view/Phoenix.LiveViewTest.html#element/3 function and after targeting it we trigger the render_click/2 https://hexdocs.pm/phoenix_live_view/Phoenix.LiveViewTest.html#render_click/2, the same way a user would do, by pointing to the button and hitting click.

In the end, I want to use the updated version of the page and not the initial static one, I do not use html, instead I use view. If you wanna know more details about the returned tuple from the live/2 call please check the docs

Well, this is a very tiny example but is the core of how to test and manage testing with LiveView modules, it should be simple and act on top of real user actions.

If you see yourself doing much to test LiveView, like heavy business logic assertions, and socket assertions, maybe consider you possibly doing something wrong or adding too much logic inside the LiveView module.

Full example:

HTML

<%= if @update_messages do %>
  <p>New message</p>
<% else %>
  <p>Hello Live View</p>
<% end %>

<%= unless @update_messages do %>
  <button phx-click="update-messages" id="button-click-me">Click me</button>
<% end %>

LiveView:

defmodule UrlShortenerWeb.ExampleLive.Index do
  use UrlShortenerWeb, :live_view

  def mount(_params, _session, socket) do
    socket = assign(socket, :update_messages, false)

    {:ok, socket}
  end

  def handle_event("update-messages", _params, socket) do
    socket = assign(socket, :update_messages, true)

    {:noreply, socket}
  end
end

Testing:

defmodule UrlShortenerWeb.ExampleLive.IndexTest do
  use UrlShortenerWeb.ConnCase, async: true
  import Phoenix.LiveViewTest

  test "must access page and see the initial message and a button", %{conn: conn} do
    {:ok, _view, html} =
      conn
      |> get(Routes.example_index_path(conn, :index))
      |> live()

    assert html =~ "Hello Live View"
    assert html =~ "Click me"
  end

  test "must update the message when click the button, hide the old message and button", %{
    conn: conn
  } do
    {:ok, view, html} =
      conn
      |> get(Routes.example_index_path(conn, :index))
      |> live()

    assert html =~ "Hello Live View"
    assert html =~ "Click me"

    view
    |> element("#button-click-me")
    |> render_click()

    assert has_element?(view, "p", "New message")
    refute has_element?(view, "p", "Hello Live View")
    refute has_element?(view, "button", "Click me")
  end
end

Tips to improve the design of your Ruby code

Luiz Cezer — Fri, 21 Sep 2018 00:55:14 +0000

Any fool can write code that a computer can understand. Good programmers write code that humans can understand - Martin Fowler.

Why you should care about the design of your code?

As developers, we sometimes tend to think that being productive is related to deliver your task as fast as possible, but for me, that is not the truth.

Be a productive developer is far from just execute your task and deploy your code, is also related to that code quality, how easy to maintain and evolve that feature in the next releases. Because of this, it's important to treat your code, even the minimal changes with attention.

Imagine that you work for a company that has software with a huge source code, too many features, too many teams, different approaches. Today you're working in a determinate feature, next week you focus is another, two weeks from now you return for the first feature... when you work for a big company, this flow is kind of normal.

Always remember, sometimes, you need to prevent your self from your own legacy old.

Avoid hidden structures

The code is hard to understand and hard to maintain
You must avoid use index position directly to get some data from an array

An example to avoid:

class ObscuringReferences
  def initialize(data)
    @data = data
  end

  def calculate
    data.collect do |cell|
      cell[0] + (cell[1] * 2)
    end
  end

  private

  attr_reader :data
end

ObscuringReferences.new([[622, 20], [622, 23], [559, 30], [559, 40]])

The main problem of this code is that it is using the indexes positions of the array to get some information to be used inside de calculate method, but we can not be sure of what are these pieces of information because 0 and 1 are not some meaningful.

How to avoid hidden structures?

Use constants to assign values

class RevealingReferences
  HEIGTH  = 0
  WIDTH = 1

  def initialize(data)
    @data = data
  end

  def calculate
    data.collect do |value|
      value[HEIGTH] + (value[WIDTH] * 2)
    end
  end

  private

  attr_reader :data
end

Assigning the indexes positions in a constant will help to improve the code because now, the indexes are meaningful.

Use a struct to create a class

Shape = Struct.new(:height, :width)

class RevealingReferences
  def initialize(data)
    @data = prepare(data)
  end

  def calculate
    data.collect do |shape|
      shape.height + (shape.width * 2)
    end
  end

  private

  attr_reader :data

  def prepare(data)
    data.collect do |value|
      Shape.new(*value)
    end
  end
end

Another approach is to use Struct data structure to represent the data.

Avoid comparison with regular expressions

Instead of it, assign this regular expression to a meaningful variable name, and use this variable.

  # Instead of using directly the regular expression in the code...
  if string =~ /\d+/
    # ...CODE
  end

  # Assign it to a variable with a meaningful name, and use it.
  is_decimal = /\d+/
  if string =~ is_decimal
    # ...CODE
  end

This simple change could save your time trying to understand what the regular expression is doing.

Avoid directly dependencies

Rather use Composition over Inheritance
Embrace SOLID Principles

Follow the Demeter's Law

Avoid high coupled code
Do not know about the dependencies from a dependency

class Customer
  def state
    address.state.name
  end
end

In the example above, the Customer#state method violates the Demeter's Law, because of the fact that, to access the state.name we first need to the customer to get in contact with your relation with address and then the relationship with address will contact with state.

So we can conclude that the class Customer knows too much about your dependencies. Any error inside the State class can break the Customer, even they are not directly related.

An approach to solve this problem is using Delegators.

Tell don' t Ask!

Tell the objects what to do, do not ask if the can do
Avoid asking an object which is your current state, to perform something based on this answer

class SocialMediaPost
  def send
    SocialMediaPost::API.post(args)
  end

  def connected?
    connected
  end
end

post = SocialMediaPost.new(content: 'Some Message')

if post.connected?
  post.send
end

In the code, above we first ask to the object if it's connected and then based on this we perform an action to post.send.

Now imagine that you need to execute this actions in different points inside your code base and now, you need to add another verification in addition to the current one. Besides, with this code the internal details of the SocialMediaPost are exposed, we know that connected? must be true to perform other methods.

Do not expose the details of an object unnecessarily

class SocialMediaPost
  def send
    SocialMediaPost::API.post(args) if connected?
  end

  private

  def connected?
    connected
  end
end

post = SocialMediaPost.new(content: 'Some Message')
post.send

This approach will not expose the internal details of the class and follows that Demeter's Law.

Conclusions

Boy scout rule: Always leave your code better than you found it
A better design starts on the small changes
You need to write code for humans, not for computers

Design Patterns in Ruby: Strategy Pattern

Luiz Cezer — Fri, 24 Aug 2018 01:18:36 +0000

By definition, the Strategy Pattern defines a family of an algorithm and encapsulate each of them in you own class, that way it will enable that the strategy can be interchanged.

In other words, the pattern allows the main algorithm to vary independently of the clients that use it.

It's very similar to Template Method but it uses a different approach, it prefers to use Composition over Inheritance.

To get a start, imagine that exist a Parser class that is responsible to parse texts to different formats, initially JSON and XML.

class TextParser
  attr_accessor :text, :parser

  def initialize(text, parser)
    @text   = text
    @parser = parser
  end

  def parse
    if parser == :json
      "{ text: #{text} }"
    elsif parser == :xml
      "<text>#{text}</text>"
    end
  end
end

parser_xml = TextParser.new('My Text', :xml)
parser_xml.parse => "<text>My Text</text>"

puts "\n -- \n"

parser_json = TextParser.new('My Text', :json)
parser_json.parse => "{ text: My Text }"

The solution seems to work fine, but uses an if to define which strategy to format the text. It's not a good approach, for the same reasons that I already explained in Template Method post.

If we need to add a new (or many others) parsers? Are we going to add a lot of ifs to check each parser? I won't scale and doesn't conform with Open Closed Principle

We need a better approach, that will allow a flexible way to add new parsers, without the need to change the existent code.

Use the right Strategy to contemplate many parsers

The Template Method, could solve this, but the approach of use Inheritance is not that we want. Inheritance has certain problems:

Make the code very coupled
Does not favor encapsulation

The Strategy Pattern will provide us a nice approach that will avoid the problems above and will conform the Open Closed Principle from SOLID (that I plan to talk in a future post).

At first, to solve the problem and give to the code more flexibility, the TextParser#parse method will only be responsible to delegate the call of parser method to a given class, each of these concrete classes, (JSONParser or XMLParser) will contain their own behavior to implement the parse method and will be injected through the TextParser constructor as a dependency.

class BaseParser
  def parse(text)
    raise 'Must implement!'
  end
end

###

class XMLParser < BaseParser
  def parse(text)
    "<text>#{text}</text>"
  end
end

###

class JSONParser < BaseParser
  def parse(text)
    "{ text: #{text} }"
  end
end

###

class TextParser
  attr_reader :text, :parser

  def initialize(text, parser)
    @text = text
    @parser = parser
  end

  def parse
    puts(parser.parse(text))
  end
end

parser_xml = TextParser.new('My Text', XMLParser.new)
parser_xml.parse => "<text>My Text</text>"

puts "\n -- \n"

parser_json = TextParser.new('My Text', JSONParser.new)
parser_json.parse => "{ text: My Text }"

First of all, I created a BaseParser class with an abstract method that must be implemented by the subclasses, the main intent of BaseParser here, is to "simulate" an interface, and guarantee that all subclasses will be required to implement these interface.

But, as Ruby is a dynamic language that uses Duck Typing as an approach to check if a given message must be executed or not for the receiver, we can get rid of these base class and use only the concrete parsers, the result must be the same.

class XMLParser
  def parse(text)
    "<text>#{text}</text>"
  end
end

###

class JSONParser
  def parse(text)
    "{ text: #{text} }"
  end
end

###

class TextParser
  attr_reader :text, :parser

  def initialize(text, parser)
    @text = text
    @parser = parser
  end

  def parse
    puts(parser.parse(text))
  end
end

parser_xml = TextParser.new('My Text', XMLParser.new)
parser_xml.parse => "<text>My Text</text>"

puts "\n -- \n"

parser_json = TextParser.new('My Text', JSONParser.new)
parser_json.parse => "{ text: My Text }"

With this approach is really simple to add new behaviors, for example, if I need to add a new parser, I just need to create the new parser code that implements the parse method, and everything will continue to work:

class ReverseParser
  def parse(text)
    text.reverse
  end
end

parser_xml = TextParser.new('My Text', ReverseParser.new)
parser_xml.parse => "txeT yM"

Besides, the Strategy Pattern will favor the use of Composition over Inheritance and the code will be in accordance with Open Closed Principle.

Well, that’s it, now you can create how many parsers do you need. This is how to use the Strategy pattern with Ruby.

Check out the full source code.

References

Design Patterns in Ruby: Template Method pattern

Luiz Cezer — Tue, 21 Aug 2018 10:56:39 +0000

By definition, the pattern defines a skeleton of an algorithm, but leave certain parts of this algorithm to be implemented by subclasses. Those subclasses can override the main behavior, without a need to change the main structure of the base algorithm.

In other words, the base class defines a skeleton and subclasses must fill this skeleton with your own implementation.

Deal with different membership plans

Let's say that you need to add a membership feature to your application, and the membership has two different plans, the basic and the premium. Each of these plans has their own title, description and a bunch of benefits.

At first try, you can simply add an if statement to check which type plan will be created, and it seems a good idea.

class Plan
  attr_reader :title, :description, :benefits

  def initialize(kind)
    if kind == :basic
      @title = "I'm the basic plan"
      @description = "My description of basic plan"
      @benefits = ['It is free', 'Access to one account', 'Basic features']
    else
      @title = "I'm the other plan"
      @description = "My description of other plan"
      @benefits = ['No benefits']
    end
  end

  def output
    output = <<-STRING
      Title: #{title}
      Description: #{description}
      Plan benefits: #{benefits.join(', ')}.
    STRING

    puts(output)
  end
end

####

basic = Plan.new(:basic)
basic.output

"""
Title: I'm the basic plan
Description: My description of basic plan
Plan benefits: It is free, Access to one account, Basic features.
"""

other_plan = Plan.new(:other)
other_plan.output

"""
Title: I'm the other plan
Description: My description of other plan
Plan benefits: No benefits.
"""

But, what will happen if we need to add a check for a new plan called premium? If we keep in this approach, the code will look like this:

class Plan
  attr_reader :title, :description, :benefits

  def initialize(kind)
    if kind != :basic
      @title = "I'm the basic plan"
      @description = "My description of basic plan"
      @benefits = ['It is free', 'Access to one account', 'Basic features']
    elsif kind == :premium
      @title = "I'm the premium plan"
      @description = "My description of premium plan"
      @benefits = ['It is paid', 'Access to ten accounts', 'Premium features', 'Access to support']
    else
      @title = "I'm the other plan"
      @description = "My description of other plan"
      @benefits = ['No benefits']
    end
  end

  # ...
end

And what if we need to add a new plan called master premium? Yeah, this approach will not scale well and will deny the code to be flexible and with support many plans.

Using Template Method Pattern to allow multiple plans

As I said before, the main definition of Template Method pattern is to define a skeleton and let the subclasses to fill this skeleton with their own implementation.

So let's define the base class:

class Base
  def title
    raise 'Must implement'
  end

  def description
    raise 'Must implement'
  end

  def benefits
    raise 'Must implement'
  end

  def output
    output = <<-STRING
      Title: #{title}
      Description: #{description}
      Plan benefits: #{benefits}.
    STRING

    puts(output)
  end
end

It's pretty basic, the Base class just define 3 methods title, description and benefits. The output method, contains the skeleton algorithm with the behaviors that subclasses will implement.

The importance of Base class is to define an interface that all subclasses must follow and implement.

Now let's create the subclasses:

class BasicPlan < Base
  def title
    "I'm the basic plan"
  end

  def description
    "My description of basic plan"
  end

  def benefits
    ['It is free', 'Access to one account', 'Basic features'].join(', ')
  end
end

###

class PremiumPlan < Base
  def title
    "I'm the premium plan"
  end

  def description
    "My description of premium plan"
  end

  def benefits
    [
      'It will cost USD 10.00',
      'Access to ten accounts',
      'Premium features',
      'You will receive a gift on your birthday'
    ].join(', ')
  end
end

Each subclass implement your own behavior for each method without worrying about output method, your only
a concern is to implement the hook methods, that will be used inside Base#output.

And what happens if we need to add a new membership plan? Well, it very simple, we just need to create the new class and implement Base class methods.

class AwesomePlan < Base
  def title
    "I'm the awesome plan"
  end

  def description
    "My description of awesome plan"
  end

  def benefits
    [
      'It will cost USD 1,000.00',
      'Access to a hundread accounts',
      'Awesome features',
      'You will receive a gift on your birthday',
    ].join(', ')
  end
end

###

"""
Title: I'm the awesome plan
Description: My description of awesome plan
Plan benefits: It will cost USD 1,000.00, Access to a hundread accounts, Awesome features, You will receive a gift on your birthday.
"""

Well, this is it, this is how to use the Template Method pattern with Ruby.