Phoenix LiveView File Upload

Recently I was doing some work with the Phoenix framework and needed to get file upload working. To achieve this I opted for a LiveView implementation for an easy, slick user interface with no JavaScript. There were a few gaps in my knowledge though, and, honestly, some resources I found were less than helpful. I thought I'd share a simple implementation from start to finish for anyone to make use of.

Before I dig in too deeply, I'll share working LiveView code below. It's small, I'd say, but also the bulk of the necessary code. I'm quite happy with how small it is and the user experience it's able to provide. It blows my mind a bit that you can get a nice interactive experience with no JavaScript involved. It's also worth mentioning this was built using Phoenix 1.6.11:

defmodule FileUploadWeb.FileUploadLive do
  require Logger
  use FileUploadWeb, :live_view

  @impl Phoenix.LiveView
  def render(assigns) do
    ~H'''
    <style>
      #cover {
        position: absolute;
        width: 100%;
        height: 100%;
        z-index: 9999;
        background-color: rgba(128,128,128,0.6);
      }
      #message {
        position: relative;
        top: 20%;
        font-weight: bold;
        background-color: white;
        padding: 1em;
        border-radius: 3px;
        text-align: center;
        width: 60%;
        margin: auto;
      }
    </style>
    <div class="container">
      <%= if @loading do %>
      <div class="row">
        <div id="cover">
          <p id="message"><%= @loading_message %></p>
        </div>
      </div>
      <% end %>
      <div class="row">
        <div class="column">
          <.form let={form} for={:upload} phx-submit="upload" phx-change="validate">
          <%= label form, :csv_file %>
          <%= live_file_input @uploads.csv %>
          <%= submit "upload" %>
          </.form>
        </div>
      </div>
        <%= if @complete do %>
        <div class="row">
        <%= for entry <- @uploaded_files do %>
          <a href={entry} download="uploaded_csv_as_zip">
            <button type="button">Download ZIP</button>
          </a>
        <% end %>
        </div>
        <% end %>
    </div>
    '''
  end

  @impl Phoenix.LiveView
  def mount(_params, _session, socket) do
    {:ok,
      socket
      |> assign(:uploaded_files, [])
      |> assign(:loading, false)
      |> assign(:loading_message, "")
      |> assign(:complete, false)
      |> allow_upload(:csv, accept: ~w(.csv), max_entries: 1)
    }
  end

  @impl Phoenix.LiveView
  def handle_event("upload", _params, socket) do
    send(self(), :parse_csv)
    {:noreply,
      socket
      |> assign(loading: true)
      |> assign(loading_message: "Procesing uploaded file...")
    }
  end

  @impl Phoenix.LiveView
  def handle_event("validate", _params, socket) do
    {:noreply, socket}
  end

  @impl Phoenix.LiveView
  def handle_info(:parse_csv, socket) do
    [csv_row_data | _tail] = 
      consume_uploaded_entries(socket, :csv , fn %{path: path_to_file}, _entry ->
      files =
        path_to_file
        |> File.stream!
        |> NimbleCSV.RFC4180.parse_stream()
        |> map_csv_rows()

      {:ok, files}
    end)

    # Line up the processing sequence
    Enum.each(csv_row_data, &(send(self(), {:show_row_info, &1})))
    send(self(), :create_zip_download)
    send(self(), :complete_processing)

    row_count = Kernel.length(csv_row_data)
    {:noreply,
      assign(socket, loading_message: "Processing #{row_count} rows ...")
    }
  end

  @impl Phoenix.LiveView
  def handle_info({:show_row_info, csv_row_data}, socket) do
    Process.sleep(1000)
    {:noreply,
      socket
      |> assign(loading_message: "Processing data for: #{csv_row_data[:name]}")
    }
  end

  @impl Phoenix.LiveView
  def handle_info(:create_zip_download, socket) do
    save_zip()
    file_path = Routes.static_path(socket, "/uploads/uploaded_csv.zip")
    {:noreply,
      socket
      |> assign(loading_message: "Creating ZIP file...")
      |> assign(uploaded_files: [file_path])
    }
  end

  @impl Phoenix.LiveView
  def handle_info(:complete_processing, socket) do
    Process.sleep(1000)
    {:noreply,
      socket
      |> assign(loading_message: "")
      |> assign(loading: false)
      |> assign(complete: true)
    }
  end

  defp map_csv_rows(data) do
    Enum.map(data, fn [name, date, event] -> %{
        name: name,
        date: date,
        event: event,
      }
    end)
  end

  defp save_zip do
    csv_file_name = ["tmp/uploaded.csv"]
    charlist_file_names = Enum.map(csv_file_name, fn(file_name) ->
      String.to_charlist(file_name)
    end)

    case :zip.create("uploaded_csv.zip", charlist_file_names) do
      {:ok, filename} ->
        destination_file_name = Path.absname("priv/static/uploads/#{filename}")
        File.cp(filename, destination_file_name)
        File.rm(filename)
      {:error, error} ->
        Logger.debug(error)
    end
  end
end

Okay, so what is this doing? In the mount() function we're setting defaults for the initial load. It's here we specify CSV files are what we'll allow. Then, on upload, we process the provided file. Along the way, we make changes to the socket in order to update the user interface to provide feedback. Finally, as more of an example than anything else, we create a ZIP file and provide that to the user as a download. That's the high-level. Now, let's dig in more deeply!

There's a decent amount to cover so let's break this down into sections:

• the render() function
• the mount() function
• the consume_uploaded_entries() function
• sending and handling messages
• other required code

