DEV Community: Lubien

Free Beginner Friendly LiveView Course in English and Portuguese

Lubien — Tue, 16 Apr 2024 09:40:40 +0000

https://adopt-liveview.lubien.dev

I've been working on writing beginner friendly lessons aimed at teaching LiveView, Phoenix and Elixir to those who might not have even prior Elixir experience.

I've previously helped many folks joining in on this framework so I've wrote it in a hand-holding way for newcomers to feel safe when first learning things. It's a bottom-up course so most of time I'm teaching how things are built before diving in on the niceties of generators.

This project is also open source and built with LiveView too:

https://github.com/adopt-liveview/adopt-liveview

Huge thanks to https://ultimatemercer.com/ (open to work) and https://tanukesensei.github.io/ (open to work) who helped me building this so I could focus on writing content!

Sidenote: if you're into Portuguese LiveView content I've been also posting videos in 🇧🇷 at my youtube channel from time to time:

https://www.youtube.com/@lubiendev

Listing matches for users

Lubien — Mon, 05 Feb 2024 19:37:11 +0000

Last post we had to use IEx to see matches being inserted on the database. This time we are going to do a little bit of frontend and at the same time learn a bit more about Ecto and LiveView streams. Our goal is to make the user page list all their matches.

Reviewing some Ecto concepts

First of all, we need a method that lists matches for a certain user. Since we established last time that the Ranking module will handle those, let's go there.

@doc """
Returns the list of matches a certain user participated.

## Examples

    iex> list_matches_for_user(1)
    [%Match{}, ...]

"""
def list_matches_for_user(user_id) do
  Match
  |> or_where(user_a_id: ^user_id)
  |> or_where(user_b_id: ^user_id)
  |> order_by(desc: :id)
  |> Repo.all()
end

This is a simple Ecto query that starts as broad as "list me all the matches" but uses or_where/3 to list only when either user_a_id or user_b_id is equal to user_id. Not only that we use order_by/3 to sort descendingly so the latest matches can shine first.

Back to the tables

Back when we needed to show a list of users we opted to use the <.table> component. We will do so again. Go to user_live/show.ex.

defmodule ChampionsWeb.UserLive.Show do
  # some stuff here

  @impl true
  def handle_params(%{"id" => id}, _session, socket) do
    user = Accounts.get_user!(id)
+   matches = Ranking.list_matches_for_user(user.id)
+
    {:noreply,
     socket
     |> assign(:page_title, "Showing user #{user.email}")
-    |> assign(:user, user)}
+    |> assign(:user, user)
+    |> stream(:matches, matches)
+   }
  end

  # some stuff here
  @impl true
  def render(assigns) do
    ~H"""
    <.header>
      User <%= @user.id %>
      <:subtitle>This is a player on this app.</:subtitle>
    </.header>

    <.list>
      <:item title="Email"><%= @user.email %></:item>
      <:item title="Points"><span data-points><%= @user.points %></span></:item>
    </.list>

    <div :if={@current_user && @current_user.id != @user.id} class="my-4">
      <.button type="button" phx-click="concede_loss">I lost to this person</.button>
      <.button type="button" phx-click="concede_draw">Declare draw match</.button>
    </div>
+
+   <.table
+     id="matches"
+     rows={@streams.matches}
+   >
+     <:col :let={{_id, match}} label="User A"><%= match.user_a_id %></:col>
+     <:col :let={{_id, match}} label="User B"><%= match.user_b_id %></:col>
+     <:col :let={{_id, match}} label="Points"><%= match.result %></:col>
+   </.table>

    <.back navigate={~p"/users"}>Back to users</.back>
    """
  end
end

Now there you go, another boring table! Wait, it's even more boring because it doesn't even show user names! Let's fix that. I'd like to take this opportunity to teach you how NOT to do this and after show you a good way of doing this.

How NOT to load nested information on Phoenix LiveView

We could just use Accounts.get_user! inside our render function and just get users when rendering.

<.table
  id="matches"
  rows={@streams.matches}
>
- <:col :let={{_id, match}} label="User A"><%= match.user_a_id %></:col>
+ <:col :let={{_id, match}} label="User A"><%= Accounts.get_user!(match.user_a_id).email %></:col>
- <:col :let={{_id, match}} label="User B"><%= match.user_b_id %></:col>
+ <:col :let={{_id, match}} label="User B"><%= Accounts.get_user!(match.user_b_id).email %></:col>
  <:col :let={{_id, match}} label="Points"><%= match.result %></:col>
</.table>

The above works but have you ever heard of the N+1 problem? That's bad. We are basically querying once for the matches then for each match two more queries, one for each user. Here's how my terminal logs appear after rendering that.

↳ ChampionsWeb.UserLive.Show.handle_params/3, at: lib/champions_web/live/user_live/show.ex:9
[debug] QUERY OK source="matches" db=5.0ms idle=374.9ms
SELECT m0."id", m0."result", m0."user_a_id", m0."user_b_id", m0."inserted_at", m0."updated_at" FROM "matches" AS m0 WHERE (m0."user_a_id" = $1) OR (m0."user_b_id" = $2) ORDER BY m0."id" DESC [2, 2]
↳ ChampionsWeb.UserLive.Show.handle_params/3, at: lib/champions_web/live/user_live/show.ex:10
[debug] Replied in 11ms
[debug] QUERY OK source="users" db=2.4ms idle=372.6ms
SELECT u0."id", u0."email", u0."hashed_password", u0."confirmed_at", u0."points", u0."inserted_at", u0."updated_at" FROM "users" AS u0 WHERE (u0."id" = $1) [1]
↳ anonymous fn/3 in ChampionsWeb.UserLive.Show.render/1, at: lib/champions_web/live/user_live/show.ex:66
[debug] QUERY OK source="users" db=3.3ms decode=0.7ms idle=369.5ms
SELECT u0."id", u0."email", u0."hashed_password", u0."confirmed_at", u0."points", u0."inserted_at", u0."updated_at" FROM "users" AS u0 WHERE (u0."id" = $1) [2]
↳ anonymous fn/3 in ChampionsWeb.UserLive.Show.render/1, at: lib/champions_web/live/user_live/show.ex:67
[debug] QUERY OK source="users" db=4.1ms idle=365.0ms
SELECT u0."id", u0."email", u0."hashed_password", u0."confirmed_at", u0."points", u0."inserted_at", u0."updated_at" FROM "users" AS u0 WHERE (u0."id" = $1) [1]
...

To add fuel to the problem, every single time our render function is called we would run those queries again. So if something triggers an update in the template, say the points changed, we'd run a ton of load on our database. Don't do queries inside your HEEx!

How to do load nested information on Phoenix LiveView Ecto

Ecto, just like any other good ORM, already knows that models can have relations to each other. We can teach it that a Match model belongs to each User model by simply changing the following:

schema "matches" do
  field :result, Ecto.Enum, values: [:winner_a, :winner_b, :draw]
- field :user_a_id, :integer
+ belongs_to :user_a, Champions.Accounts.User
- field :user_b_id, :integer
+ belongs_to :user_b, Champions.Accounts.User

  timestamps()
end

Implicetely when you use Ecto's belongs_to/3 you get two fields in your model. If you say belongs_to: :user_a, Champions.Accounts.User a user_a_id field will be created with :integer type and also a :user_a field will be created which will store User when we preload it. Preloading relations in Ecto is quite easy. Go to your Rankings context and add this line:

def list_matches_for_user(user_id) do
  Match
  |> or_where(user_a_id: ^user_id)
  |> or_where(user_b_id: ^user_id)
  |> order_by(desc: :id)
+ |> preload([:user_a, :user_b])
  |> Repo.all()
end

Now all matches will come with both fields pre-populated. We can use them like this:

<.table
  id="matches"
  rows={@streams.matches}
>
- <:col :let={{_id, match}} label="User A"><%= match.user_a_id %></:col>
+ <:col :let={{_id, match}} label="User A"><%= match.user_a.email %></:col>
- <:col :let={{_id, match}} label="User B"><%= match.user_b_id %></:col>
+ <:col :let={{_id, match}} label="User B"><%= match.user_b.email %></:col>
  <:col :let={{_id, match}} label="Points"><%= match.result %></:col>
</.table>

That's magic, ladies and gentleman. Our table is slightly less boring. One thing it doesn't do though is add matches as soon as someone clicks on the button. Let's do that.

Learning a little bit more about Phoenix LiveView Streams

Whenever we run the functions that concede loss or declare a draw match we receive back the updated users so we can update our UI. We should do the same for the match that was just created so we can put that into our UI. Let's get back to the Ranking context.

  @doc """
  Adds 3 points to the winning user

  ## Examples

      iex> concede_loss_to(%User{points: 0})
-     {:ok, %User{points: 3}}
+     {:ok, %User{points: 3}, %Match{}}

  """
  def concede_loss_to(loser, winner) do
