DEV Community: Florian Arens

Building a Table of Contents Component for a Phoenix Blog

Florian Arens — Sun, 04 Aug 2024 00:00:00 +0000

1. Introduction
2. Steps
       2.1. Configure MDEx
       2.2. Parse and convert headings
       2.3. Build the table of contents component
       2.4. How to use the component
3. Conclusion

This article shows how to parse MDEx-generated HTML into a nested data structure that is used to build a table of contents component for a Phoenix blog.

Introduction

In this article, we are going to build a table of contents component that can be used in blogs or other markdown based pages. The table of contents component will display a link to each section of your content that allows users to quickly navigate through the content.

We assume that you have set up a Phoenix project and are using the MDEx markdown parser to render markdown content. We will configure MDEx to include IDs and anchor links for headings in the generated HTML that we can use to build the table of contents component. If you are not using MDEx, you can still follow along, but you will need to make some adjustments to the code to make it work with your markdown parser.

Steps

Configure MDEx

The first step is to configure the MDEx markdown parser to include IDs and anchor links for headings in the generated HTML. By default, MDEx does not include any IDs and or additional anchor links. To enable this feature, we need to set the header_ids option in the extensions keyword list when calling the MDEx.to_html function. This tells the MDEx markdown parser to include IDs and anchor links for headings in the generated HTML.

MDEx.to_html(body, extension: [header_ids: ""])

In the code snippet above, we pass an empty string to the header_ids option. The string will be used as a prefix for the generated IDs. We do not necessarily need a prefix, but it can be useful to avoid conflicts with other IDs on the page.

You can see a list of all available extension in the comrak documentation as MDEx uses Rust’s comrak crate under the hood.

We can write a simple test to verify that the generated HTML includes the IDs and anchor links for headings:

use ExUnit.Case

test "MDEx includes IDs and anchor links" do
  assert MDEx.to_html("## Introduction\n", extension: [header_ids: ""]) ==
            "\"#introduction\" aria-hidden=\"true\" class=\"anchor\" id=\"introduction\"></a>Introduction</h2>\n"
end

As you can see, the generated HTML includes an anchor link with the ID introduction for the heading ## Introduction.

Parse and convert headings

The next step is to parse the generated HTML, extract the headings from it and transform them into a suitable data structure that we can use to build the table of contents component. We will use the Floki library for this. From the README: “Floki is a simple HTML parser that enables search for nodes using CSS selectors.”

We will write a function that takes the generated HTML content as input, parses the headings, and returns a list of headings with labels, hrefs and subheadings.

defp parse_headings(content) do
  content
  |> Floki.parse_fragment!()
  |> Enum.reduce([], fn
    {"h2", _class, child} = el, acc ->
      acc ++ [%{label: Floki.text(el), href: get_href(child), childs: []}]

    {"h3", _class, child} = el, acc ->
      List.update_at(acc, -1, fn %{childs: subs} = h2 ->
        %{h2 | childs: subs ++ [%{label: Floki.text(el), href: get_href(child), childs: []}]}
      end)

    _other, acc ->
      acc
  end)
end

def get_href(heading_element) do
  attr = heading_element |> Floki.find("a") |> Floki.attribute("href")

  case attr do
    [] -> nil
    [href | _] -> href
  end
end

The parse_headings/1 function takes the generated HTML content as input. Since we are dealing with a string we first use the Floki.parse_fragment! function to parse the string into a Floki html_tree() data structure. We then use Enum.reduce/3 to iterate over the html tree. We check if the element is an h2 or h3 element and extract the label and href. The label is the text content of the heading element and the href is generated using the get_href/1 helper function (the get_href/1 function searches for the anchor link in the heading element and returns the corresponding href attribute). If the element is an h3 element, we need to add it as a child of the last h2 element. This results in a nested data structure.

We can validate the function by writing a test that also demonstrates the resulting data structure:

use ExUnit.Case

test "parse_headings" do
  headings =
    """
    ## Section 1

    ### Subsection 1.1

    ### Subsection 1.2

    ## Section 2
    """
    |> MDEx.to_html(extension: [header_ids: ""])
    |> parse_headings()

  expected = [
    %{
      label: "Section 1",
      childs: [
        %{label: "Subsection 1.1", childs: [], href: "#subsection-11"},
        %{label: "Subsection 1.2", childs: [], href: "#subsection-12"}
      ],
      href: "#section-1"
    },
    %{label: "Section 2", childs: [], href: "#section-2"}
  ]

  assert headings = expected
end

