Phoenix Live View, The Beginner Guide
Table of Contents
[TOC]
This guide assumes you have Elixir and Phoenix installed. So go do that if you haven't.
If you don't know what LiveView is, basically a wrapper around websocket to transfer data and update the page seamlessly. I suggest you watch Chris McCord talk about it on ElixirConf EU 2019 to understand more.
Initial Setup
Now, let's dive into it. First you need to create Phoenix project.
```
$ mix phx.new random_cat --no-ecto
```
Answer Y to Fetch and install dependencies? question.
We're passing --no-ecto flag because what we're going to create doesn't have anything to do
with database.
To make sure it's working, run the server, and then go open http://localhost:4000 on your browser. You should see "Welcome to Phoenix!" message along with some links.
```
$ cd random_cat
$ mix phx.server
```
The page is controlled by index function inside lib/controllers/page_controller.ex.
Now, we need to install LiveView. To do that, open
mix.exs and add {:phoenix_live_view, "~> 0.3.1"} to deps, and while we're at it,
add httposion as well. It's HTTP client library, and we need that for our small project:
```
defp deps do
[
{:phoenix, "~> 1.4.9"},
{:phoenix_pubsub, "~> 1.1"},
{:phoenix_html, "~> 2.11"},
{:phoenix_live_view, "~> 0.3.1"},
{:phoenix_live_reload, "~> 1.2", only: :dev},
{:httpoison, "~> 1.6.1"},
{:gettext, "~> 0.11"},
{:jason, "~> 1.0"},
{:plug_cowboy, "~> 2.0"}
]
end
```
Stop the server and install the added library by running mix deps.get.
Then you can re-run the server using mix phx.server.
LiveView
This is where the fun starts. First define the /live endpoint.
Open lib/random_cat_web/endpoint.ex and add socket "/live", Phoenix.LiveView.Socket:
```
defmodule RandomCatWeb.Endpoint do
use Phoenix.Endpoint, otp_app: :random_cat
socket "/live", Phoenix.LiveView.Socket
...
end
```
Then configure the signing salt, open config/config.exs, and add live_view: [signing_salt: ...]:
```
config :random_cat, RandomCatWeb.Endpoint,
url: [host: "localhost"],
secret_key_base: "abc",
render_errors: [view: RandomCatWeb.ErrorView, accepts: ~w(html json)],
pubsub: [name: RandomCat.PubSub, adapter: Phoenix.PubSub.PG2],
live_view: [signing_salt: "xyz"]
```
You can generate the salt by running mix phx.gen.secret 32.
Next we need to initialize the socket connection via javascript.
First add phoenix_live_view npm dependencies:
```
{
"dependencies": {
"phoenix": "file:../../../deps/phoenix",
"phoenix_html": "file:../../../deps/phoenix_html",
"phoenix_live_view": "file:../../../deps/phoenix_live_view"
}
}
```
And run npm install --prefix assets.
Then Open assets/js/app.js and insert these lines:
```
import {Socket} from "phoenix"
import LiveSocket from "phoenix_live_view"
let liveSocket = new LiveSocket("/live", Socket)
liveSocket.connect()
```
For now, that's all javascript we have to write in order to make things work.
Now we create the actual LiveView. Create new file inside lib/random_cat_web/live
(you need to create live directory first), called cat_live.ex. Insert this code block:
```
defmodule RandomCatWeb.CatLive do
use Phoenix.LiveView
def render(assigns) do
~L"""
<img src="<%= @url %>">
"""
end
def mount(%{}, socket) do
fallback = "http://lorempixel.com/g/500/300/animals/"
case HTTPoison.get("http://aws.random.cat/meow") do
{:ok, %HTTPoison.Response{body: body}} ->
case Jason.decode(body) do
{:ok, %{"file" => url}} ->
{:ok, assign(socket, :url, url)}
{:error, _} ->
{:ok, assign(socket, :url, fallback)}
end
{:error, _} ->
{:ok, assign(socket, :url, fallback)}
end
end
end
```
We'll explore this part by part. Basically LiveView needs to have 2 functions in order
for it to works, render and mount. First part is the render.
```
def render(assigns) do
~L"""
<img src="<%= @url %>">
"""
end
```
This part defines how you will render the live view content. This could be a whole page, or just
part of a page. We could also use template file for this(we'll convert to template file later).
The ~L part is the sigil
for live view template.
```
def mount(%{}, socket) do
fallback = "http://lorempixel.com/g/500/300/animals/"
case HTTPoison.get("http://aws.random.cat/meow") do
{:ok, %HTTPoison.Response{body: body}} ->
case Jason.decode(body) do
{:ok, %{"file" => url}} ->
{:ok, assign(socket, :url, url)}
{:error, _} ->
{:ok, assign(socket, :url, fallback)}
end
{:error, _} ->
{:ok, assign(socket, :url, fallback)}
end
end
```
The next one is mount. Mount is accessed when the LiveView is rendered for the first time.
Our mount is simple. It's trying to fetch data from http://aws.random.cat/meow, and use
fallback it the data is invalid, or the fetch is failed. If we get the data sucessfully,
we show the cat image.
The last part is add the LiveView to the router. Open lib/random_cat_web/router.ex, andd add live "/cat", CatLive to scope "/" so:
```
scope "/", RandomCatWeb do
pipe_through :browser
get "/", PageController, :index
live "/cat", CatLive
end
```
Now everything is ready, restart the server just to be sure, then open http://localhost:4000/cat The cat image should show up.
Right now, the only way to update the image it to do the page refresh. Next, we're going to change that and add a button to update the image without refreshing the page.
LiveView Event Handling
The way event being handled is you can call single function from the page. It's done via socket, but you don't need to do anything with that. All we need is use the provided binding on our element and let LiveView do the rest.
First, let's update the template. We add a button that will trigger function on the server,
using phx-click binding. Your render function should be similiar to this:
```
def render(assigns) do
~L"""
<div>
<img src="<%= @url %>">
</div>
<button phx-click="moar">moar!</button>
"""
end
```
Next we create the function that will handle that click event. What we want to do is to
update the image everytime the button is clicked. To do that, we refactor the mount function,
so we could re-use the HTTP call routine. Your mount should be like this:
```
def mount(_session, socket) do
{:ok, assign(socket, :url, get_cat_url())}
end
```
And for the get_cat_url function, it will always return url.
```
defp get_cat_url() do
fallback = "http://lorempixel.com/g/500/300/animals/"
case HTTPoison.get("http://aws.random.cat/meow") do
{:ok, %HTTPoison.Response{body: body}} ->
case Jason.decode(body) do
{:ok, %{"file" => url}} ->
url
{:error, _} ->
fallback
end
{:error, _} ->
fallback
end
end
```
Last, in function to handle moar event, we assign :url to new url from get_cat_url
everytime the function is called.
```
def handle_event("moar", _values, socket) do
{:noreply, assign(socket, :url, get_cat_url())}
end
```
Your whole cat_live.ex content should be like this:
```
defmodule RandomCatWeb.CatLive do
use Phoenix.LiveView
def render(assigns) do
~L"""
<div>
<img src="<%= @url %>">
</div>
<button phx-click="moar">moar!</button>
"""
end
def mount(_session, socket) do
{:ok, assign(socket, :url, get_cat_url())}
end
def handle_event("moar", _values, socket) do
{:noreply, assign(socket, :url, get_cat_url())}
end
defp get_cat_url() do
fallback = "http://lorempixel.com/g/500/300/animals/"
case HTTPoison.get("http://aws.random.cat/meow") do
{:ok, %HTTPoison.Response{body: body}} ->
case Jason.decode(body) do
{:ok, %{"file" => url}} ->
url
{:error, _} ->
fallback
end
{:error, _} ->
fallback
end
end
end
```
Now go restart the server and try clicking the button. Now we could update the image without restarting the page. Remember we only write 4 lines of javascript so far.
Hooks
The last thing that I want to show is how to bind more javascript code. In our case,
we want to be able to maybe show loading message after the button is clicked. We could
use phx-hook for that.
First, update your app.js to this:
```
let Hooks = {};
Hooks.MoarButton = {
mounted() {
this.el.addEventListener('click', e => {
this.el.innerText = 'Loading ...';
this.el.disabled = true;
});
}
};
let liveSocket = new LiveSocket('/live', Socket, { hooks: Hooks });
```
This hook will set the button to Loading ..., and disable it once the element is clicked.
To use the hook, update the button in the template to use phx-hook:
```
...
<button phx-click="moar" phx-hook="MoarButton">moar!</button>
...
```
So there the very basic way to setup LiveView. If you want to know more, you could check the documentation on hexdocs.pm. I hope that helps, and if you see anything wrong or invalid, please tweet me @kriwil. Thank you for reading!