Elixir Phoenix PubSub Tutorial

This page is in progress

---

Prerequisites

You should know how to launch a 1 page Live View app that lets the user submit data via a form. The form data should print to the page.

---

This tutorial explains the basics of building a Phoenix PubSub chat app.

What is PubSub?

PubSub is the Phoenix frameworks real time publish/subscribe service. This is an API that lets developers write applications that update in near real time such as chat rooms and multi-player games.

The goal of this writing is to explain how to use the code provided by the PubSub API to build real time applications.

Project Description

The tutorial is divided into three parts, each part building on the completion of the previous one.

• Part 1: We create a two route live view app with each route assigned its own page. The two routes are /send and /receive.

The page at /send contains an html form and form submission code. When data is submitted, the /receive page receives the data, and renders it to its page. The code we write for this exercise uses pubsub functions to connect the two LiveView pages.

When complete, you will have two browser tabs open, one opened to /send and one opened to /receive. The /send route sends data to /receive and you view the update in real time.

• Part 2: We convert the previous app into a single LiveView page that performs both actions on a single route. The end result is the creation of a single page chat application containing real time updates that you view across browser tabs.

• Part 3: We write code to update your single page app to store chat data in a database.

Part 1

Setup

To begin we will start with an new Phoenix instance. In your terminal create a new phoenix app by typing:

mix phx.new app

When the console prompts you to Fetch and install dependencies, choose yes.

When you see the following instructions configure your database, run mix ecto.create.

We are almost there! The following steps are missing:

    $ cd app

Then configure your database in config/dev.exs and run:

    $ mix ecto.create

Start your Phoenix app with:

    $ mix phx.server

You can also run your app inside IEx (Interactive Elixir) as:

    $ iex -S mix phx.server

If you are new to Elixir and are having trouble with database setup, please fix those issues before proceeding with this tutorial.

When the app is created, open your web browser to localhost:4000. The app will launch. If it doesn't, fix the errors before moving forward.

Create Routes

Go to the router and update it as shown.

directory: app/app_web/router.ex

  scope "/", AppWeb do
    pipe_through :browser
    live "/send", SendLive, :home
    live "/receive", ReceiveLive, :home
    get "/", PageController, :home
  end

Create the LiveView Pages

Create a new folder named live in this directory: App/lib/app_web. The end result looks like this: App/lib/app_web/live.

In the live directory, create two files and name them send_live.ex and receive_live.ex.

Edit Send Live.ex

Open the file send_live.ex in your text editor. Paste the following code into it.

defmodule AppWeb.SendLive do
  use AppWeb, :live_view

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

  def handle_event("send", %{"text" => text}, socket) do
    IO.inspect(text)

    Phoenix.PubSub.broadcast(App.PubSub, "message", {:pubsub_transmission, text})

    {:noreply, socket}
  end


  def render(assigns) do
    ~H"""
    <div>
      <h1>Send Message</h1>
      <form phx-submit="send">
        <input type="text" name="text" />
        <button type="submit">Send</button>
      </form>
    </div>
    """
  end
end

Open receive_live.ex and copy the following code to it.

defmodule AppWeb.ReceiveLive do
  use AppWeb, :live_view

  def mount(_params, _session, socket) do
    if connected?(socket) do
      Phoenix.PubSub.subscribe(App.PubSub, "message")
    end

    {:ok, assign(socket, message_item: "")}
  end

  def handle_info({:pubsub_transmission, text}, socket) do
    {:noreply, assign(socket, message_item: text)}
  end

  def render(assigns) do
    ~H"""
    <div>
      <h1>ChatLive</h1>
      <%= @message_item %>
    </div>
    """
  end
end

Launch the server and open up two browser tabs. Set one to /send and the other to /receive

Submit data from /send and view the result on /receive.

Play with the code and explore it. Ensure that it works.

Explanation

Before explaining the code, the following summarizes the important parts applicable to all PubSub applications. Direct your attention to the three functions below. These functions are the main tools that you use when working with the PubSub API and it is important to get familiar with them.

• Phoenix.PubSub.broadcast(App.PubSub, "message", {:pubsub_transmission, text})
• Phoenix.PubSub.subscribe(App.PubSub, "message")
• handle_info({:pubsub_transmission, text}, socket)

For brevity I refer to these as broadcast,subscribe and handle_info.

All PubSub applications are composed of these three functions.

A Simple Mental Model

Mental Models are helpful not because they are 100 percent accurate but because they are tangibly useful. The mental model I use is as follows:

The broadcast and subscribe functions are used to send data from one module to another. You can look at these functions as two ends of a physical cable that connects modules together. The module(s) that transmits the data must contain the broadcast function in it's code, the module(s) receiving the data must contain the subscribe function in it's code.

The receiving module must also contain a handle_info function. This function acts as an event handler that listens for and captures the data.

Phoenix.PubSub.broadcast

1. In SendLive the code Phoenix.PubSub.broadcast is used to broadcast message data. This method takes three arguments.

• The pubsub type
• The topic
• The payload (the data you want to send to all listeners)

The pubsub type is always going to be named your-app dot PubSub (such as App.PubSub) For our purposes you can treat this argument as boiler plate code.

Phoenix.PubSub.broadcast(App.PubSub)

The second argument, called the topic, is a string that represents a connection between the broadcast function and a subscribe function. The topic connects them together.

Phoenix.PubSub.broadcast( App.PubSub, "some-topic-goes-here" )

The third argument is the payload. This can be any data you want to transmit between Live Views.

Phoenix.PubSub.broadcast( App.PubSub, "some-topic-goes-here",%{data: "hello world})

Phoenix.PubSub.subscribe

The first two arguments of subscribe mirror broadcast.

• Phoenix.PubSub. subscribe (App.PubSub, topic)

To use subscribe in a Module, you place it in the mount function.

handle_info

This is a function that is invoked on any "send" event to a process. In our code it is used as a tool to capture the data being subscribed to.