As you can see, the parse_headings/1 function returns a list of headings with labels, hrefs and subheadings. This data structure is suitable for building the table of contents component because it represents the hierarchy of the headings in the content.

Note that we only parse h2 and h3 elements in this example. You can extend the function to include deeper heading levels if needed.

Build the table of contents component

The last step is to build the actual table of contents component. It takes the list of parsed headings from the previous steps and an optional list of classes. Since we are using daisyUI in our Phoenix project, we can use the menu class to make the table of contents look like a sidebar menu by default (see daisyUI menu component). We also add some other default classes. You can customize the component to fit your design.

The toc/1 component renders an unordered list with list items and a link for each heading. If the current heading has child headings, the toc component is called recursively with them as input. This creates a nested HTML list structure that represents the headings data structure in the UI.

@doc """
Renders a table of contents from a list of headings.
"""
attr :headings, :list, required: true
attr :class, :string, default: "menu w-56 p-0 opacity-60"

def toc(assigns) do
  ~H"""
  <ul class={@class}>
    <li :for={%{label: label, href: href, childs: childs} <- @headings}>
      <.link href={href}>
        <%= label %>
      </.link>
      <.toc :if={childs != []} headings={childs} class={nil} />
    </li>
  </ul>
  """
end

How to use the component

We are now ready to use the component in our layout. On my blog, I only show the table of contents on larger screens, so I can place it next to the main content. I also made it sticky so that it stays visible while scrolling. Here is an example of how I placed the component in my layout:

<div class="relative">
  <div class="absolute top-16 bottom-16 -left-14 w-10 text-xs">
    <div class="sticky top-6 hidden xl:block">
      <.toc headings={@article.heading_links} />
    </div>
  </div>

</div>

The above code uses absolute positioning to place the table of contents on the left side of the main content. It is only visible on larger screens (xl:block) and is sticky so that it stays visible while scrolling. To not stick to the top of the page, we use the top-6 class to save some space.

Conclusion

In this article, we configured the Elixir MDEx markdown parser to include IDs and anchor links for headings in the generated HTML. We then parsed the generated HTML into a nested data structure we can pass to a table of contents component we built. This component renders a list of links to the headings in the content, creating a table of contents that allows users to quickly navigate through the content.

How to integrate Tabler Icons into your Phoenix project

Florian Arens — Thu, 20 Jun 2024 00:00:00 +0000

1. Introduction
2. Tracking the Tabler Icons source repository
3. Updating the Tailwind CSS config
3.1. Reading the SVG files
3.2. Generating the CSS classes
4. Remove width and height from the SVG
5. Build an icon component
6. Conclusion
7. Credits

Tabler Icons is one of the most popular icon libraries. This article shows how to integrate the icon library into Phoenix projects. We will track the Tabler Icons source repository using Mix and use the Tailwind CSS plugin feature to create an icon component.

Introduction

In almost every web application you will need icons to represent different actions or states. There are many icon libraries available, but one of the most popular is Tabler Icons. Tabler Icons is a set of over 5000 free, MIT-licensed, high quality SVG icons. The icons are maintained by Paweł Kuna and come in two versions: filled and outlined.

This article shows how to integrate Tabler Icons into an existing Phoenix project.

Tracking the Tabler Icons source repository

The first step is to track the Tabler Icons source repository using Mix. This will allow us to easily update the icons in our project when new icons are added or existing icons are updated.

To track the Tabler Icons source repository, we need to add the following to the deps function in the mix.exs file:

{:tabler_icons, github: "tabler/tabler-icons", sparse: "icons", app: false, compile: false}

This will add the Tabler Icons repository as a dependency to our project. The sparse option is used to only download the icons directory from the repository. We set app to false because we don't want to read the app file. We also set compile to false because we don't want to compile the icons. We just want to download the icons so we can use them later in our Tailwind CSS config.

If you have not seen the above options before, you can find a detailed explanation of them in the Mix documentation.

After adding the dependency, we need to run mix deps.get to download the icons from the Tabler Icons repository. The icons will be downloaded to the deps/tabler_icons/icons directory.

Updating the Tailwind CSS config

Next, we need to update thetailwind.config.js. We create a custom plugin that generates the CSS classes for the icons.

Reading the SVG files

The first step is to make the plugin read the SVG files from the deps/tabler_icons/icons directory.