-   {:ok, _match} = create_match(%{
+   {:ok, match} = create_match(%{
      user_a_id: loser.id,
      user_b_id: winner.id,
      result: :winner_b
    })
-   increment_user_points(winner, 3)
+   {:ok, updated_user} = increment_user_points(winner, 3)
+   {:ok, updated_user, Repo.preload(match, [:user_a, :user_b])}
  end

  @doc """
  Adds 1 point to each user

  ## Examples

      iex> declare_draw_match(%User{points: 0}, %User{points: 0})
-     {:ok, %User{points: 1}, %User{points: 1}}
+     {:ok, %User{points: 1}, %User{points: 1}, %Match{}}

  """
  def declare_draw_match(user_a, user_b) do
-   {:ok, _match} = create_match(%{
+   {:ok, match} = create_match(%{
      user_a_id: user_a.id,
      user_b_id: user_b.id,
      result: :draw
    })
    {:ok, updated_user_a} = increment_user_points(user_a, 1)
    {:ok, updated_user_b} = increment_user_points(user_b, 1)
-   {:ok, updated_user_a, updated_user_b}
+   {:ok, updated_user_a, updated_user_b, Repo.preload(match, [:user_a, :user_b])}
  end

As you can see both functions now also send a %Match{} as the last element on the tuple. Now let's update our usages in the UI. It's very important to notice that we also preloaded the associations after creating the matches so our UI will have that info otherwise it's going to error later on.

  def handle_event("concede_loss", _value, %{assigns: %{current_user: current_user, user: user}} = socket) do
-   {:ok, updated_user} = Ranking.concede_loss_to(current_user, user)
-   {:noreply, assign(socket, :user, updated_user)}
+   {:ok, updated_user, match} = Ranking.concede_loss_to(current_user, user)
+
+   {:noreply,
+     socket
+     |> assign(:user, updated_user)
+     |> stream_insert(:matches, match, at: 0)
+   }
  end

  def handle_event("concede_draw", _value, %{assigns: %{current_user: current_user, user: user}} = socket) do
-   {:ok, updated_my_user, updated_user} = Ranking.declare_draw_match(current_user, user)
+   {:ok, updated_my_user, updated_user, match} = Ranking.declare_draw_match(current_user, user)
    {:noreply,
      socket
      |> assign(:user, updated_user)
      |> assign(:current_user, updated_my_user)
+     |> stream_insert(:matches, match, at: 0)
    }
  end

Now we have a new function here. Meet stream_insert/4. Remember that whenever we defined tables we used stream(socket, :stream_name, elements)? Streams are an efficient way of handling large collections of data in LiveView without storing them in memory.

When the user opens the LiveView we render the matches stream once and leave it at that. Now that we have a new match we use stream_insert using the same stream name and saying that the position should be 0 so this is effectively a prepend. If you're wondering why we prepend to the table, remember our match table is sorted in descending ID order so new ones should go at the top. Feel free to test it and when you're comfortable we will start fixing some tests.

Fixing old tests

Right now you should have at least a couple erroring tests. It's fine, we changed things on Ranking module so let's head to test/champions/ranking_test.exs.

  describe "concede_loss_to/2" do
    test "adds 3 points to the winner" do
      loser = user_fixture()
      user = user_fixture()
      assert user.points == 0
-     assert {:ok, %User{points: 3}} = Ranking.concede_loss_to(loser, user)
-     match = get_last_match!()
+     assert {:ok, %User{points: 3}, match} = Ranking.concede_loss_to(loser, user)
      assert match.user_a_id == loser.id
      assert match.user_b_id == user.id
      assert match.result == :winner_b
    end
  end

  describe "declare_draw_match/2" do
    test "adds 1 point to each user" do
      user_a = user_fixture()
      user_b = user_fixture()
      assert user_a.points == 0
      assert user_b.points == 0
-     assert {:ok, %User{points: 1}, %User{points: 1}} = Ranking.declare_draw_match(user_a, user_b)
-     match = get_last_match!()
+     assert {:ok, %User{points: 1}, %User{points: 1}, match} = Ranking.declare_draw_match(user_a, user_b)
      assert match.user_a_id == user_a.id
      assert match.user_b_id == user_b.id
      assert match.result == :draw
    end
  end

# some stuff

- def get_last_match!() do
-   Match
-   |> order_by(desc: :id)
-   |> limit(1)
-   |> Repo.one!()
- end

All of a sudden our get_last_match! function is useless! But it was nice since it taught you some Ecto concepts last time.

Adding tests for the UI changes

You LiveView tests are probably not failing right now, but that doesn't mean they have good coverage. Let's add simple tests for the matches. Head out to test/champions_web/live/user_live_test.exs:

describe "Authenticated Show" do
  setup [:register_and_log_in_user]

  # stuff

- test "concede 3 points when I lose to another player", %{conn: conn, user: _user} do
+ test "concede 3 points when I lose to another player", %{conn: conn, user: user} do
    other_user = user_fixture()
    {:ok, show_live, _html} = live(conn, ~p"/users/#{other_user}")

    assert other_user.points == 0
    assert show_live |> element("button", "I lost to this person") |> render_click()
    assert element(show_live, "span[data-points]") |> render() =~ "3"
+   assert element(show_live, "#matches") |> render() =~ user.email
+   assert element(show_live, "#matches") |> render() =~ other_user.email
+   assert element(show_live, "#matches") |> render() =~ "winner_b"
    assert Accounts.get_user!(other_user.id).points == 3
  end

  test "concede 1 point to each user when there's a draw match", %{conn: conn, user: user} do
    other_user = user_fixture()
    {:ok, show_live, _html} = live(conn, ~p"/users/#{other_user}")

    assert user.points == 0
    assert other_user.points == 0
    assert show_live |> element("button", "Declare draw match") |> render_click()
    assert element(show_live, "span[data-my-points]") |> render() =~ "1"
    assert element(show_live, "span[data-points]") |> render() =~ "1"
+   assert element(show_live, "#matches") |> render() =~ user.email
+   assert element(show_live, "#matches") |> render() =~ other_user.email
+   assert element(show_live, "#matches") |> render() =~ "draw"
    assert Accounts.get_user!(user.id).points == 1
    assert Accounts.get_user!(other_user.id).points == 1
  end
end

This is a simple tricky because <.table> will use an ID equal to the stream name so in this case #matches then we just check the user emails and the result to be winner_b and draw. In just a few lines we already added tests to check that our LiveView is reactive. Neat huh?

Summary

Do not do queries on your LiveView, use assigns
Preload that whenever need and possible
We learned a bit more about LiveView streams, namely stream_insert/4

See you next time!

Where are all these points coming from?

Lubien — Thu, 06 Jul 2023 13:22:18 +0000

Where's the fun of winning if people can't know who lost to you? With sportsmanship in our best interest, let's start recording players and outcomes for matches and in the meantime, we will learn some interesting stuff from Ecto and LiveView.

Storing new stuff means we need a new model

Currently, we have a User model and two other related models that Phoenix created for auth stuff. I just told you we need to store match outcomes so that means we need to create a new model. Remember I told you that to change a model we need a migration? The same goes to create a new one.

We are going to create a table called matches that will contain 3 pieces of information: who's player one, who's player two and what's the result of that match. We start that by generating the migration file:

$ mix ecto.gen.migration create_matches
* creating priv/repo/migrations/20230702143738_create_matches.exs

Now we need to edit that to add the information we want:

defmodule Champions.Repo.Migrations.CreateMatches do
  use Ecto.Migration

  def change do
    create table(:matches) do
      add :result, :string
      add :user_a_id, references(:users, on_delete: :delete_all)
      add :user_b_id, references(:users, on_delete: :delete_all)

      timestamps()
    end

    create index(:matches, [:user_a_id])
    create index(:matches, [:user_b_id])
  end
end

Just a quick reminder: the change method means Ecto knows how to run both the migration and rollback methods for this. Since we are using create table(:matches) ecto knows that migrating means create table matches… and rolling back means drop table matches.

As for the fields, the first one will be called :result which we will talk more about later. As for the other fields we have :user_a_id and :user_b_id both using the function references/2 to link those IDs to the users table. Let's talk about these.

First of all the naming choice. I've been calling our users as 'players' sometimes and it definitely would make sense to call those player_a_id and player_b_id. I just think it's easier to reason about this code if the field is called user since the referenced table is called users.

The other thing you might have paid attention to is the keyword on_delete: :delete_all. That means if that specific user were to be deleted this match will also be deleted. This might sound scary right now but I'm making a decision of making user records not delectable. That would cause issues with things like GDPR but since I won't be risking making my database invalid, when the time comes for the app to need users to be able to delete all their data I'll go for the path of obfuscating all Personal Identifiable Information (PII) so John Doe would become 'Unknown User ABC'.

We also add indexes to the foreign keys so it's faster to search for them and trust me we are going to be a lot of listing on those. Don't forget to run mix ecto.migrate. If you do it's no big issue, Phoenix will show a big error message with a button to run this the next time you go to your app.

Now there are 3 implicit columns being created there. First of all, when you use table/2 on an Ecto migration, you're by default creating a field called id. You can opt-out of that but in this case, we want this so we can easily sort, locate, delete, and update them. Next, there's timestamps/1 which adds inserted_at and updated_at fields. inserted_at will be great to know when a match was declared and updated_at could be useful in the future to track updates when this table gets more features.

Contexts strike again

In the Phoenix world, context modules dictate the business rules of our app. Up until today we only used the generated Champions.Accounts module because we only edited things on our users table. That made sense at that time but we are outgrowing the Accounts module and starting something bigger and more and more not so related to the main goal of Accounts which is managing users.

We will start a new context called Ranking that will contain things related to matches and points. All you need to do to create a new module is create a new file under lib/champions.

# lib/champions/ranking.ex
defmodule Champions.Ranking do
  @moduledoc """
  The Ranking context.
  """
end

Later on, we will reason about moving functions from Accounts to here but let's focus on the new code first.

An Ecto migration needs an Ecto model

Ecto migrations only change how data would be stored in your database, you can say it uses Data Definition Language (DDL) if you're into details. But after that, you need to prepare our Elixir app to manage that data, which you can call Data Manipulation Language (DML) if you want to be fancy.

The first step to creating a model is to define the module. Since we are working under the Champions.Ranking module it makes sense for our model to live under Champions.Ranking.Match and of course, the folder structure should match so the file will live under lib/champions/ranking/.

# lib/champions/ranking/match.ex
defmodule Champions.Ranking.Match do
  use Ecto.Schema
  import Ecto.Changeset

  schema "matches" do
    field :result, Ecto.Enum, values: [:winner_a, :winner_b, :draw]
    field :user_a_id, :integer
    field :user_b_id, :integer

    timestamps()
  end

  @doc false
  def changeset(match, attrs) do
    match
    |> cast(attrs, [:result, :user_a_id, :user_b_id])
    |> validate_required([:result, :user_a_id, :user_b_id])
    |> foreign_key_constraint(:user_a_id)
    |> foreign_key_constraint(:user_b_id)
  end
end

There's a lot to unpack here, some of those things you've already seen before but lets take our time to analyze everything bit by bit here.

First of all, this is an elixir module. There's no magic here, defmodule Champions.Ranking.Match says it all. The fun begins in line 3, the use Ecto.Schema means we are using a macro. I promise we will look into how use works later but for now, trust me that use Ecto.Schema makes your module Champions.Ranking.Match also be available as a struct like %Champions.Ranking.Match{user_a_id: 1, user_b_id: 2, result: :winner_a}.

In the next line, we import Ecto.Changeset so we have neat features for data validation. If we didn't import we could be still using all those functions but we'd need to type Ecto.Changeset.cast and Ecto.Changeset.validate_required and that takes soo long we might as well import all functions already. And you just learned how Elixir's import keyword works.

Lines 6 to 12 are where the fun begins. The schema/2 macro receives first the table name followed by a do block. We need the table name to be the same as our migration so since we did create table(:users) here we say schema "users" do. Now let's talk about the do block. Inside it, we do something very similar to our migration except we define fields that will be available inside our struct. The user IDs are very simple since Ecto will map Postgres IDs to Elixir integers we just say they're of the type :integer. And at the end, you will notice there is timestamps/1 again. The last time we saw that function it was from Ecto.Migration now this one is from Ecto.Schema but as you guessed it, it adds inserted_at and updated_at to your model.

The new type here you should be curious about is Ecto.Enum. So far you've only seen types in the form of atom such as :integer and :string but this time the type is a module. This is an Ecto custom type. More specifically, this is a built-in custom type so you don't have to install anything. What it does is help us validate values users try to place on :result and remember you, the programmer, is also an user so whatever validation we can get we take it.

Remember that our migration only said :result is a :string so your database doesn't know anything about enums, this is all in the Ecto.Model. If we ever need to stop using Ecto.Enum all we need to do is change this type to :string and maybe fix some tests.

Last but not the least, when we define an Ecto.Model we need to create at least one changeset to control how the outside world manipulates this data. Ours is pretty simple, we cast and validate_required all fields then do something you haven't seen so far: foreign_key_constraint/3. This validation is a delayed check on the foreign keys. If you try to Repo.insert or Repo.update this changeset, if the foreign keys don't match, Ecto will gracefully handle the error.

Our database knows about our table, we have a model to manipulate such table. The next step is to create functions in our module to make this process easier for anyone who needs.

Adding functions to our Ranking context

defmodule Champions.Ranking do
  @moduledoc """
  The Ranking context.
  """

  import Ecto.Query, warn: false
  alias Champions.Repo

  alias Champions.Ranking.Match

  @doc """
  Creates a match.

  ## Examples

      iex> create_match(%{field: value})
      {:ok, %Match{}}

      iex> create_match(%{field: bad_value})
      {:error, %Ecto.Changeset{}}

  """
  def create_match(attrs \\ %{}) do
    %Match{}
    |> Match.changeset(attrs)
    |> Repo.insert()
  end
end

To start we can be simple, we need only a create_match/1 function. After that we need to teach the places that generate matches how to save them. Let's start with our Champions.Accounts.declare_draw_match/2 .

defmodule Champions.Accounts do
  alias Champions.Ranking
# a lot of things
  def declare_draw_match(user_a, user_b) do
+   {:ok, _match} = Ranking.create_match(%{
+     user_a_id: user_a.id,
+     user_b_id: user_b.id,
+     result: :draw
+   })
    {:ok, updated_user_a} = increment_user_points(user_a, 1)
    {:ok, updated_user_b} = increment_user_points(user_b, 1)
    {:ok, updated_user_a, updated_user_b}
  end
# a lot of things
end

Don't forget to alias Champions.Ranking in the top otherwise you're going to get an error. There's no mystery here, we just used the create_match/2 function to start recording those matches. Now let's go see what it needs to be done for conceding losses:

defmodule Champions.Accounts do
  alias Champions.Ranking
# a lot of things
- def concede_loss_to(winner) do
+ def concede_loss_to(loser, winner) do
+   {:ok, _match} = Ranking.create_match(%{
+     user_a_id: loser.id,
+     user_b_id: winner.id,
+     result: :winner_b
+   })
    increment_user_points(winner, 3)
  end
# a lot of things
end

This time we need to do something to the function signature. concede_loss_to/1 became concede_loss_to/2 because we also need to know who is losing here for the record. Needless to say, you'll need to look for all places that use Accounts.concede_loss_to/1 and change. You could do that by global searching "concede_loss_to(" but if you run mix test right now you will see a ton of errors, some from LiveViews and some from tests itself too. Let's quickly address those so we can move on:

# lib/champions_web/live/user_live/show.ex
- def handle_event("concede_loss", _value, %{assigns: %{user: user}} = socket) do
+ def handle_event("concede_loss", _value, %{assigns: %{current_user: current_user, user: user}} = socket) do
-   {:ok, updated_user} = Accounts.concede_loss_to(current_user, user)
+   {:ok, updated_user} = Accounts.concede_loss_to(user)
    {:noreply, assign(socket, :user, updated_user)}
  end

Fixing that LiveView will also fix its test.

# test/champions/accounts_test.exs
- describe "concede_loss_to/1" do
+ describe "concede_loss_to/2" do
    test "adds 3 points to the winner" do
+     loser = user_fixture()
      user = user_fixture()
      assert user.points == 0
-     assert {:ok, %User{points: 3}} = Accounts.concede_loss_to(user)
+     assert {:ok, %User{points: 3}} = Accounts.concede_loss_to(loser, user)
    end
  end

For now, we just fixed this test error but we will come back to also test that the Match was created. Now your tests should be green.

How do I see data when there's no UI?

If you have a Postgres client such as DBeaver or Postico you probably don't need this right now but in case you don't know about IEx I'll show you something very interesting in Elixir right now.

iex (Interactive Elixir) is a command that comes with Elixir by default that lets enter a REPL where you can quickly test Elixir code just as you would do with JavaScript's console in your browser. If you are inside a Mix project folder and run iex -S mix you tell IEx that you also want to be able to do things using code from your project. Let's do this so we can list all our Matches.

$ iex -S mix
Erlang/OTP 24 [erts-12.3.2] [source] [64-bit] [smp:10:10] [ds:10:10:10] [async-threads:1]

Interactive Elixir (1.14.1) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)> Champions.Repo.all(Champions.Ranking.Match)
[debug] QUERY OK source="matches" db=23.5ms decode=1.3ms queue=15.4ms idle=717.2ms
SELECT m0."id", m0."result", m0."user_a_id", m0."user_b_id", m0."inserted_at", m0."updated_at" FROM "matches" AS m0 []
↳ :erl_eval.do_apply/6, at: erl_eval.erl:685
[
  %Champions.Ranking.Match{
    __meta__: #Ecto.Schema.Metadata<:loaded, "matches">,
    id: 1,
    result: :draw,
    user_a_id: 1,
    user_b_id: 2,
    inserted_at: ~N[2023-07-02 14:43:08],
    updated_at: ~N[2023-07-02 14:43:08]
  },
  %Champions.Ranking.Match{}
  ...
]

The trick is on line 5: Champions.Repo.all(Champions.Ranking.Match). I've just used our Repo.all on our Ranking.Match model to see the results. But right now this is obnoxious to read, let's alias those:

iex(2)> alias Champions.Repo
Champions.Repo
iex(3)> alias Champions.Ranking.Match
Champions.Ranking.Match
iex(4)> Repo.all(Match)
[debug] QUERY OK source="matches" db=23.5ms queue=0.1ms idle=1778.9ms
SELECT m0."id", m0."result", m0."user_a_id", m0."user_b_id", m0."inserted_at", m0."updated_at" FROM "matches" AS m0 []
↳ :erl_eval.do_apply/6, at: erl_eval.erl:685

Now it's more nice right? But what if you wanted to see the lastest ones? I'll explain those functions in detail later but you can copy this so you can reuse it later when you need:

iex(5)> import Ecto.Query
Ecto.Query
iex(6)> Match |> order_by(desc: :id) |> limit(3) |> Repo.all
[debug] QUERY OK source="matches" db=22.0ms queue=18.3ms idle=1938.1ms
SELECT m0."id", m0."result", m0."user_a_id", m0."user_b_id", m0."inserted_at", m0."updated_at" FROM "matches" AS m0 ORDER BY m0."id" DESC LIMIT 3 []
↳ :erl_eval.do_apply/6, at: erl_eval.erl:685
[
  %Champions.Ranking.Match{
    __meta__: #Ecto.Schema.Metadata<:loaded, "matches">,
    id: 31,
    result: :draw,
    user_a_id: 1,
    user_b_id: 2,
    inserted_at: ~N[2023-07-02 18:29:05],
    updated_at: ~N[2023-07-02 18:29:05]
  },
  %Champions.Ranking.Match{
    __meta__: #Ecto.Schema.Metadata<:loaded, "matches">,
    id: 30,
    result: :draw,
    user_a_id: 1,
    user_b_id: 2,
    inserted_at: ~N[2023-07-02 18:29:04],
    updated_at: ~N[2023-07-02 18:29:04]
  },
  %Champions.Ranking.Match{
    __meta__: #Ecto.Schema.Metadata<:loaded, "matches">,
    id: 29,
    result: :draw,
    user_a_id: 1,
    user_b_id: 2,
    inserted_at: ~N[2023-07-02 18:29:04],
    updated_at: ~N[2023-07-02 18:29:04]
  }
]

We've imported Ecto.query to get functions like order_by and limit and just piped our query into Repo.all. Feel free to use it whenever you need.

Where should functions related to points live?

As mentioned previously, these functions were added to the Accounts context for the sake of simplicity and since points are stored in the User model which is managed by Accounts. There's no exact answer here but my gut say that for this project the Ranking module should take care and know about everything related to points so I'm making a choice of moving those.

# lib/champions/ranking.ex
defmodule Champions.Ranking do
  @moduledoc """
  The Ranking context.
  """

  import Ecto.Query, warn: false
  alias Champions.Repo

+ alias Champions.Accounts
  alias Champions.Ranking.Match
+ alias Champions.Accounts.User

  @doc """
  Creates a match.

  ## Examples

      iex> create_match(%{field: value})
      {:ok, %Match{}}

      iex> create_match(%{field: bad_value})
      {:error, %Ecto.Changeset{}}

  """
  def create_match(attrs \\ %{}) do
    %Match{}
    |> Match.changeset(attrs)
    |> Repo.insert()
  end
+
+ @doc """
+ Returns an `%Ecto.Changeset{}` for tracking user changes.
+
+ ## Examples
+
+     iex> change_user_points(user)
+     %Ecto.Changeset{data: %User{}}
+
+ """
+ def change_user_points(%User{} = user, attrs \\ %{}) do
+   User.points_changeset(user, attrs)
+ end
+
+ @doc """
+ Updates the current number of points of a user
+
+ ## Examples
++     iex> update_user_points(user, 10)
+     {:ok, %User{points: 10}}
+
+ """
+ def update_user_points(%User{} = user, points) do
+   user
+   |> change_user_points(%{"points" => points})
+   |> Repo.update()
+ end
+
+ @doc """
+ Adds 3 points to the winning user
+
+ ## Examples
++     iex> concede_loss_to(%User{points: 0})
+     {:ok, %User{points: 3}}
+
+ """
+ def concede_loss_to(loser, winner) do
+   {:ok, _match} = create_match(%{
+     user_a_id: loser.id,
+     user_b_id: winner.id,
+     result: :winner_b
+   })
+   increment_user_points(winner, 3)
+ end
+
+ @doc """
+ Adds 1 point to each user
+
+ ## Examples
+
+     iex> declare_draw_match(%User{points: 0}, %User{points: 0})
+     {:ok, %User{points: 1}, %User{points: 1}}
+
+ """
+ def declare_draw_match(user_a, user_b) do
+   {:ok, _match} = create_match(%{
+     user_a_id: user_a.id,
+     user_b_id: user_b.id,
+     result: :draw
+   })
+   {:ok, updated_user_a} = increment_user_points(user_a, 1)
+   {:ok, updated_user_b} = increment_user_points(user_b, 1)
+   {:ok, updated_user_a, updated_user_b}
+ end
+
+ @doc """
+ Increments `amount` points to the user and returns its updated model
+
+ ## Examples
+
+     iex> increment_user_points(%User{points: 0}, 1)
+     {:ok, %User{points: 1}}
+
+ """
+ def increment_user_points(user, amount) do
+   {1, nil} =
+     User
+     |> where(id: ^user.id)
+     |> Repo.update_all(inc: [points: amount])
+
+   {:ok, Accounts.get_user!(user.id)}
+ end
end

There's a lot of additions plus note one function from Accounts is not there, get_user! so we aliased that model and changed the code to be Accounts.get_user!. Similarly we need to remove those from Accounts. Just remove those functions from there:

# lib/champions/accounts.ex
  @moduledoc """
  The Accounts context.
  """

  import Ecto.Query, warn: false
  alias Champions.Repo
- alias Champions.Ranking

# a ton of code

- @doc """
- Returns an `%Ecto.Changeset{}` for tracking user changes.
-
- ## Examples
-
-     iex> change_user_points(user)
-     %Ecto.Changeset{data: %User{}}
-
- """
- def change_user_points(%User{} = user, attrs \\ %{}) do
-   User.points_changeset(user, attrs)
- end
-
- @doc """
- Updates the current number of points of a user
-
- ## Examples
-
-     iex> update_user_points(user, 10)
-     {:ok, %User{points: 10}}
-
- """
- def update_user_points(%User{} = user, points) do
-   user
-   |> change_user_points(%{"points" => points})
-   |> Repo.update()
- end
-
- @doc """
- Adds 3 points to the winning user
-
- ## Examples
-
-     iex> concede_loss_to(%User{points: 0})
-     {:ok, %User{points: 3}}
-
- """
- def concede_loss_to(loser, winner) do
-   {:ok, _match} = Ranking.create_match(%{
-     user_a_id: loser.id,
-     user_b_id: winner.id,
-     result: :winner_b
-   })
-   increment_user_points(winner, 3)
- end
-
- @doc """
- Adds 1 point to each user
-
- ## Examples
-
-     iex> declare_draw_match(%User{points: 0}, %User{points: 0})
-     {:ok, %User{points: 1}, %User{points: 1}}
-
- """
- def declare_draw_match(user_a, user_b) do
-   {:ok, _match} = Ranking.create_match(%{
-     user_a_id: user_a.id,
-     user_b_id: user_b.id,
-     result: :draw
-   })
-   {:ok, updated_user_a} = increment_user_points(user_a, 1)
-   {:ok, updated_user_b} = increment_user_points(user_b, 1)
-   {:ok, updated_user_a, updated_user_b}
- end
-
- @doc """
- Increments `amount` points to the user and returns its updated model
-
- ## Examples
-
-     iex> increment_user_points(%User{points: 0}, 1)
-     {:ok, %User{points: 1}}
-
- """
- def increment_user_points(user, amount) do
-   {1, nil} =
-     User
-     |> where(id: ^user.id)
-     |> Repo.update_all(inc: [points: amount])
-
-   {:ok, get_user!(user.id)}
- end

Don't forget to remove the alias Champions.Ranking so you wont be seeing warnings in your terminal. Time to do a similar thing with tests. We will use this as an opportunity to get started on our Ranking tests.

# test/champions/ranking_test.exs
defmodule Champions.RankingTest do
  use Champions.DataCase

  alias Champions.Ranking
  alias Champions.Accounts.User
  import Champions.AccountsFixtures

  describe "change_user_points/2" do
    test "accepts non-negative integers" do
      assert %Ecto.Changeset{} = changeset = Ranking.change_user_points(%User{}, %{"points" => -1})
      refute changeset.valid?

      assert %Ecto.Changeset{} = changeset = Ranking.change_user_points(%User{}, %{"points" => 0})
      assert changeset.valid?

      assert %Ecto.Changeset{} = changeset = Ranking.change_user_points(%User{}, %{"points" => 10})
      assert changeset.valid?
    end
  end

  describe "set_user_points/2" do
    setup do
      %{user: user_fixture()}
    end

    test "updates the amounts of points of an existing user", %{user: user} do
      {:ok, updated_user} = Ranking.update_user_points(user, 10)
      assert updated_user.points == 10
    end
  end

  describe "concede_loss_to/2" do
    test "adds 3 points to the winner" do
      loser = user_fixture()
      user = user_fixture()
      assert user.points == 0
      assert {:ok, %User{points: 3}} = Ranking.concede_loss_to(loser, user)
    end
  end

  describe "declare_draw_match/2" do
    test "adds 1 point to each user" do
      user_a = user_fixture()
      user_b = user_fixture()
      assert user_a.points == 0
      assert user_b.points == 0
      assert {:ok, %User{points: 1}, %User{points: 1}} = Ranking.declare_draw_match(user_a, user_b)
    end
  end

  describe "increment_user_points/2" do
    test "performs an atomic increment on a single user points amount" do
      user = user_fixture()
      assert user.points == 0
      assert {:ok, %User{points: 10}} = Ranking.increment_user_points(user, 10)
      assert {:ok, %User{points: 5}} = Ranking.update_user_points(user, 5)
      assert {:ok, %User{points: 15}} = Ranking.increment_user_points(user, 10)
    end
  end
end

We pretty much copy-pasted the functions from Account tests and renamed the context name. Feel free to copy the code above under test/champions/ranking_test.exs or challenge yourself to create the file and copy your current test/champions/accounts_test.exs and fix the differences, that's going to be interesting. It's worth mentioning your LiveView will be erroring right now so to focus only on this file run mix test test/champions/ranking_test.exs.

defmodule Champions.AccountsTest do
# a lot of code
- describe "change_user_points/2" do
-   test "accepts non-negative integers" do
-     assert %Ecto.Changeset{} = changeset = Accounts.change_user_points(%User{}, %{"points" => -1})
-     refute changeset.valid?
-
-     assert %Ecto.Changeset{} = changeset = Accounts.change_user_points(%User{}, %{"points" => 0})
-     assert changeset.valid?
-
-     assert %Ecto.Changeset{} = changeset = Accounts.change_user_points(%User{}, %{"points" => 10})
-     assert changeset.valid?
-   end
- end
-
- describe "set_user_points/2" do
-   setup do
-     %{user: user_fixture()}
-   end
-
-   test "updates the amounts of points of an existing user", %{user: user} do
-     {:ok, updated_user} = Accounts.update_user_points(user, 10)
-     assert updated_user.points == 10
-   end
- end
  describe "list_users/0" do
    test "show all users on our system" do
      user = user_fixture()
      assert [^user] = Accounts.list_users()
    end
  end
-
- describe "concede_loss_to/2" do
-   test "adds 3 points to the winner" do
-     loser = user_fixture()
-     user = user_fixture()
-     assert user.points == 0
-     assert {:ok, %User{points: 3}} = Accounts.concede_loss_to(loser, user)
-   end
- end
-
- describe "declare_draw_match/2" do
-   test "adds 1 point to each user" do
-     user_a = user_fixture()
-     user_b = user_fixture()
-     assert user_a.points == 0
-     assert user_b.points == 0
-     assert {:ok, %User{points: 1}, %User{points: 1}} = Accounts.declare_draw_match(user_a, user_b)
-   end
- end
-
- describe "increment_user_points/2" do
-   test "performs an atomic increment on a single user points amount" do
-     user = user_fixture()
-     assert user.points == 0
-     assert {:ok, %User{points: 10}} = Accounts.increment_user_points(user, 10)
-     assert {:ok, %User{points: 5}} = Accounts.update_user_points(user, 5)
-     assert {:ok, %User{points: 15}} = Accounts.increment_user_points(user, 10)
-   end
- end
end

I haven't realized before by list_users/0 test was in the middle of that mess but it doesn't matter now.

defmodule ChampionsWeb.UserLive.Show do
# some code
  def handle_event("concede_loss", _value, %{assigns: %{current_user: current_user, user: user}} = socket) do
-   {:ok, updated_user} = Accounts.concede_loss_to(current_user, user)
+   {:ok, updated_user} = Ranking.concede_loss_to(current_user, user)
    {:noreply, assign(socket, :user, updated_user)}
  end

  def handle_event("concede_draw", _value, %{assigns: %{current_user: current_user, user: user}} = socket) do
-   {:ok, updated_my_user, updated_user} = Accounts.declare_draw_match(current_user, user)
+   {:ok, updated_my_user, updated_user} = Ranking.declare_draw_match(current_user, user)
    {:noreply,
      socket
      |> assign(:user, updated_user)
      |> assign(:current_user, updated_my_user)
    }
  end

There's no tricky here, this fixes our LiveView and consequently all our tests. Your mix test should be all green now!

Testing the new things

We so far only focused on refactoring code and got some tests on ranking_tests.exs but those are all for old things, we need to ensure the new code works and will keep working. The easiest test we can do is just check if we can create a match:

defmodule Champions.RankingTest do
  use Champions.DataCase

  alias Champions.Ranking
+ alias Champions.Ranking.Match
  alias Champions.Accounts.User
  import Champions.AccountsFixtures

+ describe "create_match/1" do
+   test "create_match/1 with valid data creates a match" do
+     loser = user_fixture()
+     winner = user_fixture()
+     valid_attrs = %{result: :winner_a, user_a_id: loser.id, user_b_id: winner.id}
+
+     assert {:ok, %Match{} = match} = Ranking.create_match(valid_attrs)
+     assert match.result == :winner_a
+   end
+
+   test "create_match/1 with an invalid user ID fails" do
+     loser = user_fixture()
+     valid_attrs = %{result: :winner_a, user_a_id: loser.id, user_b_id: 10_000_000}
+
+     assert {:error, %Ecto.Changeset{} = changeset} = Ranking.create_match(valid_attrs)
+     assert {"does not exist", _rest} = Keyword.fetch!(changeset.errors, :user_b_id)
+   end
+ end
# more code
end

Now let's talk about the functions that generate matches: Ranking.concede_loss_to/2 and Ranking.declare_draw_match/2. Their signature is to always return the users that were updated so our LiveView can update them. Doesn't seems we have a reason to change those functions specifically now so we need a different way to test that matches where created. Since Mix tests use a sandboxed Postgres adapter we can simply trust that the last Match will be the one just created.

  describe "concede_loss_to/2" do
    test "adds 3 points to the winner" do
      loser = user_fixture()
      user = user_fixture()
      assert user.points == 0
      assert {:ok, %User{points: 3}} = Ranking.concede_loss_to(loser, user)
+     match = get_last_match!()
+     assert match.user_a_id == loser.id
+     assert match.user_b_id == user.id
+     assert match.result == :winner_b
    end
  end

  describe "declare_draw_match/2" do
    test "adds 1 point to each user" do
      user_a = user_fixture()
      user_b = user_fixture()
      assert user_a.points == 0
      assert user_b.points == 0
      assert {:ok, %User{points: 1}, %User{points: 1}} = Ranking.declare_draw_match(user_a, user_b)
+     match = get_last_match!()
+     assert match.user_a_id == user_a.id
+     assert match.user_b_id == user_b.id
+     assert match.result == :draw
    end
  end

# put this in the end:

+ def get_last_match!() do
+   Match
+   |> order_by(desc: :id)
+   |> limit(1)
+   |> Repo.one!()
+ end
end

We created a simple get_last_match! helper function so we wont duplicate code here. After getting the last match all we need is to check if the data is set according to our test and we are good. But now, assuming you never did an Ecto.Query before, you could be confused about that and that's already the second time in this post I use it so let's talk about that.

A 3 minutes introduction to Ecto.Query

Whenever we need to query data from our database, in the end, we use Repo with functions such as Repo.exists?/2 to check if the query contains any results, Repo.all/2 to get all results that fit the query or Repo.one/2 that will get a single result and error if there's none or more than one possible result. What those functions don't do is tell "what am I looking for". Ecto.Query and Ecto.Repo combine themselves to be more powerful: Ecto.Query scope things and Ecto.Repo executes the database call.

What's the most basic Ecto.Query possible? The answer is simple and you've been seeing me do that all the time: all Ecto.Model are queries. If you go to iex -S mix and do Repo.all(Match) (don't forget the aliases) you will see a list of all queries. So Ecto.Model is a query with no boundaries.

What if I want to get more specific results? That's were Ecto.Query jumps in. It comes with very useful functions. They're so useful that, I don't know if you paid attention, all contexts contain import Ecto.Query, warn: false at the top because we all know we will be using them at some point so we ignore the warn until them, Phoenix will generate that for you in every single context. If you don't import it's also fine but you'll quickly see yourself writing things like Ecto.Query.where and Ecto.Query.order_bya lot so why not import as soon as needed.

Now how we scope things down with queries? We first start with a query that knows no boundaries: a model. After that we just keep adding constraints. Let's dive down into get_last_match!/0 so we have an example.

  def get_last_match!() do
# The query starts with `Match` so it reads as 'give me all matches'
# or if you like SQL: `select * from matches`
    Match
# As soon as we use order_by/3 we add a new constraint saying exactly what the
# function name days. SQL: `select * from matches order by id desc`
    |> order_by(desc: :id)
# Needless to say, limit/3 does the same.
# SQL: `select * from matches order by id desc limit 1`
    |> limit(1)
# As for Repo.one!/2 it will run the query and error if the count is not
# exactly 1. In this case, it only can be 0 or 1 because of our limit.
    |> Repo.one!()
  end

Summary

We learned how to create a new Ecto model from scratch, including migrations and why those two correlate.
We created our first context by hand and reasoned about when functions should be moved from one to another
We quickly glanced at how to see data on IEx also using Ecto.Query
We also learned that Postgres tests live on a sandbox environment so things like getting the last row can be relied on for tests and we also created a helper function for our tests
We quickly talked about how Ecto queries work scoping things down.

To prevent this post from becoming much longer I will stop it here and next time we will learn interesting stuff related to how to show data on LiveView and some Ecto tricks to make getting related models easier. See you next time.

The Lazy Programmer's Intro to LiveView: Chapter 8

Lubien — Sun, 18 Jun 2023 15:07:45 +0000

Distributed systems are hard

I want to invite you to test our system in a particular way. I assume you have two users on your platform: Lubien and Enemy. Open one browser window logged in as Lubien and another browser window logged in as enemy (you should probably use incognito), on each account open the user page for the other user. As Lubien, I can see Enemy's points at 72 and mine at 104. From the other point of view, Enemy sees my points at 104 and their navbar tells they have 72.

Now I'm going to concede 10 losses to Enemy using my UI.

Without refreshing, I'm going to Enemy's browser and declare a draw match.

You probably already guessed but if you refresh my window it's going to downgrade Enemy's points to 73 too. All that mess happens because we trust the current LiveView state to apply updates to points and both users happened to be with their windows open. There are many solutions to this: sync LiveViews when points change, create a CRDT, use a Postgres table to record matches then always sum the results of points, etc. The last option seems really good too, but I'd like to use this bug as an excuse to show off some more Ecto so bear with me.

Removing business logic from LiveView

LiveView has no guilt in this bug but it definitely shouldn't be the one doing these calculations. We should put business logic inside our context modules not inside handle_event/3. Let's start by fixing that. Edit show.ex:

def handle_event("concede_loss", _value, %{assigns: %{user: user}} = socket) do
- {:ok, updated_user} = Accounts.update_user_points(user, user.points + 3)
+ {:ok, updated_user} = Accounts.concede_loss_to(user)
  {:noreply, assign(socket, :user, updated_user)}
end

def handle_event("concede_draw", _value, %{assigns: %{current_user: current_user, user: user}} = socket) do
- {:ok, updated_user} = Accounts.update_user_points(user, user.points + 1)
- {:ok, updated_my_user} = Accounts.update_user_points(current_user, current_user.points + 1)
+ {:ok, updated_my_user, updated_user} = Accounts.declare_draw_match(current_user, user)
  {:noreply,
    socket
    |> assign(:user, updated_user)
    |> assign(:current_user, updated_my_user)
  }
end

Then head back to accounts.ex to create those functions:

@doc """
Adds 3 points to the winning user

## Examples

    iex> concede_loss_to(%User{points: 0})
    {:ok, %User{points: 3}}

"""
def concede_loss_to(winner) do
  update_user_points(winner, winner.points + 3)
end

@doc """
Adds 1 point to each user

## Examples

    iex> declare_draw_match(%User{points: 0}, %User{points: 0})
    {:ok, %User{points: 1}, %User{points: 1}}

"""
def declare_draw_match(user_a, user_b) do
  {:ok, updated_user_a} = update_user_points(user_a, user_a.points + 1)
  {:ok, updated_user_b} = update_user_points(user_b, user_b.points + 1)
  {:ok, updated_user_a, updated_user_b}
end

You should be able to easily run mix test to verify everything still works just fine. Now what we need is to avoid assuming the current amount of points is the most updated one. Instead of update_user_points we must create an atomic function that increments points based on the current database state:

@doc """
Adds 3 points to the winning user

## Examples

    iex> concede_loss_to(%User{points: 0})
    {:ok, %User{points: 3}}

"""
def concede_loss_to(winner) do
  increment_user_points(winner, 3)
end

@doc """
Adds 1 point to each user

## Examples

    iex> declare_draw_match(%User{points: 0}, %User{points: 0})
    {:ok, %User{points: 1}, %User{points: 1}}

"""
def declare_draw_match(user_a, user_b) do
  {:ok, updated_user_a} = increment_user_points(user_a, 1)
  {:ok, updated_user_b} = increment_user_points(user_b, 1)
  {:ok, updated_user_a, updated_user_b}
end

@doc """
Increments `amount` points to the user and returns its updated model

## Examples

    iex> increment_user_points(%User{points: 0}, 1)
    {:ok, %User{points: 1}}

"""
defp increment_user_points(user, amount) do
  {1, nil} =
    User
    |> where(id: ^user.id)
    |> Repo.update_all(inc: [points: amount])

  {:ok, get_user!(user.id)}
end

We created increment_user_points/2 that takes the user and the number of points. The real magic here comes from Repo.update_all/3. We define a query and then pass it to Repo.update_all/3 to run. The query is pretty simple:

On line 30 we start by saying this query affects all users because we started with the User Ecto model.
At line 31 we scope this query only for users with an id equal to user.id using where/3. We need to use the pin operator (^) to put a variable that comes from outside the query in there, it will escape inputs to prevent SQL injection.
Last but not least, we run Repo.update_all/3 using the special inc option to increment points by amount as many times.

Since this query returns a tuple containing the count of updated entries and nil unless we manually select fields, we just ignore the result and a {:ok, get_user!(user.id)} to get the updated user. Your bug should be fixed now.

Let's not forget our tests

The good thing is that since these functions are already being used on our LiveView we know they work by simply running mix test. But let's not forget to test those out on our accounts_test.exs too. Who knows, maybe that LiveView page goes away and we lose that coverage.

describe "concede_loss_to/1" do
  test "adds 3 points to the winner" do
    user = user_fixture()
    assert user.points == 0
    assert {:ok, %User{points: 3}} = Accounts.concede_loss_to(user)
  end
end

describe "declare_draw_match/2" do
  test "adds 1 point to each user" do
    user_a = user_fixture()
    user_b = user_fixture()
    assert user_a.points == 0
    assert user_b.points == 0
    assert {:ok, %User{points: 1}, %User{points: 1}} = Accounts.declare_draw_match(user_a, user_b)
  end
end

describe "increment_user_points/2" do
  test "performs an atomic increment on a single user points amount" do
    user = user_fixture()
    assert user.points == 0
    assert {:ok, %User{points: 10}} = Accounts.increment_user_points(user, 10)
    assert {:ok, %User{points: 5}} = Accounts.update_user_points(user, 5)
    assert {:ok, %User{points: 15}} = Accounts.increment_user_points(user, 10)
  end
end

The first two ones are pretty obvious but the increment_user_points/2 suite tries to reproduce the bug the out-of-sync bug we caught at the start of this post and ensures that this function solves it.

Summary

Be careful doing updates on stated based on cached state, they can easily go out of sync.
Business logic should live outside LiveView.
Ecto allows you to run atomic update queries with Repo.update_all/3.

Chapter 9: TODO 😉

The Lazy Programmer's Intro to LiveView: Chapter 7

Lubien — Sun, 18 Jun 2023 15:07:42 +0000

Conceding points to the winner

Sometimes you will lose and that's okay. Just don't forget to give your opponent 3 points for their victory. In this chapter, we will explore how one user could give 3 points to another if they lose to them. In case you haven't already, create a second account on your app.

Dynamic interactions with LiveView

So far we haven't created any sort of user interaction besides boring links from one page to another. Let's make our user LiveView more powerful. What we need to do is create an 'I lost to this person' button that when pressed gives them 3 points. Let's start with the render function. Update your lib/champions_web/live/user_live/show.ex render function to:

@impl true
def render(assigns) do
  ~H"""
  <.header>
    User <%= @user.id %>
    <:subtitle>This is a player on this app.</:subtitle>
  </.header>

  <.list>
    <:item title="Email"><%= @user.email %></:item>
    <:item title="Points"><%= @user.points %></:item>
  </.list>

+ <div class="my-4">
+   <.button type="button" phx-click="concede_loss">I lost to this person</.button>
+ </div>

  <.back navigate={~p"/users"}>Back to users</.back>
  """
end

We just added a Phoenix <.button> component and it contains an attribute called phx-click. Clicking this button will trigger an event on our LiveView but there's a catch: we are not ready for this event yet. Press that button right now and your terminal will show the following error:

[error] GenServer #PID<0.3550.0> terminating
** (UndefinedFunctionError) function ChampionsWeb.UserLive.Show.handle_event/3 is undefined or private
    ChampionsWeb.UserLive.Show.handle_event("concede_loss", %{"value" => ""}, #Phoenix.LiveView.Socket<id: "phx-F2mNT8Nhl-Qz2gxH", endpoint: ChampionsWeb.Endpoint, view: ChampionsWeb.UserLive.Show, parent_pid: nil, root_pid: #PID<0.3550.0>, router: ChampionsWeb.Router, assigns: %{__changed__: %{}, current_user: #Champions.Accounts.User<__meta__: #Ecto.Schema.Metadata<:loaded, "users">, id: 1, email: "lubien@example.com", confirmed_at: ~N[2023-06-17 13:55:41], points: 0, inserted_at: ~N[2023-06-17 13:53:56], updated_at: ~N[2023-06-17 13:55:41], ...>, flash: %{}, live_action: :show, page_title: "Showing user enemy@example.com", user: #Champions.Accounts.User<__meta__: #Ecto.Schema.Metadata<:loaded, "users">, id: 2, email: "enemy@example.com", confirmed_at: nil, points: 0, inserted_at: ~N[2023-06-18 10:28:49], updated_at: ~N[2023-06-18 10:28:49], ...>}, transport_pid: #PID<0.3544.0>, ...>)
    (phoenix_live_view 0.19.2) lib/phoenix_live_view/channel.ex:401: anonymous fn/3 in Phoenix.LiveView.Channel.view_handle_event/3
    (telemetry 1.2.1) /Users/lubien/workspace/champions/deps/telemetry/src/telemetry.erl:321: :telemetry.span/3
    (phoenix_live_view 0.19.2) lib/phoenix_live_view/channel.ex:221: Phoenix.LiveView.Channel.handle_info/2
    (stdlib 3.17.2) gen_server.erl:695: :gen_server.try_dispatch/4
    (stdlib 3.17.2) gen_server.erl:771: :gen_server.handle_msg/6
    (stdlib 3.17.2) proc_lib.erl:236: :proc_lib.wake_up/3
Last message: %Phoenix.Socket.Message{topic: "lv:phx-F2mNT8Nhl-Qz2gxH", event: "event", payload: %{"event" => "concede_loss", "type" => "click", "value" => %{"value" => ""}}, ref: "12", join_ref: "4"}
State: %{components: {%{}, %{}, 1}, join_ref: "4", serializer: Phoenix.Socket.V2.JSONSerializer, socket: #Phoenix.LiveView.Socket<id: "phx-F2mNT8Nhl-Qz2gxH", endpoint: ChampionsWeb.Endpoint, view: ChampionsWeb.UserLive.Show, parent_pid: nil, root_pid: #PID<0.3550.0>, router: ChampionsWeb.Router, assigns: %{__changed__: %{}, current_user: #Champions.Accounts.User<__meta__: #Ecto.Schema.Metadata<:loaded, "users">, id: 1, email: "lubien@example.com", confirmed_at: ~N[2023-06-17 13:55:41], points: 0, inserted_at: ~N[2023-06-17 13:53:56], updated_at: ~N[2023-06-17 13:55:41], ...>, flash: %{}, live_action: :show, page_title: "Showing user enemy@example.com", user: #Champions.Accounts.User<__meta__: #Ecto.Schema.Metadata<:loaded, "users">, id: 2, email: "enemy@example.com", confirmed_at: nil, points: 0, inserted_at: ~N[2023-06-18 10:28:49], updated_at: ~N[2023-06-18 10:28:49], ...>}, transport_pid: #PID<0.3544.0>, ...>, topic: "lv:phx-F2mNT8Nhl-Qz2gxH", upload_names: %{}, upload_pids: %{}}

That's a lot to unpack but bear with me. I like Phoenix errors because they tell you a lot once you understand how to read them. I'd like to teach you that right now so let's break down it bit by bit:

Learning how to interpret a LiveView event error

First of all, the first line tells you something very important: [error] GenServer #PID<0.3550.0> terminating. That means this error was bad, our LiveView page crashed and had to be restarted. That's not a great experience so you definitely want to fix this.

On line 2 you can already see a good hint at the issue: UndefinedFunctionError. That name says all: LiveView expected a certain function to be defined but it wasn't. Keep reading that line and we can see that function ChampionsWeb.UserLive.Show.handle_event/3 is undefined or private tells us that we forgot to create a handle_event function that takes 3 arguments or we mistakenly created it as a private function using defp. Well you didn't forget it since you're learning yet, I just wanted you to experience this cool error message though.

But say you've never heard of handle_event/3 , what do I need to do with that function? Line 3 gives you exactly what Phoenix tried passing to that function so you can pretty much get started with that: ChampionsWeb.UserLive.Show.handle_event("concede_loss", %{"value" => ""}, #Phoenix.LiveView.Socket<id: "phx-F2mNT8Nhl-Qz2gxH"...>). Do note that Phoenix.LiveView.Socket contains a lot of information so it can be threatening to read the whole piece but in time you will learn to ignore it and focus on the other arguments, I even cut it for you already in this paragraph.

Creating our `handle_event/3`

handle_event/3 is a new LiveView callback you should learn about. It is triggered when one of your LiveView events from the render function is called such as phx-click. In this case, we created a phx-click="concede_loss" so our event name will be concede_loss. The second argument with contains values, we will ignore that for now, and last but not least there's the socket as the third argument. Did you notice that all callbacks have the socket as the last argument? That's because all callbacks are just functions that manage what is inside the socket so it makes sense for it to be available.

@impl true
def handle_event("concede_loss", _value, socket) do
  {:noreply, socket}
end

The code above is the minimal event handler needed to receive our custom event and do nothing. handle_event/3 must return either {:noreply, socket} or {:reply, map, socket}. For now, we will focus on the :noreply case. Now that we have an event handler we need to modify it to get the user being shown on the page and add 3 points to them. Fortunately socket contains a property called assigns that has all assigns. Since this page has a user assigns, socket.assigns.user is readily available to us.

@impl true
def handle_event("concede_loss", _value, socket) do
  user = socket.assigns.user
  {:ok, updated_user} = Accounts.update_user_points(user, user.points + 3)
  {:noreply, assign(socket, :user, updated_user)}
end

That's it! All we had to do was get the user assign and run that function we created back in the early chapters of this project. Don't forget to reassign the user so the LiveView updates immediately without a page refresh needed to show the new points.

Conceding a draw

I've also told you when this series started that draws would give both players 1 point. You can probably guess 90% of what needs to be done by copying and pasting what you just learned so let's start with that. We will create a concede_draw event that's a carbon copy of concede_loss.

  @impl true
  def handle_event("concede_loss", _value, socket) do
    user = socket.assigns.user
    {:ok, updated_user} = Accounts.update_user_points(user, user.points + 3)
    {:noreply, assign(socket, :user, updated_user)}
  end
+
+ def handle_event("concede_draw", _value, socket) do
+   user = socket.assigns.user
+   {:ok, updated_user} = Accounts.update_user_points(user, user.points + 1)
+   {:noreply, assign(socket, :user, updated_user)}
+ end

  @impl true
  def render(assigns) do
    ~H"""
    <.header>
      User <%= @user.id %>
      <:subtitle>This is a player on this app.</:subtitle>
    </.header>

    <.list>
      <:item title="Email"><%= @user.email %></:item>
      <:item title="Points"><%= @user.points %></:item>
    </.list>

    <div class="my-4">
      <.button type="button" phx-click="concede_loss">I lost to this person</.button>
+     <.button type="button" phx-click="concede_draw">Declare draw match</.button>
    </div>

    <.back navigate={~p"/users"}>Back to users</.back>
    """
  end

Do note we didn't add @impl true on the second handle_event/3 clause because Elixir will already infer that from the first one. How can I know which user am I on my LiveView so I can add 1 point to myself? Back when we generated our auth code Phoenix added something called LiveSession, which we will explore later, but the important bit is that it adds an assign called current_user on your socket, so you can use it on callbacks and on your render functions, we even used it to show your points on the navbar.

def handle_event("concede_draw", _value, socket) do
+ my_user = socket.assigns.current_user
  user = socket.assigns.user
  {:ok, updated_user} = Accounts.update_user_points(user, user.points + 1)
+ {:ok, updated_my_user} = Accounts.update_user_points(my_user, my_user.points + 1)
- {:noreply, assign(socket, :user, updated_user)}
+ {:noreply,
+   socket
+   |> assign(:user, updated_user)
+   |> assign(:current_user, updated_my_user)
+ }
end

Amazing, we already have two main features of our app up and running. But if you pay attention to your navbar you will notice that your points aren't increasing but if you refresh the page your new points will show up. What is happening with our layout?

Difference between `root.html.heex` and `app.html.heex` layout

The root.html.heex layout is meant to be rendered only once and never update again with one single exception: updating page titles. That means that in order for us to see live updates to our navbar we must move our navbar logic to app.html.heex which is LiveView-aware. That's quite simple actually. Remove this entire ul from your root.html.heex:

<!DOCTYPE html>
<html lang="en" class="[scrollbar-gutter:stable]">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="csrf-token" content={get_csrf_token()} />
    <.live_title suffix=" · Phoenix Framework">
      <%= assigns[:page_title] || "Champions" %>
    </.live_title>
    <link phx-track-static rel="stylesheet" href={~p"/assets/app.css"} />
    <script defer phx-track-static type="text/javascript" src={~p"/assets/app.js"}>
    </script>
  </head>
  <body class="bg-white antialiased">
-   <ul class="relative z-10 flex items-center gap-4 px-4 sm:px-6 lg:px-8 justify-end">
-     <%= if @current_user do %>
-       <li class="text-[0.8125rem] leading-6 text-zinc-900">
-         <%= @current_user.email %>
-         (<%= @current_user.points %> points)
-       </li>
-       <li>
-         <.link
-           href={~p"/users/settings"}
-           class="text-[0.8125rem] leading-6 text-zinc-900 font-semibold hover:text-zinc-700"
-         >
-           Settings
-         </.link>
-       </li>
-       <li>
-         <.link
-           href={~p"/users/log_out"}
-           method="delete"
-           class="text-[0.8125rem] leading-6 text-zinc-900 font-semibold hover:text-zinc-700"
-         >
-           Log out
-         </.link>
-       </li>
-     <% else %>
-       <li>
-         <.link
-           href={~p"/users/register"}
-           class="text-[0.8125rem] leading-6 text-zinc-900 font-semibold hover:text-zinc-700"
-         >
-           Register
-         </.link>
-       </li>
-       <li>
-         <.link
-           href={~p"/users/log_in"}
-           class="text-[0.8125rem] leading-6 text-zinc-900 font-semibold hover:text-zinc-700"
-         >
-           Log in
-         </.link>
-       </li>
-     <% end %>
-   </ul>
    <%= @inner_content %>
  </body>
</html>

Then add it to the top of your app.html.heex:

+<ul class="relative z-10 flex items-center gap-4 px-4 sm:px-6 lg:px-8 justify-end">
+<%= if @current_user do %>
+  <li class="text-[0.8125rem] leading-6 text-zinc-900">
+    <%= @current_user.email %>
+    (<%= @current_user.points %> points)
+  </li>
+  <li>
+    <.link
+      href={~p"/users/settings"}
+      class="text-[0.8125rem] leading-6 text-zinc-900 font-semibold hover:text-zinc-700"
+    >
+      Settings
+    </.link>
+  </li>
+  <li>
+    <.link
+      href={~p"/users/log_out"}
+      method="delete"
+      class="text-[0.8125rem] leading-6 text-zinc-900 font-semibold hover:text-zinc-700"
+    >
+      Log out
+    </.link>
+  </li>
+<% else %>
+  <li>
+    <.link
+      href={~p"/users/register"}
+      class="text-[0.8125rem] leading-6 text-zinc-900 font-semibold hover:text-zinc-700"
+    >
+      Register
+    </.link>
+  </li>
+  <li>
+    <.link
+      href={~p"/users/log_in"}
+      class="text-[0.8125rem] leading-6 text-zinc-900 font-semibold hover:text-zinc-700"
+    >
+      Log in
+    </.link>
+  </li>
+<% end %>
+</ul>
<header class="px-4 sm:px-6 lg:px-8">
... rest of the things here

Now your points should be updated each time you click on the draw button! But here's a catch: we just broke our tests! If you run mix test you will spot two errors. They're both related to the fact that the login and register tests send you to the root path / and expect your navbar to be there but the homepage explicitly says it doesn't want to use app.html.heex on lib/champions_web/controllers/page_controller.ex by render(conn, :home, layout: false).

That's okay and since we won't be caring for that page in the future the solution is quite simple: let's change those tests to send users to the /users page. Locate and change this on test/champions_web/controllers/user_session_controller_test.exs

# Now do a logged in request and assert on the menu
-conn = get(conn, ~p"/")
+conn = get(conn, ~p"/users")
response = html_response(conn, 200)
assert response =~ user.email
assert response =~ ~p"/users/settings"
assert response =~ ~p"/users/log_out"

Do the same thing on test/champions_web/live/user_registration_live_test.exs:

# Now do a logged in request and assert on the menu
-conn = get(conn, "/")
+conn = get(conn, "/users")
response = html_response(conn, 200)
assert response =~ email
assert response =~ "Settings"
assert response =~ "Log out"

Your mix test should be running just fine now!

Preventing unauthorized users from using these buttons

Right now if you open an anonymous tab and hit those buttons you will have pleasant surprises. Hitting the concede loss button will work just fine even though I'm not a player. Hitting the concede draw button will crash our LiveView because there's no current_user assign. Let's fix that.

@impl true
def handle_event("concede_loss", _value, socket) do
  socket =
    if socket.assigns.current_user do
      user = socket.assigns.user
      {:ok, updated_user} = Accounts.update_user_points(user, user.points + 3)
      assign(socket, :user, updated_user)
    else
      put_flash(socket, :error, "You must be a player to do that!")
    end

  {:noreply, socket}
end

def handle_event("concede_draw", _value, socket) do
  socket =
    if my_user = socket.assigns.current_user do
      user = socket.assigns.user
      {:ok, updated_user} = Accounts.update_user_points(user, user.points + 1)
      {:ok, updated_my_user} = Accounts.update_user_points(my_user, my_user.points + 1)
      socket
      |> assign(:user, updated_user)
      |> assign(:current_user, updated_my_user)
    else
      put_flash(socket, :error, "You must be a player to do that!")
    end

  {:noreply, socket}
end

This time a simple if expression could solve our problems. Even if our user shouldn't be able to do some events we still need to return {:noreply, socket} but in case they're unauthorized we will use put_flash/3 to show a pretty error message. Now let's hide these buttons from those who shouldn't see them:

@impl true
def render(assigns) do
  ~H"""
  <.header>
    User <%= @user.id %>
    <:subtitle>This is a player on this app.</:subtitle>
  </.header>

  <.list>
    <:item title="Email"><%= @user.email %></:item>
    <:item title="Points"><%= @user.points %></:item>
  </.list>

- <div class="my-4">
+ <div :if={@current_user} class="my-4">
    <.button type="button" phx-click="concede_loss">I lost to this person</.button>
    <.button type="button" phx-click="concede_draw">Declare draw match</.button>
  </div>

  <.back navigate={~p"/users"}>Back to users</.back>
  """
end

HEEx nodes can use :if={condition} to show elements, pretty handy. At this point, you could be asking yourself 'Why bother validating in the events if we are not going to show these buttons?' And that's a really good question. The thing about LiveView events is that there's no real magic on the HTML side, a <.button phx-click="concede_loss"> is just a regular HTML button like <button phx-click="concede_loss>. If your users are clever to figure that out they could 👻 haxx your system! Don't believe me? Paste the HTML below on an unauthenticated tab on /users/:id using your browser dev tools:

<button type="button" phx-click="concede_loss">
  Hacking to the Gate 🔥
</button>

How to prevent a user from giving points to himself infinitely

Right now you can also go to your own page and concede losses/draws to yourself and you get all the points. That's not right so let's fix this!

@impl true
def handle_event("concede_loss", _value, socket) do
  socket =
    case {socket.assigns.current_user, socket.assigns.user} do
      {nil, _user} ->
        put_flash(socket, :error, "You must be a player to do that!")

      {%{id: my_id}, %{id: other_id}} when my_id == other_id ->
        put_flash(socket, :error, "You can't give points to yourself")

      {_my_user, user} ->
        {:ok, updated_user} = Accounts.update_user_points(user, user.points + 3)
        assign(socket, :user, updated_user)
    end

  {:noreply, socket}
end

def handle_event("concede_draw", _value, socket) do
  socket =
    case {socket.assigns.current_user, socket.assigns.user} do
      {nil, _user} ->
        put_flash(socket, :error, "You must be a player to do that!")

      {%{id: my_id}, %{id: other_id}} when my_id == other_id ->
        put_flash(socket, :error, "You can't give points to yourself")

      {my_user, user} ->
        {:ok, updated_user} = Accounts.update_user_points(user, user.points + 1)
        {:ok, updated_my_user} = Accounts.update_user_points(my_user, my_user.points + 1)
        socket
        |> assign(:user, updated_user)
        |> assign(:current_user, updated_my_user)
    end

  {:noreply, socket}
end

This time we changed our if to a pattern match to compare {my_user, user} so we can prevent both my_user being nil and my_user and user being the same person. As for the HEEx change:

-<div :if={@current_user} class="my-4">
+<div :if={@current_user && @current_user.id != @user.id} class="my-4">

That should cover all cases.

Don't forget the tests

How do we test a LiveView with a button click? How do we test whether being authenticated or not and whether I'm the same user on that page or not? In all tests that required a user so far we did this:

describe "Show" do
  setup [:create_user]

  test "displays user", %{conn: conn, user: user} do
    {:ok, _show_live, html} = live(conn, ~p"/users/#{user}")

    assert html =~ "This is a player on this app"
    assert html =~ user.email
  end
end

The setup [:create_user] will create a user for us and pass it under our context at line 4 so we can immediately go to its page. :create_user does not authenticates us. If we change that to setup [:register_and_log_in_user] it will authenticate us and our context user will be ourselves so we can use this to go to our own page. Let's add a test for that. Go to test/champions_web/live/user_live_test.exs and add this suite:

describe "Authenticated Show" do
  setup [:register_and_log_in_user]

  test "displays my own user but no action buttons", %{conn: conn, user: user} do
    {:ok, _show_live, html} = live(conn, ~p"/users/#{user}")

    assert html =~ "This is a player on this app"
    assert html =~ user.email
    refute html =~ "I lost to this person"
    refute html =~ "Declare draw match"
  end
end

Now we should also be able to go to another user's page and see those buttons. Inside that describe block add this test:

test "displays another user with action buttons", %{conn: conn, user: _user} do
  other_user = user_fixture()
  {:ok, _show_live, html} = live(conn, ~p"/users/#{other_user}")

  assert html =~ "This is a player on this app"
  assert html =~ other_user.email
  assert html =~ "I lost to this person"
  assert html =~ "Declare draw match"
end

Now we should also verify that unauthenticated users can't see those buttons. Luckly we already have a describe for that! Here's how the full suite for this page ended up as:

describe "Authenticated Show" do
  setup [:register_and_log_in_user]

  test "displays my own user but no action buttons", %{conn: conn, user: user} do
    {:ok, _show_live, html} = live(conn, ~p"/users/#{user}")

    assert html =~ "This is a player on this app"
    assert html =~ user.email
    refute html =~ "I lost to this person"
    refute html =~ "Declare draw match"
  end

  test "displays another user with action buttons", %{conn: conn, user: _user} do
    other_user = user_fixture()
    {:ok, _show_live, html} = live(conn, ~p"/users/#{other_user}")

    assert html =~ "This is a player on this app"
    assert html =~ other_user.email
    assert html =~ "I lost to this person"
    assert html =~ "Declare draw match"
  end
end

describe "Show" do
  setup [:create_user]

  test "displays user", %{conn: conn, user: user} do
    {:ok, _show_live, html} = live(conn, ~p"/users/#{user}")

    assert html =~ "This is a player on this app"
    assert html =~ user.email
+   refute html =~ "I lost to this person"
+   refute html =~ "Declare draw match"
  end
end

But we forgot to test our actions! Before we do that we are going to do two small HTML tweaks that will make our testing live easier. We are going to add tags to help us find the number of points users have inside our HTML. Inside show.ex change this line:

-<:item title="Points"><%= @user.points %></:item>
+<:item title="Points"><span data-points><%= @user.points %></span></:item>

And inside app.html.heex change this line:

<li class="text-[0.8125rem] leading-6 text-zinc-900">
  <%= @current_user.email %>
- (<%= @current_user.points %> points)
+ <span data-my-points>(<%= @current_user.points %> points)</span>
</li>

First, add an alias to Champions.Accounts on the top of our user_live_test.exs file. We are going to be using it to check the state of things in the database.

defmodule ChampionsWeb.UserLiveTest do
  use ChampionsWeb.ConnCase

+ alias Champions.Accounts
  import Phoenix.LiveViewTest
  import Champions.AccountsFixtures
...

From now on we will add tests to "Authenticated Show". Here's how you can trigger a click action from LiveView:

test "concede 3 points when I lose to another player", %{conn: conn, user: _user} do
  other_user = user_fixture()
  {:ok, show_live, _html} = live(conn, ~p"/users/#{other_user}")

  assert other_user.points == 0
  assert show_live |> element("button", "I lost to this person") |> render_click()
  assert element(show_live, "span[data-points]") |> render() =~ "3"
  assert Accounts.get_user!(other_user.id).points == 3
end

This time we use new helpers from LiveViewTest. First, we need to locate the button so we use element/3 to locate a <button> with a certain text. After that, we use render_click/2 to trigger our event. After that, we use element/3 again on our LiveView to find the span[data-points] we just added to see if the value 3 appears there, this ensures our LiveView is updating the UI. The last test line gets the latest state of the other user and asserts it should be 3. Time to add the draw match test:

test "concede 1 point to each user when there's a draw match", %{conn: conn, user: user} do
  other_user = user_fixture()
  {:ok, show_live, _html} = live(conn, ~p"/users/#{other_user}")

  assert user.points == 0
  assert other_user.points == 0
  assert show_live |> element("button", "Declare draw match") |> render_click()
  assert element(show_live, "span[data-my-points]") |> render() =~ "1"
  assert element(show_live, "span[data-points]") |> render() =~ "1"
  assert Accounts.get_user!(user.id).points == 1
  assert Accounts.get_user!(other_user.id).points == 1
end

Very similar to the previous test but we add checks for the logged-in user too. At this point, we should be very confident our tests cover the important bits of our user interactions. Now let's spend a bit of our time on optimization.

Refactoring because we can

Now that we have unit tests that ensure our system work we have room for some refactoring without having the trouble of manual testing every step of the way. Whenever we change something just run mix test and you should be good to go. I've saved some cool things just for now.

The first thing we can notice is that both handle_event/3 have the same check for users being logged in and users being different. We can use pattern matching to make that simpler! Let's start with one:

@impl true
+def handle_event(_event_name, _value, %{assigns: %{current_user: nil}} = socket) do
+ {:noreply, put_flash(socket, :error, "You must be a player to do that!")}
+end
+
def handle_event("concede_loss", _value, socket) do
  socket =
    case {socket.assigns.current_user, socket.assigns.user} do
-     {nil, _user} ->
-       put_flash(socket, :error, "You must be a player to do that!")
-
      {%{id: my_id}, %{id: other_id}} when my_id == other_id ->
        put_flash(socket, :error, "You can't give points to yourself")

      {_my_user, user} ->
        {:ok, updated_user} = Accounts.update_user_points(user, user.points + 3)
        assign(socket, :user, updated_user)
    end

  {:noreply, socket}
end

def handle_event("concede_draw", _value, socket) do
  socket =
    case {socket.assigns.current_user, socket.assigns.user} do
-     {nil, _user} ->
-       put_flash(socket, :error, "You must be a player to do that!")
-
      {%{id: my_id}, %{id: other_id}} when my_id == other_id ->
        put_flash(socket, :error, "You can't give points to yourself")

      {my_user, user} ->
        {:ok, updated_user} = Accounts.update_user_points(user, user.points + 1)
        {:ok, updated_my_user} = Accounts.update_user_points(my_user, my_user.points + 1)
        socket
        |> assign(:user, updated_user)
        |> assign(:current_user, updated_my_user)
    end

  {:noreply, socket}
end

We added a clause for any handle_event/3 on the top that ignores the _event_name and matches if current_user is nil. If it is, stop everything and put_flash that error message. With that simple addition, we already traded 4 duplicated lines with 3 lines that should be easier to read. It's not really about the line count, it's all about being able to easily see that this first clause has an important meaning for all the events below. Let's do the same for the other error condition. Here's the final product:

@impl true
def handle_event(_event_name, _value, %{assigns: %{current_user: nil}} = socket) do
  {:noreply, put_flash(socket, :error, "You must be a player to do that!")}
end

def handle_event(_event_name, _value, %{assigns: %{current_user: current_user, user: user}} = socket)
 when current_user.id == user.id do
 {:noreply, put_flash(socket, :error, "You can't give points to yourself")}
end

def handle_event("concede_loss", _value, %{assigns: %{user: user}} = socket) do
  {:ok, updated_user} = Accounts.update_user_points(user, user.points + 3)
  {:noreply, assign(socket, :user, updated_user)}
end

def handle_event("concede_draw", _value, %{assigns: %{current_user: current_user, user: user}} = socket) do
  {:ok, updated_user} = Accounts.update_user_points(user, user.points + 1)
  {:ok, updated_my_user} = Accounts.update_user_points(current_user, current_user.points + 1)
  {:noreply,
    socket
    |> assign(:user, updated_user)
    |> assign(:current_user, updated_my_user)
  }
end

Summary

phx-click works for sending events from HTML to your LiveView.
LiveView events are caught by handle_event/3 which takes 3 arguments: event name, value, and the socket.
Being able to read LiveView errors will help you creating your applications.
You can access assigns from socket.assigns including current_user to get data about yourself if you're logged in.
root.html.heex never updates based on assigns except for page_title. app.html.heex will be updated if they use assigns.
Dead Views and LiveViews can opt out of using app.html.heex if they need.
To verify that your user is logged in, check for socket.assigns.current_user.
You can add :if={condition} to HTML tags to make HEEx render or not them.
You should not trust hiding buttons from unauthorized users directly on HEEx, you should validate your events callbacks.
You can use put_flash/3 to send messages to your user.
LiveView comes with useful helper functions for tests ranging from getting elements on the screen to clicking buttons.
You can create handle_event/3 clauses to handle errors for all events below them b simply ignoring the event name.
You can keep your mind at easy refactoring your code if you have a good battery of tests. mix test can be your best friend.

The Lazy Programmer's Intro to LiveView: Chapter 6

Lubien — Sun, 18 Jun 2023 15:07:39 +0000

Go to Chapter 1

Creating the user page

Now that we have a way to list users in our application we should add a page that shows just one of them so later we can add features such as 'request match'. This chapter be very similar to the previous one with very few additions, you will be able to exercise more of the basics of LiveView that way.

Creating the route

live_session :current_user,
  on_mount: [{ChampionsWeb.UserAuth, :mount_current_user}] do
  live "/users/confirm/:token", UserConfirmationLive, :edit
  live "/users/confirm", UserConfirmationInstructionsLive, :new
  live "/users", UserLive.Index, :index
+ live "/users/:id", UserLive.Show, :show
end

Back to the router.ex add a new route just beside your UserLive.Index. This time, since we are talking about a single user, we are going to call the module UserLive.Show using the :show action. If you pay attention to the URL you're going to see a variable there: :id. Phoenix calls those variables in the URL params.

Using params for the first time

Inside lib/champions_web/live/user_live/show.ex paste the following code:

defmodule ChampionsWeb.UserLive.Show do
  use ChampionsWeb, :live_view

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

  @impl true
  def handle_params(_params, _session, socket) do
    {:noreply,
     socket
     |> assign(:page_title, "Show user")}
  end

  @impl true
  def render(assigns) do
    ~H"""
    <div>I'm a user</div>
    """
  end
end

This time we are looking at handle_params/3 a new LiveView callback. This callback is specifically meant to handle your LiveView params both when your view starts but also when those params change as we will be seeing in later chapters.

In short and omitting some cool details for now, that's the cycle of callbacks before your view is first rendered. Whenever you need to use params, you should prefer to use handle_params. One thing worth noting here: our mount/3 does absolutely nothing, it just returns {:ok, socket} so it's fine to delete it. How can we get the id from params then?

defmodule ChampionsWeb.UserLive.Show do
  use ChampionsWeb, :live_view

- @impl true
- def mount(_params, _session, socket) do
-   {:ok, socket}
- end

  @impl true
- def handle_params(_params, _session, socket) do
+ def handle_params(%{"id" => id}, _session, socket) do
    {:noreply,
     socket
-    |> assign(:page_title, "Show user")}
+    |> assign(:page_title, "Showing user #{id}")
+    |> assign(:id, id)}
  end

  @impl true
  def render(assigns) do
    ~H"""
-   <div>I'm a user</div>
+   <div>I'm the user <%= @id %></div>
    """
  end
end

Instead of ignoring our params using the _ operator at the start of its name we changed the first argument of handle_params/3 to receive a Map that contains the key "id" and pattern matched it out. Now we have a variable id so we used that to update the page_title assign to be more specific and even created a new assign called id to be used on our render function as @id. So far we haven't actually fetched the user though.

defmodule ChampionsWeb.UserLive.Show do
  use ChampionsWeb, :live_view

+ alias Champions.Accounts

  @impl true
  def handle_params(%{"id" => id}, _session, socket) do
+   user = Accounts.get_user!(id)
    {:noreply,
     socket
-    |> assign(:page_title, "Showing user #{id}")
+    |> assign(:page_title, "Showing user #{user.email}")
-    |> assign(:id, id)}
+    |> assign(:user, user)}
  end

  @impl true
  def render(assigns) do
    ~H"""
-   <div>I'm the user <%= @id %></div>
+   <div>I'm the user <%= @user.email %></div>
    """
  end
end

The first thing we needed to do was an alias to Champions.Accounts so we won't need to write Champions. when we use the Accounts context. After that we used Accounts.get_user!/1, a function created by Phoenix auth generator. We then updated our page_title to be more descriptive and changed from using an id assignment to an user assignment. Let's make this page slightly prettier. Change your render function to this:

@impl true
def render(assigns) do
  ~H"""
  <.header>
    User <%= @user.id %>
    <:subtitle>This is a player on this app.</:subtitle>
  </.header>

  <.list>
    <:item title="Email"><%= @user.email %></:item>
    <:item title="Points"><%= @user.points %></:item>
  </.list>

  <.back navigate={~p"/users"}>Back to users</.back>
  """
end

You already know about the <.header> component albeit you're seeing how to use <:subtitle> inside it now but there are also two new components here for you and both come from Phoenix by default too. The first one is <.list> which is kinda like a horizontal table but instead of each row being an element on a list we use manually add each row using <:item>. Also, another fun component to use is <.back> which will simulate a back button press to the appointed path passed to it's navigate property.

Oh no, we just realized we have a way from going from /users/:id to /users but we don't have the other way around. Our users are in trouble. Let's go back to lib/champions_web/live/user_live/index.ex:

@impl true
def render(assigns) do
  ~H"""
  <.header>
    Listing Users
  </.header>

  <.table
    id="users"
    rows={@streams.users}
+   row_click={fn {_id, user} -> JS.navigate(~p"/users/#{user}") end}
  >
    <:col :let={{_id, user}} label="Email"><%= user.email %></:col>
    <:col :let={{_id, user}} label="Points"><%= user.points %></:col>
  </.table>
  """
end

Phoenix got you covered. The <.table> component can receive an row_click attribute that receives a function that takes a single argument {id, element} and you can use JS.navigate/1 to change into the user page.

Adding tests!

Let's get back to test/champions_web/live/user_live_test.exs and add a new test suite:

describe "Show" do
  setup [:create_user]

  test "displays user", %{conn: conn, user: user} do
    {:ok, _show_live, html} = live(conn, ~p"/users/#{user}")

    assert html =~ "This is a player on this app"
    assert html =~ user.email
  end
end

Nothing really magical here, we just go straight to the page and verify that the information that should be there is there.

Summary

Phoenix routes can receive variables using the :param_name syntax inside it's URL.
Params are passed to LiveViews inside both mount/3 and handle_params/3. They are run in that order before our render function.
Devs should prefer using params on handle_params/3 because it's aware of when params change in some specific cases we will dive in later.
Phoenix comes with a <.list> component for horizontal lists and <.back> for navigating back through pages.
The <.table> component can receive an row_click attribute to handle clicks on rows. We used that to navigate from the users list to the user page.

Read chapter 7: Conceding points to the winner

The Lazy Programmer's Intro to LiveView: Chapter 5

Lubien — Sun, 18 Jun 2023 15:07:35 +0000

Go to Chapter 1

Listing our users

Before it's possible for users to create matches between themselves they must at least be able to know who else is on the platform. For this, we are going to build a user list page.

Creating `Accounts.list_users`

Now you should be aware how to add a new context function so let's speedrun through it. Head out to accounts.ex and add this function:

@doc """
List users.

## Examples

    iex> list_users()
    [%User{}]

"""
def list_users() do
  Repo.all(User)
end

Unlike the previous function we created this time we are using Repo.all/2 to list all entries on the table corresponding to the User model. That should be enough for now. Let's add a new unit test to account_test.exs:

describe "list_users/0" do
  test "show all users on our system" do
    user = user_fixture()
    assert [^user] = Accounts.list_users()
  end
end

The cool thing about the code above is that the assertion above just says 'create an user then listing users should return that exact same user' using the amazing pin operator (^). In case you never seen it in action, definitely take a look later. This should be enough for our context for now.

Creating your first new route

So far you got new routes for free using generators. Time to do it by hand. The first thing you want to check is your router.ex file under champions_web. There's a ton of new things here but to start simple, look for live_session :current_user, and we are going to put our new route there.

live_session :current_user,
  on_mount: [{ChampionsWeb.UserAuth, :mount_current_user}] do
  live "/users/confirm/:token", UserConfirmationLive, :edit
  live "/users/confirm", UserConfirmationInstructionsLive, :new
+ live "/users", UserLive.Index, :index
end

Since we will be creating a LiveView we used the live/4 macro. The arguments we pass are the route path name, the LiveView file name and the live action. Since the LiveView we passed is called UserLive.Index that means we must define a module called ChampionsWeb.UserLive.Index. As for the live action it could be any atom but it's recommended to use :index, :show, :edit, :new, :create and :update whenever possible. We will take a look on them over the project's progress.

Creating the your first LivView

Create the lib/champions_web/live/user_live folder then make a file called index.ex. Let's start by creating your first LiveView ever.

defmodule ChampionsWeb.UserLive.Index do
  use ChampionsWeb, :live_view

  @impl true
  def render(assigns) do
    ~H"""
    <div>Hello LiveView</div>
    """
  end
end

This is the minimal LiveView module you can create to show a Hello World. First of all, the module name is important: it should match what you defined inside router.ex to the letter prepended by ChampionsWeb. The second line contains the use macro to import useful things for LiveView modules defined under ChampionsWeb. If you're curious open champions_web.ex and look for def live_view do, we will talk about this at another time.

The real start of the module above really is the render/1 function. All LiveViews must have a render function that takes exactly one argument called assigns. Those functions often return a HEEx markup delimited by the H sigil (often wrote as ~H"""). This time it only returns a single div. Open http://localhost:4000/users to see this working.

Giving the page a title

LiveViews separate state management from view rendering. The rule of thumb is that your render function should only know how to render whatever it is in your assigns and the other LiveView functions, known as callbacks, are responsible of managing the state you need.

To get started let's meet your first LiveView callback: mount/3. This callback is responsible often for starting the initial state of your view and also is likely to fetch data from the server. Let's start with the simplest scenario.

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

This mount/3 callback receives parameters from the URL, the session state and the socket but ignore everything but the socket. All mount/3 must return a tuple with :ok as the first element and a socket as the second argument. Sockets maintain the state of your LiveView. We will talk more about that over time. The current state of that callback is the same as it didn't exist, it does nothing.

If you are on /users and look at your tab name you're going to see something generic including the name of your app. Let's improve that. Update your mount/3 callback to this:

@impl true
def mount(_params, _session, socket) do
  {:ok,
    socket
    |> assign(:page_title, "Listing Users")
  }
end

Now instead of returning the socket as-is we used assign/3 to assign page_title to your socket state. Why page_title? This assign is used by root.html.heex to generate your HTML <title> tag. Looking at your tab name should show 'Listing Users · Phoenix Framework' now. You'll notice we will be adding page_title assign to most if not all pages from now on.

Using streams to list users

Recently LiveView added a new memory efficient way of handling collections of data: streams. For the sake of this chapter will overly simplify things and just say streams are used for lists of things. They behave a lot like assigns: you defined them on callbacks and your render function renders them. Let's rewrite out module:

defmodule ChampionsWeb.UserLive.Index do
  use ChampionsWeb, :live_view

  alias Champions.Accounts

  @impl true
  def mount(_params, _session, socket) do
    {:ok,
      socket
      |> assign(:page_title, "Listing Users")
      |> stream(:users, Accounts.list_users())
    }
  end

  @impl true
  def render(assigns) do
    ~H"""
    <.header>
      Listing Users
    </.header>

    <.table
      id="users"
      rows={@streams.users}
    >
      <:col :let={{_id, user}} label="Email"><%= user.email %></:col>
      <:col :let={{_id, user}} label="Points"><%= user.points %></:col>
    </.table>
    """
  end
end

The first step to create a stream is, just like assigns, add it to the socket. With line 11 we create @streams.users containing the list of all users in our platform. Phoenix comes packed with a component called <.table> that is aware of streams and can render those just fine. All you need to do is pass two parameters to it: id and rows.

Inside the <.table> we can spot two <:col> slots, each representing a single column on our table. In short those part of the <.table> component as we used them to render each item from our stream. There's also the <.header> component but that's very self explanatory. Your /users page should look something like this:

Testing your LiveView

It brings me so much joy to say that testing LiveViews are not only easy but support for it comes by default. Since our LiveView file is lib/champions_web/live/user_live/index.ex our test file will live in test/champions_web/live/user_live_test.exs.

defmodule ChampionsWeb.UserLiveTest do
  use ChampionsWeb.ConnCase

  import Phoenix.LiveViewTest
  import Champions.AccountsFixtures

  defp create_user(_) do
    user = user_fixture()
    %{user: user}
  end

  describe "Index" do
    setup [:create_user]

    test "lists all users", %{conn: conn, user: user} do
      {:ok, _index_live, html} = live(conn, ~p"/users")

      assert html =~ "Listing Users"
      assert html =~ user.email
    end
  end
end

The whole magic lies in live/2 from the Phoenix.LiveViewTest module. All you need to do is pass a conn, which already comes ready for tests that use ChampionsWeb.ConnCase and a route such as ~p"/users". The return value is a 3-tuple of :ok, a reference to the LiveView so we could do things like navigation or clicking buttons, and last but not least the rendered HTML so far. For this test all we need to do is check if the title and HTML contain what we expect such as the user email and the title on our render function.

Summary

Using Repo.all/2 its possible to query all items from an Ecto model.
To add new pages to Phoenix always start with the router.ex
Phoenix routes map to modules such as live "/users", UserLive.Index, :index mapping to ChampionsWeb.UserLive.Index
It's a common practice to call route actions as :index, :new, :create, :edit, :update and :delete but any other atom works such as :confirm_email.
To create a LiveView you start with creating the render function.
Render functions always take one argument: assigns.
LiveView manages the state via callback functions.
We can use the mount/3 callback to create the initial state of our LiveView.
Assigning something to page_title change the value of the <title> tag because that's used on root.html.heex
Assigns are just variables accessible on the LiveView render function using @assign_name.
Streams are how LiveView handles collections of data in a memory-efficient manner. Usually used for lists.
Streams are very like assigns: you defined and manage them on callbacks then use them on the render function as @streams.stream_name.
Phoenix comes with helper components such as <.header> and <.table>.
The <.table> component does all the stream's magic so we can learn that later.
Testing a LiveView can be quite easy with the live/2 helper.

Read chapter 6: Creating the user page

The Lazy Programmer's Intro to LiveView: Chapter 4

Lubien — Sun, 18 Jun 2023 15:06:39 +0000

Go to Chapter 1

Adding points to users

In the previous chapter, we just added the points column to users table. We need a way to add points to users. This time we are going to learn how to use Ecto to modify rows in our database.

Ecto Changesets 101

Ecto comes with a powerful abstraction to validate and map data from user input to the database, it's called Ecto.Changeset. Think of it as an intermediate state between user input and actually storing the data.

User inputs usually come in the form of an Elixir map (a key-value structure) such as %{"points" => 10}. Since we want to make changes, we must change something. If you wanted to update an existing user, you first need to get that user then you'd have a variable with a value such as %User{email: "…", …}. Combine both with a change_* function and we have a changeset. Let's do it from scratch!

Since we are going to make a function that modifies our users it makes sense to use the accounts.ex context and since this is related to our Ecto model we will also be modifying our user.ex file too. With the same reasoning that means we will be testing this at accounts_test.exs.

Head out to lib/champions/accounts/user.ex. You'll notice there are multiple *_changeset named functions with specific intents. Scroll to the bottom and create a new function called points_changeset/2.

@doc """
A user changeset to update points
"""
def points_changeset(user, attrs) do
  user
  |> cast(attrs, [:points])
  |> validate_required([:points])
  |> validate_number(:points, greater_than_or_equal_to: 0)
end

There's a lot to unpack so let's go bit by bit. We use @doc to give this function a nice documentation for the developers of the future who want to use this. Following that we define a function that takes two arguments: the user to be modified and the new data on the attrs variable.

The fun comes with the pipes. It's all about transformation. On line 5 we start with the user as-is. On line 6 we use cast/4 to convert the user into a changeset but we limit the attrs to only read points changes and ignore everything else. Next, we do two validations: we want to make points mandatory and it should be a non-negative integer. By the end of this pipe chain, we have a validated changeset without any trouble at all.

Then, we need to expose this function to our Accounts context. Head out to lib/champions/accounts.ex and create a new function in the end called change_user_points/2.

@doc """
Returns an `%Ecto.Changeset{}` for tracking user changes.

## Examples

    iex> change_user_points(user)
    %Ecto.Changeset{data: %User{}}

"""
def change_user_points(%User{} = user, attrs \\ %{}) do
  User.points_changeset(user, attrs)
end

As you can see this is just an alias to the changeset contained in the Ecto model. Making your context module the place to talk to the external world (your_app_web) is a good practice. Last but not least, we need to test that this actually works. go to test/champions/accounts_test.exs and add a new test case in the end:

describe "change_user_points/2" do
  test "accepts non-negative integers" do
    assert %Ecto.Changeset{} = changeset = Accounts.change_user_points(%User{}, %{"points" => -1})
    refute changeset.valid?

    assert %Ecto.Changeset{} = changeset = Accounts.change_user_points(%User{}, %{"points" => 0})
    assert changeset.valid?

    assert %Ecto.Changeset{} = changeset = Accounts.change_user_points(%User{}, %{"points" => 10})
    assert changeset.valid?
  end
end

With this test, we pass an empty user and a negative, zero, and positive amount of points. Note that at all times it returns an Ecto.Changeset, what changes is that if it's invalid the changeset valid? property will be false.

Applying changesets using Repo

Whenever an Ecto user wants to apply changes to the database they must go through a Repo. Think of those as abstractions between Elixir and the database itself. You don't need to handle creating connections, recovering from disconnections, writing SQL, and many other things because Repo will take care of that for you alongside your changeset. Since Phoenix by default comes with Postgres support you should have a Champions.Repo module ready to be used at any time, otherwise not even the migrations would have worked.

Let's create a high-level function on Accounts that takes a user and a number of points and updated the user points. Inside accounts.ex create a new function update_user_points/2:

@doc """
Updates the current number of points of a user

## Examples

    iex> update_user_points(user, 10)
    {:ok, %User{points: 10}}

"""
def update_user_points(%User{} = user, points) do
  user
  |> change_user_points(%{"points" => points})
  |> Repo.update()
end

The only new thing here is that there's a pipe after the changeset that calls Repo.update/2 to trigger the changes to the database. In summary, the changeset works as a mapping of what needs to be done in the database and Repo actually applies those changes. To test this out add a new unit test to accounts_test.exs:

describe "set_user_points/2" do
  setup do
    %{user: user_fixture()}
  end

  test "updates the amounts of points of an existing user", %{user: user} do
    {:ok, updated_user} = Accounts.update_user_points(user, 10)
    assert updated_user.points == 10
  end
end

A cool thing worth mentioning here is that out is that the Phoenix auth generator also created the helper user_fixture/1 function that creates a user with zero trouble so your unit tests can be DRY.

Summary

To store data in the database Ecto uses changesets.
Changesets validate and prepare which data can go to the database, you can even have more than one per Ecto model. Ecto.Changeset comes with useful validation functions.
Repo is how Ecto talks to the database.
Repo.update/2 reads a changeset and applies changes to the database.

Read chapter 5: Listing our users

The Lazy Programmer's Intro to LiveView: Chapter 3

Lubien — Sun, 18 Jun 2023 15:04:23 +0000

Go to Chapter 1

Adding a points system

From the very beginning, I mentioned this project is all about competition, which means we need a way to say a user has a certain amount of points. In this chapter, we are going to create the simplest and dumbest point system so we can use this as an excuse to learn more about what Phoenix auth generator created for us.

The modeling is pretty simple: we are going to add a points column to the users table and in the meantime, we are going to learn some Ecto.

What are migrations?

If you know what migrations are, skip this section, it's meant for beginners.

Development teams need a way of synchronizing changes to their databases. Migrations is a simple technique where all changes to the database are expressed as a migration file that contains the change. If we want to add a column, we need to create a migration file that says 'Please add a column points to my table users with type integer'. This file will be committed to the project and all developers will be able to run it and make their databases be on the latest state. We call applying one or more migrations 'migrating the database'. Remember that after running mix phx.gen.auth we needed to do mix ecto.migrate? That's it.

Migrations also need to be reversible in case something goes wrong. Using the example above the reverse command would be 'Please remove the column points from the table users'. We call reversing one or more migrations doing a 'rollback of the database'. Say you messed up your mix phx.gen.auth and created a table called userss, you could easily undo the error with mix ecto.rollback.

Usually, web frameworks come with migrations support such as Rails' Active Record, Phoenix uses Ecto and AdonisJS Lucid. Some frameworks don't come with anything related to databases such as ExpressJS so you'd need to install something like Sequelize which has migrations support too.

Here's what a migration file looks like in AdonisJS:

// database/migrations/1587988332388_users.js
import BaseSchema from '@ioc:Adonis/Lucid/Schema'

export default class extends BaseSchema {
  protected tableName = 'users'

  public async up() {
    this.schema.createTable(this.tableName, (table) => {
      table.increments('id')
      table.timestamp('created_at', { useTz: true })
      table.timestamp('updated_at', { useTz: true })
    })
  }

  public async down() {
    this.schema.dropTable(this.tableName)
  }
}

As you can see there's an up and down method to teach how to migrate and how to rollback. Also notice the filename uses a timestamp: the reason for that is so migrations must be run in the order they were created to ensure consistency.

Now that you know how roughly a migration looks like and what they're used for, let's get to what matters, Ecto.

Migrations with Ecto

Ecto migrations are slightly different. They (most of times) don't need to define up and down methods because the syntax is very aware of how to migrate and rollback it. Let's take the users migrations for example:

# 20230617121436_create_users_auth_tables.exs
defmodule Champions.Repo.Migrations.CreateUsersAuthTables do
  use Ecto.Migration

  def change do
    execute "CREATE EXTENSION IF NOT EXISTS citext", ""

    create table(:users) do
      add :email, :citext, null: false
      add :hashed_password, :string, null: false
      add :confirmed_at, :naive_datetime
      timestamps()
    end

    create unique_index(:users, [:email])

    create table(:users_tokens) do
      add :user_id, references(:users, on_delete: :delete_all), null: false
      add :token, :binary, null: false
      add :context, :string, null: false
      add :sent_to, :string
      timestamps(updated_at: false)
    end

    create index(:users_tokens, [:user_id])
    create unique_index(:users_tokens, [:context, :token])
  end
end

There's no up and down, just a change method. This means we are confident Ecto can do and undo things with whatever we do there. To make it easier to understand let's break down its blocks:

execute "CREATE EXTENSION IF NOT EXISTS citext", ""

The execute/2 function works as up and down. The first SQL statement is the up case and the second one is the down. This specific statement says 'When you migrate this, please create the extension citext if it does not exist' and the empty string as the second argument means 'don't do anything during rollbacks'.

create table(:users) do
  add :email, :citext, null: false
  add :hashed_password, :string, null: false
  add :confirmed_at, :naive_datetime
  timestamps()
end

This block tells ecto to create this table during migration and delete it during rollbacks. It's all under the hood because of the create/2 function combined with table/2 function. Inside the do block we can see we ask for 5 fields to be added:

An email of citext (case insensitive text) type non-nullable field.
A hashed_password string type non-nullable field.
A confirmed_at naive datetime (not aware of timezones) nullable field.
timestamps/1 creates inserted_at and updated_at, both naive datetime non-nullable fields with default values to what their names point at.

create unique_index(:users, [:email])
# other things here
create index(:users_tokens, [:user_id])
create unique_index(:users_tokens, [:context, :token])

As the name implies, the first unique_index/3 will create on migration and delete on rollback a unique index for the users table under email only. index/3 will generate a regular index and the second unique_index/3 is a composite index under context and token.

create table(:users_tokens) do
  add :user_id, references(:users, on_delete: :delete_all), null: false
  add :token, :binary, null: false
  add :context, :string, null: false
  add :sent_to, :string
  timestamps(updated_at: false)
end

You should already be able to understand most of what's happening here but the new things are references/2 used to create a foreign key from users_tokens to users which will make rows from the tokens table be deleted if the foreign key in users is deleted and the fact that this table opts-out of updated_at since tokens are never updated.

For more details on Ecto migrations, I recommend reading their Ecto SQL Ecto.Migration docs and guides but in case you want to learn the possible types for your columns head out to Ecto docs under Ecto.Schema. Yes, those are two different docs because Ecto does not necessarily means you need to use one of the default Ecto SQL databases, you could use Mongo adapter or even something like ClickHouse which is also SQL.

Creating our first migration by hand

$ mix help ecto.gen.migration

                             mix ecto.gen.migration                             

Generates a migration.

The repository must be set under :ecto_repos in the current app configuration
or given via the -r option.

## Examples

    $ mix ecto.gen.migration add_posts_table

Once more generators come to the rescue. We could write it by hand but you'd be having to figure out the current timestamp, write some boilerplate code and all that is boring, let Ecto do that for you. The migration name doesn't impact it's effect but it's nice to be clear what you're going to do:

$ mix ecto.gen.migration add_users_points
* creating priv/repo/migrations/20230617145124_add_users_points.exs

The default code should be something like:

defmodule Champions.Repo.Migrations.AddUsersPoints do
  use Ecto.Migration

  def change do

  end
end

Our only migration so far had used create to create/delete a database table for us, what if we just want to add a column? alter/2 comes to the rescue.

defmodule Champions.Repo.Migrations.AddUsersPoints do
  use Ecto.Migration

  def change do
    alter table(:users) do
      add :points, :integer, default: 0, null: false
    end
  end
end

No specific up and down needed, Ecto knows how to do these for you. We will be creating a field called points that default to 0 and can't be null. Let's run this migration. Here's a fun fact: if you pass --log-migrations-sql you can see the SQL queries being run:

$ mix ecto.migrate --log-migrations-sql

11:58:05.588 [info] == Running 20230617145124 Champions.Repo.Migrations.AddUsersPoints.change/0 forward

11:58:05.590 [info] alter table users

11:58:05.625 [debug] QUERY OK db=9.6ms
ALTER TABLE "users" ADD COLUMN "points" integer DEFAULT 0 NOT NULL []

11:58:05.626 [info] == Migrated 20230617145124 in 0.0s

Alright, that should do… For our Postgres database at least. We still need to teach Ecto how to map this column to Elixir. Head out to lib/champions/accounts/user.ex and let's add it:

defmodule Champions.Accounts.User do
  use Ecto.Schema
  import Ecto.Changeset

  schema "users" do
    field :email, :string
    field :password, :string, virtual: true, redact: true
    field :hashed_password, :string, redact: true
    field :confirmed_at, :naive_datetime
    field :points, :integer, default: 0

    timestamps()
  end

  # more stuff
end

Since we 10x developers and we just added something meaningful to our code, we want to make sure we add tests for this! I didn't mention it to you but the Phoenix auth generator created a lot of test files. You can verify that with mix test:

$ mix test
................................................................................................................................
Finished in 1.9 seconds (0.6s async, 1.2s sync)
128 tests, 0 failures

Randomized with seed 490838

Let's keep it simple and edit an existing test. Head out to test/champions/accounts_test.exs and look for 'returns the user if the email exists'. A simple assertion should do:

test "returns the user if the email exists" do
  %{id: id} = user = user_fixture()
  assert %User{id: ^id} = Accounts.get_user_by_email(user.email)
+ assert user.points == 0
end

If running mix test still works, we are done with Ecto. At least for now.

Your first UI change

Our users cannot see how many points they have so far. We can tweak our layout to show their points beside their email. Headout to lib/champions_web/components/layouts/root.html.heex and look for <%= @current_user do %>.

<%= if @current_user do %>
  <li class="text-[0.8125rem] leading-6 text-zinc-900">
    <%= @current_user.email %>
+   (<%= @current_user.points %> points)
  </li>
...more stuff

HEEx: your new best friend

HEEx stands for HTML + Embedded Elixir. It's simply the way Phoenix uses to express HTML with Elixir code inside. There are a ton of amazing things behind the scenes to make HEEx a thing but we will defer talking about them to later. What you need to take away from it right now are a few key concepts:

Whenever you see a tag <%= elixir code here %> that elixir code will be rendered into the HTML.
To run Elixir code and not render anything in the HTML just omit the = sign such as <% x = 10 %>.
Any variable inside tags that starts with @ are called assigns. They're special and we will talk about them a lot over the next chapters. For now, we used the @current_user assign to render both the user email and points on the navbar.

For this change, we went to our root.html.heex file which contains the outermost HTML of our web page, including the HTML, header, and body tags. Later on, we will be learning more about layouts when it comes to creating multiple of them.

Summary

Most Ecto migration codes know how to be migrated and rollbacked without needing two different code paths.
Ecto timestamps function creates inserted_at and updated_at fields unless the code opts out of one.
mix ecto.gen.migration migration_name does the boilerplate bit of creating migration files with timestamps on names.
One must also update Ecto models after doing migrations so Ecto knows which fields are available.
HEEx is how Phoenix templates HTML for interfaces, it uses variables know as assigns with names that start with @ like @current_user.
HEEx has special tags for rendering HTML content from Elixir code <%= code %> and just running elixir code without rendering things <% x = 10 %>.
root.html.heex contains a simple navbar that shows who's the currently logged user.

Read chapter 4: Adding points to users

The Lazy Programmer's Intro to LiveView: Chapter 2

Lubien — Sun, 18 Jun 2023 15:03:07 +0000

Go to Chapter 1

Adding Authentication to Champions

Authentication and authorization are a pain in the ass. It always felt like the most boring thing ever when I started new projects. Luckily Phoenix comes with a simple yet powerful auth system built-in. In this chapter, we are going to learn how to use Phoenix Auth Generator, aka mix phx.gen.auth.

A quick tip for those who like details

We are very soon going to run a command that generates a few files and modifies existing ones. If you haven't created a git repository or committed your changes yet I strongly advise you to so you can use the diff to learn what changed.

$ git init
$ git add .
$ git commit -m Init

What does Champions App need?

If you recall the last chapter I mentioned that this project was meant for people to record matches between themselves. That means we need to know who you are. We are going to build a way one can simply register and log in to our app.

Meet `mix phx.gen.auth`

As previously mentioned, mix is also an automation tool for Elixir. The Phoenix framework added a few custom commands to help generate boilerplate Phoenix code that can go very far when you need to get things done. Feel free to run mix help if you want to list all possible mix commands. For now, we care only about one: mix phx.gen.auth.

$ mix help phx.gen.auth

                                mix phx.gen.auth                                

Generates authentication logic for a resource.

    $ mix phx.gen.auth Accounts User users

The first argument is the context module followed by the schema module and its
plural name (used as the schema table name).

Additional information and security considerations are detailed in the mix
phx.gen.auth guide (mix_phx_gen_auth.html).

# A lot more info below

Did you see what I just did? I ran mix help phx.gen.auth and got a ton of useful information. Feel free to do that whenever you feel lost before running a command. What we really care about now is the usage: mix phx.gen.auth Accounts User users. What are those 3 words that come after the command? I invite you to learn about…

Phoenix Contexts

Phoenix fundamentally uses an abstraction where you separate the bones of your code into 3 places:

Context modules: a place where you should put all your business logic.
Ecto Models: a place where you should bridge Elixir and your database.
Web modules: everything that handles user interactions ranging from HTML to JSON APIs.

A lot of Phoenix generator commands follow the structure: mix phx.gen.* [Context Name] [Model Name] [Model Table Name]. If we apply that knowledge into mix phx.gen.auth Accounts User users we have:

mix phx.gen.auth: Hey Phoenix, please generate an authentication system for me.
Accounts: let's call the context module Accounts, and put all my business logic there.
User: the Ecto model name for our users should be User, define its structure there.
users: and make sure the database table name is users.

mix phx.gen.auth Accounts User users
An authentication system can be created in two different ways:
- Using Phoenix.LiveView (default)
- Using Phoenix.Controller only
Do you want to create a LiveView based authentication system? [Yn] 
* creating priv/repo/migrations/20230617121436_create_users_auth_tables.exs
* creating lib/champions/accounts/user_notifier.ex
* creating lib/champions/accounts/user.ex
* creating lib/champions/accounts/user_token.ex
* creating lib/champions_web/user_auth.ex
* creating test/champions_web/user_auth_test.exs
* creating lib/champions_web/controllers/user_session_controller.ex
* creating test/champions_web/controllers/user_session_controller_test.exs
* creating lib/champions_web/live/user_registration_live.ex
* creating test/champions_web/live/user_registration_live_test.exs
* creating lib/champions_web/live/user_login_live.ex
* creating test/champions_web/live/user_login_live_test.exs
* creating lib/champions_web/live/user_reset_password_live.ex
* creating test/champions_web/live/user_reset_password_live_test.exs
* creating lib/champions_web/live/user_forgot_password_live.ex
* creating test/champions_web/live/user_forgot_password_live_test.exs
* creating lib/champions_web/live/user_settings_live.ex
* creating test/champions_web/live/user_settings_live_test.exs
* creating lib/champions_web/live/user_confirmation_live.ex
* creating test/champions_web/live/user_confirmation_live_test.exs
* creating lib/champions_web/live/user_confirmation_instructions_live.ex
* creating test/champions_web/live/user_confirmation_instructions_live_test.exs
* creating lib/champions/accounts.ex
* injecting lib/champions/accounts.ex
* creating test/champions/accounts_test.exs
* injecting test/champions/accounts_test.exs
* creating test/support/fixtures/accounts_fixtures.ex
* injecting test/support/fixtures/accounts_fixtures.ex
* injecting test/support/conn_case.ex
* injecting config/test.exs
* injecting mix.exs
* injecting lib/champions_web/router.ex
* injecting lib/champions_web/router.ex - imports
* injecting lib/champions_web/router.ex - plug
* injecting lib/champions_web/components/layouts/root.html.heex

Please re-fetch your dependencies with the following command:

    $ mix deps.get

Remember to update your repository by running migrations:

    $ mix ecto.migrate

Once you are ready, visit "/users/register"
to create your account and then access "/dev/mailbox" to
see the account confirmation email.

That is a huge diff. But don't be scared: let's talk about the main things you should care about immediately now.

The `lib/champions` directory

lib
├── champions
│   ├── accounts
│   │   ├── user.ex
│   │   ├── user_notifier.ex
│   │   └── user_token.ex
│   ├── accounts.ex
│   ├── application.ex
│   ├── mailer.ex
│   └── repo.ex
├── champions.ex

Since our project is called champions, inside the lib folder there's a folder with that very same name that will host our business logic. When we ran mix phx.gen.auth we choose the context and model names to be, respectively, Accounts and User. We can see that here where lib/champions/accounts.ex contains the context Champions.Accounts and inside lib/champions/accounts/user.ex there's our model Champions.Accounts.User. You might have noticed but the folder and module names match.

defmodule Champions.Accounts do
  def get_user_by_email(email) when is_binary(email) do
  def get_user_by_email_and_password(email, password)
  def get_user!(id), do: Repo.get!(User, id)
  def register_user(attrs) do
  def change_user_registration(%User{} = user, attrs \\ %{}) do
  def change_user_email(user, attrs \\ %{}) do
  def apply_user_email(user, password, attrs) do
  def update_user_email(user, token) do
  def deliver_user_update_email_instructions(%User{} = user, current_email, update_email_url_fun)
  def change_user_password(user, attrs \\ %{}) do
  def update_user_password(user, password, attrs) do
  def generate_user_session_token(user) do
  def get_user_by_session_token(token) do
  def delete_user_session_token(token) do
  def deliver_user_confirmation_instructions(%User{} = user, confirmation_url_fun)
  def confirm_user(token) do
  def deliver_user_reset_password_instructions(%User{} = user, reset_password_url_fun)
  def get_user_by_reset_password_token(token) do
  def reset_user_password(user, attrs) do
end

I've deleted a ton of code just so you can see the function names of our Accounts context purpose. When I said our business logic lives there I meant it. This context is all about doing things with user accounts. Ranging from getting data to sending recovery password emails, this will be very helpful in the future. Do note that this is just a plain Elixir module with a lot of functions, there's no magic that makes it a context, it's just a good practice on Phoenix. Later on, we will be creating more contexts and adding functions to existing ones so you can get more practice.

defmodule Champions.Accounts.User do
  use Ecto.Schema
  import Ecto.Changeset

  schema "users" do
    field :email, :string
    field :password, :string, virtual: true, redact: true
    field :hashed_password, :string, redact: true
    field :confirmed_at, :naive_datetime

    timestamps()
  end

  def registration_changeset(user, attrs, opts \\ []) do
  def email_changeset(user, attrs, opts \\ []) do
  def password_changeset(user, attrs, opts \\ []) do
  def confirm_changeset(user) do
  def valid_password?(%Champions.Accounts.User{hashed_password: hashed_password}, password)
  def validate_current_password(changeset, password) do
end

If you go to lib/champions/accounts/user.ex you're going to see something like the code above. Once more I've deleted the function code so it's easier to see what does it have. Notice it starts with a simple mapping of what our model contains: email, password, hashed_password and confirmed_at. You can also see there's timestamps() there, this macro adds two fields: inserted_at and updated_at. There's really a ton of unpacking here on the future but for now think of Ecto models as an abstraction to map our database data to Elixir and the other way around.

For now we will ignore the other files created on lib/champions and will talk about them as we need later.

The `lib/champions_web` folder

lib
├── champions_web
│   ├── components
│   │   ├── core_components.ex
│   │   ├── layouts
│   │   └── layouts.ex
│   ├── controllers
│   │   ├── error_html.ex
│   │   ├── error_json.ex
│   │   ├── page_controller.ex
│   │   ├── page_html/
│   │   ├── page_html.ex
│   │   └── user_session_controller.ex
│   ├── endpoint.ex
│   ├── gettext.ex
│   ├── live
│   │   ├── user_confirmation_instructions_live.ex
│   │   ├── user_confirmation_live.ex
│   │   ├── user_forgot_password_live.ex
│   │   ├── user_login_live.ex
│   │   ├── user_registration_live.ex
│   │   ├── user_reset_password_live.ex
│   │   └── user_settings_live.ex
│   ├── router.ex
│   ├── telemetry.ex
│   └── user_auth.ex
└── champions_web.ex

Phoenix likes to separate business logic from user interfaces, which includes both HTML and APIs. It's a good practice for you to learn how to separate your concerns between your app and app_web folders once you understand better. For now I'd like to draw your focus on on these folders:

components: here we put generic Phoenix Components that can be reused over our application such as custom button, form inputs, data tables etc.
controllers: here lies both API controllers (files ending with _json.ex) and plain HTML controllers (ending with _html.ex). Any HTML here is not a LiveView (known to some as dead views).
live: the name says all, our LiveViews will be stored here. Phoenix auth generator even created some for you. Each LiveView can be reused in one or more pages. We'll talk more about that later.

What we got after all?

We need to do two more things before we proceed: install the new dependencies (bcrypt_elixir) and migrate our database to create our users tables. Stop your server and run the following commands:

$ mix deps.get
Resolving Hex dependencies...
Dependency resolution completed:
# more stuff...
* Getting bcrypt_elixir (Hex package)
* Getting comeonin (Hex package)
* Getting elixir_make (Hex package)

champions on  main [!?] via 💧 v1.14.1 took 3s 
[I] ➜ mix ecto.migrate
# Code compiling
Generated champions app

10:51:19.938 [info] == Running 20230617121436 Champions.Repo.Migrations.CreateUsersAuthTables.change/0 forward

10:51:19.942 [info] execute "CREATE EXTENSION IF NOT EXISTS citext"

10:51:20.072 [info] create table users

10:51:20.116 [info] create index users_email_index

10:51:20.124 [info] create table users_tokens

10:51:20.152 [info] create index users_tokens_user_id_index

10:51:20.159 [info] create index users_tokens_context_token_index

10:51:20.176 [info] == Migrated 20230617121436 in 0.2s

Restart your server once more with mix phx.server, you should see two links to login and registration pages on the top right. Let's register our first user. After registering you should be automatically logged in. One neat feature you should look into immediately is that Phoenix comes with a fake mail delivery system. Head out to http://localhost:4000/dev/mailbox and you're going to see your email confirmation is there. Be aware that this is memory only, stopping/restarting the server will make your email preview be lost.

Phoenix auth comes bundled with the following features:

Login
Registration
Token-based sessions with token invalidation
Email confirmation
Password reset
Preview emails without having to setup anything locally
User settings page
Authenticated routes (we will talk a lot about this later)

Go nuts with it, test it all and enjoy how a single terminal command wrote so much code anyone would hate to do over and over again. When you're done, don't forget to commit it.

Summary

mix help COMMAND shows useful help for mix commands you don't know how to use.
mix phx.gen.auth setups an entire authentication system for your app with a single command.
Phoenix contexts are where you store your business logic.
Ecto models handle mapping your database data into Elixir data.
Phoenix separates your app into two folders: app_name for business logic and app_name_web for handling user interactions from APIs and HTML interfaces.

Read chapter 3: Adding a points system

The Lazy Programmer's Intro to LiveView: Chapter 1

Lubien — Sun, 18 Jun 2023 15:02:23 +0000

Chapters

Endgame source code: https://github.com/lubien/champions (update as I write chapters).

Introduction

If you're like me, you're lazy. When it comes to learning new things you rather take it incrementally than jump on docs and spend a lot of time learning what it takes to use this new thing. That's fine, I guess. I mean, worked for me so far. I love to learn things doing projects so I'd like to invite you to learn LiveView with me doing a side project.

This project is going to be called Champions. Back in the day one of the very first projects that I created that made it into production was a side project of mine where my friends could compete with each other and get points by winning matches. It was a very simple system where all you'd have to do was declare that you lost to someone and they'd get 3 points if they confirmed their win, each would win 1 point on a draw. It was a trust-based system but worked just fine for us.

In these guides, I'm going to teach you how to rebuild that very system using Phoenix LiveView. My goal is to teach you LiveView concepts over time rather than dumping a ton of context you might not need at first. For that, you could feel like I'm not telling you the full history but I promise you by the end of it you're going to be able to make your very own side projects with the knowledge you get from here.

I'll approach these chapters as if I was just doing the project by myself and talking to the voices in my head. That means I'm going to do things incrementally and at random times I'm just going to suddenly add new scope to the app or change the current scope on a whim. I hope with that that you'd get some experience on how to change things on LiveView as needed over time since life is not all about generators, you also need to learn how to maintain code.

One more thing I'll be during throughout the entire process is that I'm going to link the documentation from Elixir, Phoenix, and Phoenix LiveView as much as possible. Those just happen to be one of the very best docs I've ever consumed as a developer and they also come packed with guides so don't feel scared of opening links from there.

Getting started

I love when a new thing I'm learning has a 'Get Started' page. That's usually where the maintainers put the minimal info you'd need to use something. I like it so much that I'm doing this section right here.

First, I assume you've installed Elixir. I'm using 1.14.1 with Erlang/OTP 24 but anything higher should just work. If you never installed it I highly recommend you to do it using asdf, there's a ton of guides out there about it. If you're a Windows user, please make your life easier and use WSL to run everything. Another assumption I'm going to do is that you have PostgreSQL installed and running on your machine. We will be using it as our main database.

We will be using Phoenix 1.7.6 and that comes with LiveView v0.19.2 as of now. It was mentioned not much is going to change from LiveView as it's getting close to v1 so I'm confident I'm not going to need to rewrite this soon and you shouldn't be worried if you're reading this when Phoenix and LiveView are on higher versions.

Whenever I forget how to start a new Phoenix project all I have to do is go to https://www.phoenixframework.org/, click on Guides, and right on my left then open the 'Installation' page. To get the latest Phoenix installer run the command below.

$ mix archive.install hex phx_new
Resolving Hex dependencies...
Dependency resolution completed:
New:
  phx_new 1.7.6
* Getting phx_new (Hex package)
All dependencies are up to date
Compiling 11 files (.ex)
Generated phx_new app
Generated archive "phx_new-1.7.6.ez" with MIX_ENV=prod
Found existing entry: /Users/lubien/.asdf/installs/elixir/1.14/.mix/archives/phx_new-1.7.3
Are you sure you want to replace it with "phx_new-1.7.6.ez"? [Yn]
* creating /Users/lubien/.asdf/installs/elixir/1.14/.mix/archives/phx_new-1.7.6

As you can see I already had v1.7.3 and it upgraded it to v1.7.6. You're also going to see a lot of paths like /Users/lubien/.asdf/installs/elixir/1.14/ since I'm using asdf, don't worry about it. Let's create our project:

$ mix phx.new champions
* creating champions/config/config.exs
* creating champions/config/dev.exs
* creating champions/config/prod.exs
* creating champions/config/runtime.exs
* creating champions/config/test.exs
* creating champions/lib/champions/application.ex
* creating champions/lib/champions.ex
* creating champions/lib/champions_web/controllers/error_json.ex
* creating champions/lib/champions_web/endpoint.ex
* creating champions/lib/champions_web/router.ex
* creating champions/lib/champions_web/telemetry.ex
* creating champions/lib/champions_web.ex
* creating champions/mix.exs
* creating champions/README.md
* creating champions/.formatter.exs
* creating champions/.gitignore
* creating champions/test/support/conn_case.ex
* creating champions/test/test_helper.exs
* creating champions/test/champions_web/controllers/error_json_test.exs
* creating champions/lib/champions/repo.ex
* creating champions/priv/repo/migrations/.formatter.exs
* creating champions/priv/repo/seeds.exs
* creating champions/test/support/data_case.ex
* creating champions/lib/champions_web/controllers/error_html.ex
* creating champions/test/champions_web/controllers/error_html_test.exs
* creating champions/lib/champions_web/components/core_components.ex
* creating champions/lib/champions_web/controllers/page_controller.ex
* creating champions/lib/champions_web/controllers/page_html.ex
* creating champions/lib/champions_web/controllers/page_html/home.html.heex
* creating champions/test/champions_web/controllers/page_controller_test.exs
* creating champions/lib/champions_web/components/layouts/root.html.heex
* creating champions/lib/champions_web/components/layouts/app.html.heex
* creating champions/lib/champions_web/components/layouts.ex
* creating champions/priv/static/images/logo.svg
* creating champions/lib/champions/mailer.ex
* creating champions/lib/champions_web/gettext.ex
* creating champions/priv/gettext/en/LC_MESSAGES/errors.po
* creating champions/priv/gettext/errors.pot
* creating champions/priv/static/robots.txt
* creating champions/priv/static/favicon.ico
* creating champions/assets/js/app.js
* creating champions/assets/vendor/topbar.js
* creating champions/assets/css/app.css
* creating champions/assets/tailwind.config.js
* creating champions/assets/vendor/heroicons/LICENSE.md
* creating champions/assets/vendor/heroicons/UPGRADE.md
* extracting champions/assets/vendor/heroicons/optimized

Fetch and install dependencies? [Yn]
* running mix deps.get
* running mix assets.setup
* running mix deps.compile

We are almost there! The following steps are missing:

    $ cd champions

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

This could take a while but our Elixir and JavaScript dependencies will come ready to be used. In the meantime feel free to open your favorite code editor on your project. Do pay attention that in the end, it will show commands that are useful to be run at first. Let's enter our project directory and create our database.

$ cd champions

$ mix ecto.create
Compiling 15 files (.ex)
Generated champions app
The database for Champions.Repo has been created

Just in case you don't know, mix is the build and automation tool Elixir comes bundled with. Libraries such as Phoenix and Ecto can add commands to it. And now we see the first mention of Ecto. In short, it's the thing that lets you access databases. We will expand more on that later. If Postgres is not running on localhost on port 5432 with a user and password equal to postgres, you're going to see a database error when running mix ecto.create. In that case, feel free to open config/dev.exs and change the ecto config.

# config/dev.exs
import Config

# Configure your database
config :champions, Champions.Repo,
  username: "postgres",
  password: "postgres",
  hostname: "localhost",
  database: "champions_dev",
  stacktrace: true,
  show_sensitive_data_on_connection_error: true,
  pool_size: 10

# more stuff...

Time to start the server!

$ mix phx.server
[info] Running ChampionsWeb.Endpoint with cowboy 2.10.0 at 127.0.0.1:4000 (http)
[info] Access ChampionsWeb.Endpoint at http://localhost:4000
[watch] build finished, watching for changes...
Browserslist: caniuse-lite is outdated. Please run:
  npx update-browserslist-db@latest
  Why you should do it regularly: https://github.com/browserslist/update-db#readme

Rebuilding...

Done in 173ms.

Open http://localhost:4000 and you're going to see your app running.

Summary

Phoenix is the web framework, and LiveView is a library that comes with it by default.
mix archive.install hex phx_new installs or update your Phoenix CLI to create new projects.
mix phx.new project_name creates a new Phoenix project.
Phoenix uses Postgres by default for your database.
mix ecto.create creates your database.

Go to Chapter 2: Adding Authentication to Champions

Elixir mix + fzf = 💜🧪

Lubien — Sat, 09 Oct 2021 06:49:12 +0000

fzf is such a powerful tool when it comes to make your terminal experiences so much better. One thing I like about it is how easy it is to extend it's features and one could make auto completions work for any command with bare minimum code.

For today's snippet I'd like to share, here's how to integrate Elixir's build tool mix with it. Just paste it on your friendly neighborhood dotfiles (.bashrc, .zshrc...) and git it a go by writting mix ** then hitting <Tab>.

_fzf_complete_mix() {
  _fzf_complete --reverse -- "$@" < <(
    mix help | \
        grep "^mix [a-zA-Z]" --color=never | \
        sed "s/^[^ ]* //" | \
        sed "s/#.*//" 
  )
}

_fzf_complete_mix_post() {
  awk '{print $NF}'
}

DEV Community: Lubien

Free Beginner Friendly LiveView Course in English and Portuguese

Listing matches for users

Reviewing some Ecto concepts

Back to the tables

How NOT to load nested information on Phoenix LiveView

How to do load nested information on Phoenix LiveView Ecto

Learning a little bit more about Phoenix LiveView Streams

Fixing old tests

Adding tests for the UI changes

Summary

Where are all these points coming from?

Storing new stuff means we need a new model

Contexts strike again

An Ecto migration needs an Ecto model

Adding functions to our Ranking context

How do I see data when there's no UI?

Where should functions related to points live?

Testing the new things

A 3 minutes introduction to Ecto.Query

Summary

The Lazy Programmer's Intro to LiveView: Chapter 8

Distributed systems are hard

Removing business logic from LiveView

Let's not forget our tests

Summary

The Lazy Programmer's Intro to LiveView: Chapter 7

Conceding points to the winner

Dynamic interactions with LiveView

Learning how to interpret a LiveView event error

Creating our handle_event/3

Conceding a draw

Difference between root.html.heex and app.html.heex layout

Preventing unauthorized users from using these buttons

How to prevent a user from giving points to himself infinitely

Don't forget the tests

Refactoring because we can

Summary

The Lazy Programmer's Intro to LiveView: Chapter 6

Creating the user page

Creating the route

Using params for the first time

Adding tests!

Summary

The Lazy Programmer's Intro to LiveView: Chapter 5

Listing our users

Creating Accounts.list_users

Creating your first new route

Creating the your first LivView

Giving the page a title

Using streams to list users

Testing your LiveView

Summary

The Lazy Programmer's Intro to LiveView: Chapter 4

Adding points to users

Ecto Changesets 101

Applying changesets using Repo

Summary

The Lazy Programmer's Intro to LiveView: Chapter 3

Adding a points system

What are migrations?

Migrations with Ecto

Creating our first migration by hand

Your first UI change

HEEx: your new best friend

Summary

The Lazy Programmer's Intro to LiveView: Chapter 2

Adding Authentication to Champions

A quick tip for those who like details

What does Champions App need?

Meet mix phx.gen.auth

Phoenix Contexts

The lib/champions directory

The lib/champions_web folder

What we got after all?

Summary

The Lazy Programmer's Intro to LiveView: Chapter 1

Chapters

Introduction

Getting started

Creating our `handle_event/3`

Difference between `root.html.heex` and `app.html.heex` layout

Creating `Accounts.list_users`

Meet `mix phx.gen.auth`

The `lib/champions` directory

The `lib/champions_web` folder