The render() Function

This function is critical to the LiveView process. Looking at it, you can see I've included inline styles and HTML elements. It accepts an assigns param which is handled by the socket. This is used by the ~H sigil for embedding elixir in the document which is then rendered by the browser. If you're familiar with Rails-land, this is comparable to .erb templates.

There is an alternative to the approach of using the render() function. You could instead create a HEEx file in the same directory as the LiveView file using the same name. This is especially helpful if there's much more going on in the HTML than what I've shown above. For example, if your LiveView file is users_index.ex then the associated HEEx file would be users_index.html.heex. If you opt for this then you can ignore the render() function altogether.

The mount() Function

The mount() function is another critical piece of the LiveView. Its job is to set the default state and it's actually called twice - once on the initial GET (a "dead render") and again with the establishment of the websocket connection. If you have any heavyish lifting in your mount() function you may want to explore the connected?/1 function in order to distinguish between the GET and the websocket connection.

In this example you can see where we enable file uploads with the allow_upload(:csv, accept: ~w(.csv), max_entries: 1) function. Without this the file upload simply won't work. You'll also notice a few other default settings such as assign(:loading_message, "") which is setting the socket's assigns to manage state within the LiveView. Within the HEEx template, you can then access these "assigns" with the @ syntax - like @loading_message.

The consume_uploaded_entries() Function

My implementation of the consume_uploaded_entries() is fairly small. You can check out the docs for a bit more you can do with it. What it allows me to do, though, is to access the uploaded file and begin manipulating it. In the code above I'm streaming the file using the path_to_file, using the NimbleCSV package to parse the CSV, and then I have a private function map_csv_rows() which turns the rows of a CSV into a map of structs.

With the above complete, I'll have easy access to a map of the row data which is easily managed in whatever way necessary. For example, maybe each row of data is stored in the database, or converted into some other document, or who knows what. In the case of the example code I've provided, I just map over the structs and update the DOM with an Enum.each... - I'll get more into this in the next section.

Sending and Handling Messages

In a number of places in the example code, you'll notice socket assigns such as:

|> assign(loading_message: "Processing data for: #{csv_row_data[:name]}")

I'm using this to update the DOM, as the CSV is processed, so that the user can see feedback regarding the process. And the key to providing that feedback is sending messages. If you again look at the code, I made a comment "# Line up the processing sequence" which is then followed by a number of send() functions. Let's take a moment to understand them.

Take the call send(self(), :complete_processing). What this is doing is sending a message to self() which is the PID of the current process (so it sends the message to the correct process!), with the message of :complete_processing. This atom is matched against a function in our file called handle_info(:complete_processing, socket). So by invoking send(self(), :complete_processing), we're telling the current process to send a message to its own function which handles :complete_processing.

There's a little bit more to this, though. When you're sending a message, it's important to understand that under the covers you're using the "actor model" and placing that message in a FIFO queue. So when you see this code:

Enum.each(csv_row_data, &(send(self(), {:show_row_info, &1})))
send(self(), :create_zip_download)
send(self(), :complete_processing)

It's iterating over csv_row_data, queueing a :show_row_info message to itself X times, and then queuing :create_zip_download followed by :complete_processing in that order. The thing is, though, the scope of the function sending these messages is not yet complete, there's still one more thing to do:

row_count = Kernel.length(csv_row_data)
{:noreply,
  assign(socket, loading_message: "Processing #{row_count} rows ...")
}

This will update the DOM that X number of records are being processed. Once that's done, and the function completes, then the other messages in the FIFO queue will be processed.

Other Required Code

Alright, we're onto the last stretch! My code footprint is pretty small, with the largest part of it being what I shared at the beginning of this post. Still, we need to:

• make a directory or two
• setup our route
• at least in my case, add a dependency for NimbleCSV

So, to start, and what I did not do is create my phoenix project with the --live flag. So, if you don't do that, we need to create one directory in particular. Using my code example, you can see my project is named FileUploadWeb so we'll use that as the basis for the mkdir command. From a terminal, in the project's root directory, run mkdir lib/file_upload_web/live. Then you can create the new file: touch lib/file_upload_web/live/file_upload_live.ex.

Next, and this is strictly because I'm allowing the user to download the file, we need to create the directory that file will be written to: mkdir priv/static/uploads. To support this change, we also need to enable serving that directory. For this, open your endpoint.ex file and change your Plug.Static definition:

plug Plug.Static,
  at: "/",
  from: :file_upload,
  gzip: false,
  only: ~w(assets fonts images uploads favicon.ico robots.txt)

Really, the only change there is to add "uploads" to the list. This is important, as I discovered, as placing a new file (the ZIP file) elsewhere could actually get my project to reload as watched directories are changed!

Next, we need to add our route for the LiveView. To do this open the router.ex file and add a new route for the "/" scope. In particular, you'll add a line similar to live "/", FileUploadLive.

scope "/", FileUploadWeb do
  pipe_through :browser
  live "/", FileUploadLive
end

Lastly, since I'm using the NimbleCSV package, I needed to add that to my deps function in the mix.exs file:

defp deps do
  [
    ...
    {:nimble_csv, "~> 1.2"}
  ]
end

Once that's plugged in, just run mix deps.get from the command line to install NimbleCSV. And that's it! You should be able to create a new project, copy some lines from here, and get a working, dynamic file upload interface. It's not much, but it may help cement some very cool Phoenix functionality.

Bonus, you have to write zero JavaScript to achieve all of this.

---

Home | Reach out to devnull @ michaelovies dot com