module.exports = {
  // ...
  plugins: [
    plugin(function () {
      const iconsDir = path.join(__dirname, "../deps/tabler_icons/icons")
      const values = {}
      const icons = [
        ["", "/outline"],
        ["-filled", "/filled"],
      ]
      icons.forEach(([suffix, dir]) => {
        fs.readdirSync(path.join(iconsDir, dir)).forEach(file => {
          const name = path.basename(file, ".svg") + suffix
          values[name] = { name, fullPath: path.join(iconsDir, dir, file) }
        })
      })
    })
  ]
}

The above code reads the SVG files from the deps/tabler_icons/icons directory and creates an object with the icon names and their full paths. This way, we can easily reference the icons later.

The values object will look like this:

{
  "user": { name: "user", fullPath: "/path/to/deps/tabler_icons/icons/outline/user.svg" },
  "user-filled": { name: "user-filled", fullPath: "/path/to/deps/tabler_icons/icons/filled/book.svg" },
  // ...
}

We append the suffix -filled to filled icon names to distinguish between the filled and outlined versions of the icons. Since outline should be the default, we don't append any suffix to the outline icons.

Generating the CSS classes

Next, we need to get the plugin to generate the CSS classes for the icons. We want to add the CSS for elements that contain a hero-* class. For example, if we have an element with a hero-user class, we want to add the CSS for the user icon. To do this, we use the matchComponent function provided by Tailwind CSS.

module.exports = {
  // ...
  plugins: [
    plugin(function ({ matchComponents, theme }) {
      const values = {}
      // read icons and add to values object

      matchComponents({
        "tabler": ({ name, fullPath }) => {
          const content = fs.readFileSync(fullPath).toString().replace(/\r?\n|\r/g, "")

          return {
            [`--tabler-${name}`]: `url('data:image/svg+xml;utf8,${content}')`,
            "-webkit-mask": `var(--tabler-${name})`,
            "mask": `var(--tabler-${name})`,
            "mask-repeat": "no-repeat",
            "background-color": "currentColor",
            "vertical-align": "middle",
            "display": "inline-block",
            "width": theme("spacing.5"),
            "height": theme("spacing.5")
          }
        }
      }, { values })
    })
  ]
}

This code matches items with the tabler-*. It extracts the name and full path of the icon from the values object created earlier. It then reads the contents of the SVG file and generates the CSS classes for the icon. The CSS classes set the icon as the element's background image and set the width and height of the element to theme("spacing.5"). This way, we can easily control the size of the icons using Tailwind's CSS spacing utilities.

Remove width and height from the SVG

The icons provided by the Tabler Icons library have width and height attributes set in the SVG files. We need to remove these attributes so that we can control the size of the icons using Tailwind CSS.

We already have a regex that removes all line breaks and carriage returns from the path string. We can extend this to also remove the width and height attributes from the SVG files.

const content = fs.readFileSync(fullPath).toString()
  .replace(/\r?\n|\r/g, "")
  .replace(/width="[^"]*"/, "")
  .replace(/height="[^"]*"/, "");

The final plugin code will look like this:

module.exports = {
  // ...
  plugins: [
    plugin(function ({ matchComponents, theme }) {
      const iconsDir = path.join(__dirname, "../deps/tabler_icons/icons")
      const values = {}
      const icons = [
        ["", "/outline"],
        ["-filled", "/filled"],
      ]
      icons.forEach(([suffix, dir]) => {
        fs.readdirSync(path.join(iconsDir, dir)).forEach(file => {
          const name = path.basename(file, ".svg") + suffix
          values[name] = { name, fullPath: path.join(iconsDir, dir, file) }
        })
      })
      matchComponents({
        "tabler": ({ name, fullPath }) => {
          const content = fs.readFileSync(fullPath).toString()
            .replace(/\r?\n|\r/g, "")
            .replace(/width="[^"]*"/, "")
            .replace(/height="[^"]*"/, "");

          return {
            [`--tabler-${name}`]: `url('data:image/svg+xml;utf8,${content}')`,
            "-webkit-mask": `var(--tabler-${name})`,
            "mask": `var(--tabler-${name})`,
            "mask-repeat": "no-repeat",
            "background-color": "currentColor",
            "vertical-align": "middle",
            "display": "inline-block",
            "width": theme("spacing.5"),
            "height": theme("spacing.5")
          }
        }
      }, { values })
    })
  ]
}

Build an icon component

Now that we have the CSS classes for the icons ready, we can create an icon component that makes it easy to use the icons in our Phoenix project.

defmodule MyAppWeb.CoreComponents do
  use Phoenix.Component

  attr :name, :string, required: true
  attr :class, :string, default: nil

  def icon(%{name: "tabler-" <> _} = assigns) do
    ~H"""
    <span class={[@name, @class]} />
    """
  end
end

