This page is in progress

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

The goal of this writing is to clarify code used to build PubSub applications in Phoenix. Using the PubSub feature of Phoenix is not difficult and this tutorial could be less verbose, I wrote it this way to give the reader the most context with the least amount of code as possible. My goal is to ensure that you understand how to integrate PubSub basics into any Phoenix app.

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

Project Description

Part 1: We create a two route liveview 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 of this exercise is the creation of a single page chat application where data updates are viewable in real time 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.

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 will look 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 render(assigns) do
    ~H"""
    <div>
      <h1>Send Connection</h1>

     
    </div>
    """
  end
end

Edit Receive_Live.ex

Open the file named receive_live.ex and paste the following code into it:


defmodule AppWeb.ReceiveLive do
  use AppWeb, :live_view

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

  def render(assigns) do
    ~H"""
    <div>
      <h1>Receive Connection</h1>

   
    </div>
    """
  end
end

Validate Your Work

Ensure the code you wrote has no errors by running the server and checking each route.

mix phx.server

Go to:

localhost:4000/send

localhost:4000/receive

The pages should load without error.

Creating a Form and its Event Handler

The first step to send data via a form is to create the form and write an event handler to listen and receive data from the form. You should have enough prerequisite knowledge to know how to do this. If you don't read this tutorial before you proceed:

Forms and Event Handlers in Elixir Phoenix

Update the send_live.ex to reflect the code below:



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
    {: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

Ensure it works by submitting form data. In the terminal console you will see the output.

Before We Add the PubSub Code

You are now going to perform these actions.

1. Add code designed to broadcast a change

2. Add code designed to subscribe to that change

Both of these code pieces act similar to event handlers/listeners in that they listen to events that the developer designates and performs an action in response.

Both broadcast code and subscribe code can be placed in different parts of your codebase depending on your goal.

For this exercise you write the broadcast code to your SendLive module and write the subscribe code to your ReceiveLive module.

Add the PubSub Broadcast Code to SendLive Module



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
    AppWeb.Endpoint.broadcast(topic, "message", text) # Broadcast
    {:noreply, socket}
  end
  

  defp topic do #Topic
    "chat"
  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

Add the PubSub Subscribe Code to ReceiveLive Module



defmodule AppWeb.ReceiveLive do
  use AppWeb, :live_view
  
  def mount(_params, _session, socket) do


    if connected?(socket) do
      AppWeb.Endpoint.subscribe(topic)     # PupSub Subscribe
    end

    {:ok, assign(socket, messages: "")}
  end
  
  def handle_info(%{event: "message", payload: message}, socket) do  # Handle Ifno is needed
    IO.inspect message
    {:noreply, assign(socket, messages: message)}
  end
  

  defp topic do  # Topic
    "chat"
  end

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


    </div>

     """
  end
  
end

PubSub Code Result and Explanation

Open the app in to broser tabs and set one to /send and one to /receive. Submit a form in /send and you will see the result in /receive

SendLive PubSub Code Explained

The SendLive module contains this code:

 AppWeb.Endpoint.broadcast(topic, "message", text)

In all default Phoenix applications the PubSub code is in the module named Endpoint.

NameOfApp.Endpoint

The broadcast function has three arguments. In our examples they are named topic, "message" and text.

 AppWeb.Endpoint.broadcast(topic, "message", text)

The first argument is the name of the topic. The topic is what connects the broadcast and the subscriber. You can have many broadcasters and subscribers all with different topics.

A topic is a string that acts as an ID to connect the broadcast and subscriber. In our example the topic is "chat" and is referenced in a private function named topic.


  defp topic do #Topic
    "chat"
  end

The code will work if you place the string in the broadcast function directly, like this:

AppWeb.Endpoint.broadcast("chat", "message", text)

Elixir Phoenix PubSub Tutorial

Contents