This component takes the name of the icon as an argument and renders a span element with the icon name as a class. We also allow the user to pass additional classes.

We can use this component in our templates like this:

<.icon name="hero-user" class="bg-blue-600" />

Tailwind CSS will generate the appropriate CSS classes for the icon based on the plugin we built in the previous step, and the icon will be displayed with a blue background.

Conclusion

In this article, we have shown how to integrate Tabler Icons into a Phoenix project. We tracked the Tabler Icons source repository using Mix, built an icon component that makes it easy to use the icons in markup, and used the Tailwind CSS plugin feature to add the appropriate CSS.

Credits

I would like to credit the Phoenix team for the inspiration for this article. They are already using the same approach to integrate Heroicons into Phoenix projects. I just adapted it to work with Tabler Icons.

Collaboration in Git: A comparison of different workflows

Florian Arens — Wed, 24 Apr 2024 00:00:00 +0000

1. Introduction
2. The Problem
3. What is a Git workflow?
4. Why is a Git workflow Important?
5. Git workflows
       5.1. Centralized workflow
       5.2. Gitflow workflow
       5.3. Feature branch workflow
       5.4. Trunk-based workflow
       5.5. Forking workflow
6. Which Git workflow to choose?
7. Conclusion

Choosing the right Git workflow is crucial for the success of a project. This article breaks down the nuances of different Git workflows and provides insight into the pros and cons of each.

Introduction

Git is a distributed version control system that is mainly used in software development to track changes in source code during the development process. It was created by by Linus Torvalds in 2005 to manage the Linux kernel development. Git is a free and open-source tool that is used by millions of developers worldwide. Altough it is mainly used in software development, Git can be used to track changes in any set of files.

No technology has revolutionized the way developers work together quite like Git. The stack overflow developer survey in 2022 showed that almost 94% of developers use Git as their version control system. Git has become the de facto standard for version control systems. Thats why it is important to understand how to work with Git and how to collaborate with other developers.

This articles assumes that you are already familiar with Git and have a basic understanding of how it works. If you are new to Git, you can learn more about it in the official Git documentation.

The Problem

When working on a software project with multiple developers, it is important to have a system in place to manage changes to the code base. Without a version control system, developers would not be able to collaborate properly. A version control system like Git makes it easy to track changes to the codebase, collaborate with other developers, and manage the development process.

However, working with Git can be challenging, especially when working with multiple developers on the same codebase. Git only provides a set of tools for developers to use, but it does not provide guidelines on how to use them and how to work together. This is where Git workflows come in.

What is a Git workflow?

A Git workflow is a set of rules that define how developers work with Git. It defines how changes are made, reviewed, and integrated into the codebase. There are many different Git workflows, but the most popular are the Gitflow, feature branch, and forking workflow.

Why is a Git workflow Important?

You may be wondering why you need a Git workflow at all. Why not just let developers decide how they want to work with Git?

The answer is simple: the Git workflow used in a project has an impact on the success of the project. The reason is that a suitable Git workflow helps developers collaborate more effectively, reduces the risk of conflicts and errors, and makes it easier to work together.

The prerequisite is that the Git workflow is well-defined, followed by all developers, and meets the needs of the project. This is why it is important to choose the right Git workflow for your project. In the following sections, we will provide an overview of the most popular Git workflows and help you choose the right one for your project.

Git workflows

Centralized workflow

Propably the simplest Git workflow is the centralized workflow. In this workflow, there is a single central repository that all developers work from. Developers clone the repository to their local machine, make changes, and push them back to the central repository. This workflow is suitable for small teams or projects where there is no need for complex branching and merging. In addition, it is easy to set up and understand, making it ideal for beginners or teams that are new to Git. Especially for teams that are used to working with a centralized version control system like Subversion, the centralized workflow is a good starting point.

However, the centralized workflow has some limitations. As there are no branches, conflicts will occur frequently when multiple developers are involved. Therefore, the centralized workflow is not suitable for large beginner teams.

A typical centralized workflow looks like this:

Clone the central repository to your local machine.
Make changes to the code.
Push the changes to the central repository.

Gitflow workflow

Probably the most popular Git workflow is the Gitflow workflow. It was created by Vincent Driessen in 2010 and has since become the standard for many software development teams. The Gitflow workflow is based on the idea of using branches to manage the development process. The workflow itself defines a set of branches and rules for how to use them. Gitflow provides a clear structure for how changes are made, reviewed, and integrated into the code base.

A list of branches along with their purpose in the Gitflow workflow:

main branch: Contains the latest stable version of the code base. Used for production releases.
develop branch: Contains the latest development version of the code base. Used for integrating new features and bug fixes.
Feature branches: Created from the develop branch and used to develop new features.
Release branches: Created from the develop branch and used to prepare a new release.
Hotfix branches: Created from the main branch and used to fix critical bugs in the production code.

In Gitflow, the team works with multiple branches. This allows developers to work on different features and bug fixes at the same time, without interfering with each other. In addition, code reviews can be done on the feature branches before they are merged into the develop branch. This helps to catch bugs and errors early in the development process. In addition, it is possible to fix critical bugs in the production code without having to include new features that are still in development because of the separation of the main and develop branches.

However, the Gitflow workflow is more complex than the centralized workflow and requires more discipline from developers. It is important that all developers follow the rules of the workflow and use the correct branches for their changes. For small teams or projects with simple requirements, the Gitflow workflow may be too complex.

Also, the Gitflow workflow can lead to long-lived branches, which can make it difficult to merge changes back into the main codebase. This can lead to conflicts and errors, especially if the branches are not kept up to date with the latest changes in the codebase. Long-lived branches also make it difficult to perform continuous integration and continuous deployment, because changes are not merged back into the main codebase frequently. Typically, you do not perform continuous integration and continuous deployment using the Gitflow workflow.

A typical Gitflow workflow looks like this:

Create a new branch from the develop branch to start working on a new feature.
Make changes to the code in the new branch.
When the feature is complete, merge the branch into the develop branch.
Once the develop branch is stable, create a new release branch from the develop branch.
Make any necessary changes to the code on the release branch.
When the release is complete, merge the release branch into the main and develop branches.
If a critical bug is found in the production code, create a new hotfix branch from the main branch, and merge it back into the main and develop branches.

Due to the complexity and overhead of the Gitflow workflow, it is usually not suitable for web development projects that often require continuous integration and continuous deployment. The Gitflow workflow is more appropriate for projects with long release cycles, such as desktop applications or embedded systems.

However, because of its popularity, Gitflow is used by many software development teams for all kinds of projects.

Read more about the Gitflow workflow in the original blog post by Vincent Driessen.

Feature branch workflow

A more modern workflow that is a mix between the centralized and Gitflow workflow is the feature branch workflow. In this workflow, every new change begins by creating a new branch. There are no strict rules about how to use branches like in Gitflow, but the general idea is to create a new branch for every new feature or bugfix. Each branch is created based on the latest version of the codebase and is used to make changes. When the changes are complete, the branch is merged back into the main codebase.

Typically, feature branches are short-lived. This reduces the risk of conflicts and bugs. Most teams also perform code reviews on feature branches before merging them back into the main codebase.

A typical Gitflow workflow looks like this

Create a new branch based on the latest version of the codebase.
Make changes to the code on the new branch.
When the changes are complete, merge the branch back into the main codebase.

The feature Branch workflow is suitable for various types of projects, as it provides a good balance between the simplicity of the centralized workflow and the complexity of the Gitflow workflow, but it may not be suitable for projects that require continuous integration and deployment because changes are not always merged back into the main codebase quickly, even though the goal is to keep branches as short-lived as possible.

Trunk-based workflow

In the trunk-based workflow, there is a single main branch called trunk (or simply main), which contains the latest version of the code base. Developers clone the trunk to their local machine, make changes, and push them back to the trunk. This workflow is very similar to the centralized workflow, but while the centralized workflow is often used by beginners, the trunk-based workflow is used by more experienced developers and can also be used by larger teams. In addition, the trunk-based workflow defines a set of rules and guidelines for how to work with the trunk and how to develop new features or bug fixes.

As only one branch is used in the trunk-based workflow, it requires responsibility and discipline from the teamn. It is important that each developer frequently commits to the trunk and keep changes as small as possible. The test coverage should be high to ensure that changes do not introduce bugs or errors as they are integrated directly into the trunk.

The trunk-based workflow is often used in projects that require continuous integration and deployment. The deployment process is often automated and each push to the trunk triggers a build and deployment process. When working on new features, the workflow often requires the use of feature flags to hide unfinished features. This allows developers to work on new features without affecting the production environment.

The trunk-based workflow also forces developers to perform code reviews synchronously, because changes are pushed directly to the trunk and changes can not be reviewed later on in a dedicated pull request like in other workflows. This enforces collaboration and communication between team members and prevents long-lived pull requests that wait for review.

A typical trunk-based workflow looks like this:

Clone the trunk to your local machine.
Make changes to the code.
Push the changes to the trunk.

The main benefit of the trunk-based workflow is that it eliminates the merge hell that can occur when working with multiple long-lived branches that need to be merged into the main branch. This significantly reduces release cycle time. It also encourages collaboration and communication between team members and ensures that changes are integrated into the codebase frequently. However, the trunk-based workflow requires discipline and responsibility from the team and may not be suitable for beginners or teams that are new to Git.

Forking workflow

The forking workflow is mainly used in open source projects or projects with external contributors. In this workflow, there is a central repository that contains the main codebase and each contributor has their own fork of the repository. Contributors clone their fork to their local machine, make changes and commit back to their fork. When the changes are complete, they create a pull request to merge the changes back into the main codebase.

A typical forking workflow looks like this:

Fork the central repository to your own account.
Clone your fork to your local machine.
Make changes to the code.
Push the changes to your fork.
Create a pull request to merge the changes into the main / original codebase.

The forking workflow provides a clear separation between the main codebase and contributions from external contributors. This makes it easy to restrict access to the main repository. Maintainers do not need to grant access to the main repository, since contributors can work on their own fork. This is why the forking workflow is often used in open source projects, where many external contributors are involved.

Which Git workflow to choose?

Choosing the right Git workflow for your project depends on many factors, such as the size of your team, the complexity of your project, and your development process. Here are some guidelines to help you choose the right Git workflow for your project:

For small teams or projects with simple requirements, the centralized workflow is a good place to start. It is easy to set up and understand, making it ideal for beginners or teams new to Git. Especially for teams that are used to working with a centralized version control system before.
For medium to large teams or projects with complex requirements and long release cycles, the Gitflow workflow is suitable. It provides a clear structure for how changes are made, reviewed, and integrated into the code base.
For all kind of projects that does not require "real" CI/CD, the feature branch workflow may a good choice. It provides a good balance between the simplicity of the centralized workflow and the complexity of the Gitflow workflow.
For more experienced developers and teams, the trunk-based workflow may be appropriate. It reduces release cycle time, allows real continuous integration and deployment, and can greatly increase development speed.
For open source projects or projects with external contributors, the forking workflow is the way to go. It provides a clear separation between the main codebase and contributions from external contributors.

It is important to note that above guidelines and workflows from this article are not set in stone. Of course, you may customize workflows or even think of new workflows that better suit your project. They key is to find a workflow that works for your team and your project.

Conclusion

In this article, we have provided an overview of the most popular Git workflows. We have discussed the pros and cons of each workflow and provided some guidelines to choose the right Git workflow for your project. Let me know what workflow you use in your project.

Display the number of online users in real-time using Phoenix Presence

Florian Arens — Sat, 18 Feb 2023 20:00:00 +0000

Adding real-time functionality is often a challenge, but in Phoenix we already have built-in functionality to make our application live. We dive into how Phoenix Presence can be used to build a real-time user count.

1. Introduction
2. The Problem
3. Background
       3.1. LiveView Lifecycle
       3.2. Phoenix PubSub
       3.3. Phoenix Presence
4. Real-time User Count
5. Conclusion

Introduction

I recently redesigned my website and published the first article on my blog. Along with the redesign, I added a live reader counter to blog posts that show the number of active sessions in real time. As soon as you open the article page, the counter increases for each user currently online on that page and it decreases as soon as a session ends.

In this post, we will dive into how Phoenix Presence was used to build this feature in a few lines of code. I will also provide some background on the Phoenix LiveView lifecycle and the real-time publisher/subscriber service in Phoenix (called PubSub).

The Problem

Adding real-time functionality to a web application for the first time is usually a challenge. While there are many packages and services available today that provide APIs and infrastructure for real-time functionality, you almost always have to rely on third-party applications.

You can decide whether to use a managed infrastructure, for example provided by Pusher, Ably or LiveBlocks or use a self-hosted solution (e.g. built with Socket.io). In either case, you will need to integrate the services or libraries into your application and learn how to use them. This process can be time-consuming and frustrating. In addition, manged services can be expensive and self-hosted solutions require maintenance.

In Phoenix, we already have built-in functionality and infrastructure to make our application live. This is not surprising when we talk about building our application with Live Views.

You might say that some applications don't necessarily need real-time functionality, but in my opinion, value can be added to almost any application by providing real-time functionality. Even for a small blog that serves static articles, it is an eye-catcher to show the number of live readers. Adding real-time functionality to an application makes it more interactive and therefore more fun to use!

Background

LiveView Lifecycle

To understand why our LiveViews in Phoenix are live by design, we first need to understand the Phoenix LiveView Lifecycle.

When you send an HTTP request to a LiveView, you receive a server-rendered HTML response. After the initial HTML response, a Websocket connection is established between the client and the LiveView. When the connection is established successfully, the view turns into a stateful view that can handle events and push updates to the client. In other words, a LiveView is a long-lived process that can handle multiple requests and events over time. The process is killed when the client leaves the page.

Elixir, and therefore LiveView processes, are lightweight and can handle many concurrent connections, making it possible to have one LiveView process for each client. Each LiveView contains stateful values called socket assigns. The assigns are maintained on the server side and are used to render dynamic content in the view. Whenever the assigns change, the LiveView sends a message to the client to update the DOM (minimal JavaScript code that comes with LiveView takes care of the DOM updates for us). Clients can also send events to the LiveView process, which can be used to update the assigns and thus the view. It is important to note that only the necessary parts of the DOM are updated, which makes the application very efficient. LiveView only patches the DOM with the necessary changes.

The following example shows how to create a simple counter with LiveView. The counter is incremented by clicking a button and the value is displayed in the view.

defmodule MyAppeWeb.CounterLive.Index do
  use MyAppeWeb, :live_view

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

  def render(assigns) do
    ~H"""
    <p>Counter: <%= @counter %></p>
    <button phx-click="increment">Increment</button>
    """
  end

  def handle_event("increment", _params, socket) do
    {:noreply, assign(socket, counter: socket.assigns.counter + 1)}
  end
end

First the counter is set to 0 in the mount/3 function. The render/1 function is used to render the view and the handle_event/3 function is used to handle the event when the button is clicked. The handle_event/3 function increments the counter and updates the assigns. The LiveView process then sends a message to the client to update the DOM with the new counter value.

This architecture allows us to minimize the JavaScript code in our application while still being able to build interactive applications. Because of the Websocket connection, the LiveView process can push updates to the client, which makes it easy to add real-time functionality to our application. We do not need to fetch data from the server at regular intervals. Instead, the server can push updates to the client as the data changes.

The LiveView lifecycle makes it possible to build efficient real-time applications. The LiveView process can push updates to the client, and the client can send events to the LiveView process. If you want to learn more about the LiveView Lifecycle, I recommend reading the Phoenix LiveView Documentation.

Phoenix PubSub

Phoenix PubSub is a real-time publisher/subscriber service that is used to broadcast messages to multiple subscribers. A subscriber can be a process and therefore can be a LiveView. If you have created a Phoenix application with the official generator, you probably have a PubSub server in your application.

If not, you can add the PubSub server to your application by adding the following line to your supervision tree:

# lib/my_app/application.ex
children = [
  ...
  {Phoenix.PubSub, name: MyApp.PubSub}
]

You can now use the PubSub server to broadcast messages to subscribers. The following example shows how to subscribe to a topic and broadcast a message to that topic:

Phoenix.PubSub.subscribe(MyApp.PubSub, "topic")
Phoenix.PubSub.broadcast(MyApp.PubSub, "topic", "Hello")

For more information about Phoenix PubSub and a list of all available features, see the Phoenix PubSub documentation.

Phoenix Presence

Phoenix Presence is built on top of Phoenix PubSub and is used to track the presence of users in a channel or process along with some metadata. The metadata can be used to track the state of the user, for example, if the user is typing or online. Phoenix Presence also provides us with features like handling diffs of join and leave events in real time or fetching the current presence state. As we learned in the previous section, LiveViews are long-lived processes. This makes it possible to use Phoenix Presence to track the presence of users in a LiveView.

Phoenix Presence is easy to integrate into our application. We just need to add a presence module to our application and add it to our supervision tree. The following example shows how a presence module could look:

defmodule MyAppWeb.Presence do
  use Phoenix.Presence,
    otp_app: :my_app,
    pubsub_server: MyApp.PubSub
end

We use the Phoenix.Presence module to define our presence module. We need to specify the otp_app and the pubsub_server. The otp_app is the name of our application and the pubsub_server is the PubSub server we are using in our application. We then add the presence module to our supervision tree:

children = [
  ...
  {Phoenix.PubSub, name: MyApp.PubSub},
  MyAppWeb.Presence,
  MyAppWeb.Endpoint
]

Make sure it is defined after the Phoenix.PubSub process in the supervision tree and before the MyAppWeb.Endpoint process.

That's it! We now have Phoenix Presence integrated into our application.

We can now use Phoenix Presence features like listing all presences in a process, getting the current presence state, or handling diffs of join and leave events in real time.

You can learn more about Phoenix Presence in the Phoenix Presence documentation. There you will find a list of all the features and how to use them.

Real-time User Count

Let us return to live reader counting and combine the knowledge we gained in the previous sections to build the feature. We will use Phoenix Presence to track the presence of users in a LiveView.

To prepare, we need to add Phoenix Presence to our application. We will create a presence module that uses Phoenix.Presence and add it to our supervision tree. We will use the same code as shown in the Phoenix Presence section of this article.

Since Phoenix Presence uses Phoenix PubSub under the hood, we subscribe to a topic in our LiveView process that will be used to broadcast the presence events. Since we want to have a live reader count for each article, we need to subscribe to a unique topic for each article. We can use the article id as the topic along with a prefix to make the topic unique.

Let's define a function that returns the topic for a given article:

defp topic(%{id: id} = _article) do
  "article:#{id}"
end

We can now subscribe to the topic in the mount/3 function of our LiveView process. We want to do this after the websocket connection between the client and LiveView has been established and not during the first render. We can use the connected?/1 function to check this. We also need to tell Phoenix Presence that we would like to track the presence of the user in the topic. We use the track/3 function to do this.

if connected?(socket) do
  Phoenix.PubSub.subscribe(MyApp.PubSub, topic(article))
  {:ok, _ref} = Presence.track(self(), topic(article), "live_reading", %{})
end

We pass the topic and PubSub name to the subscribe/2 function. The track/3 function takes the process, the topic, a key, and metadata. The key is used to identify the presence and the metadata can be used to track the state of the user. In our case, we only need to track the presence of the user, so we use an empty map as metadata.

We now have the user's presence tracked in the topic. We can use the list/1 function to retrieve the presences in a given topic. We write a function that lists the presences for the topic of a given article and counts the number of presences under the given key. The returned value is the live readers count for the article, or more generally the number of online users on the page.

defp get_live_reading_count(article) do
  case Presence.list(topic(article)) do
    %{"live_reading" => %{metas: list}} -> Enum.count(list)
    _other -> 0
  end
end

We assign this value to the socket and use it to represent the number of live readers in the view.

live_reading = get_live_reading_count(article)

socket = assign(socket, live_reading: live_reading)

Now the live reader count can be displayed in the view. We now need to handle presence diffs to update the live reader count in real time. We use the handle_info/2 function to listen for the presence_diff event sent by Phoenix Presence when a user joins or leaves.

In the event handler, we call the get_live_reading_count/1 function and update the assigns with the new live reader count.

def handle_info(%Broadcast{event: "presence_diff"} = _event, socket) do
  live_reading = get_live_reading_count(socket.assigns.article)

  {:noreply, assign(socket, :live_reading, live_reading)}
end

That's it! We now have a live reader counter for each article. The live reader count is updated in real time when a user enters or leaves the article page. You can fetch the value from the assigns in the view and display it wherever you want.

The full code for the live counter might look like this:

defmodule MyAppWeb.BlogLive.Show do
  use MyAppWeb, :live_view

  alias Phoenix.Socket.Broadcast
  alias MyApp.Blog
  alias MyAppWeb.Presence

  @presence_key "live_reading"

  @impl Phoenix.LiveView
  def mount(%{"slug" => slug} = _params, _session, socket) do
    article = MyApp.Blog.get_article_by_slug(slug)
    live_reading = get_live_reading_count(article)

    if connected?(socket) do
      Phoenix.PubSub.subscribe(MyApp.PubSub, topic(article))
      {:ok, _ref} = Presence.track(self(), topic(article), @presence_key, %{})
    end

    socket =
      socket
      |> assign(:article, article)
      |> assign(:live_reading, live_reading)

    {:ok, socket}
  end

  @impl Phoenix.LiveView
  def handle_info(%Broadcast{event: "presence_diff"} = _event, socket) do
    live_reading = get_live_reading_count(socket.assigns.article)

    {:noreply, assign(socket, :live_reading, live_reading)}
  end

  defp get_live_reading_count(article) do
    case Presence.list(topic(article)) do
      %{@presence_key => %{metas: list}} -> Enum.count(list)
      _other -> 0
    end
  end

  defp topic(%{id: id} = _article), do: "article:#{id}"
end

You are welcome to use the code as a starting point for your own online user count indicator. You can also use the code to add other real-time features to your application.

Conclusion

This article showed how to create a live reader count with Phoenix LiveView and Phoenix Presence in just a few lines of code. We also learned about the Phoenix LiveView Lifecycle and how it makes it easy to add real-time functionality to our application.