Plug_Static_Ls v0.5.2 PlugStaticLs

A plug for serving directory listing on a static asset directory.

Note: this module only serves the directory listing. For serving the static asset contents, use Plug.Static.

It requires two options:

  • :at - the request path to reach for the static assets. It must be a string.

  • :from - the file system path to read the static assets from. It can be either: a string containing a file system path, an atom representing the application name (where assets will be served from priv/static), or a tuple containing the application name and the directory to serve assets from (besides priv/static).

The preferred form is to use :from with an atom or tuple, since it will make your application independent from the starting directory. On the other hand, if you want to serve the directory listing for a specific directory, use the file system path.

If a static asset directory specified is not found, PlugStaticLs simply forwards the connection to the rest of the pipeline. If the directory is found, PlugStaticLs verifies the path given in conn.path_info and the path must be a subset of :at path for showing the directory listing; otherwise PlugStaticLs forwards the connection to the rest of the pipeline.

Options

  • :only - filters which requests to serve. This is useful to avoid file system traversals on every request when this plug is mounted at "/". For example, if only: ["dir1", "dir2"] is specified, only files under the “dir1” and “dir2” directories will be served by PlugStaticLs. Defaults to nil (no filtering).

  • :only_matching - a relaxed version of :only that will serve any request as long as one of the given values matches the given path. For example, only_matching: ["images", "logos"] will match any request that starts at “images” or “logos”, be it “/images”, “/images-high”, “/logos” or “/logos-high”. Such matches are useful when serving digested files at the root. Defaults to nil (no filtering).

Templates

The following EEx templates are used to build the directory listing page:

  • lib/templates/plug_static_ls_header.html.eex
  • lib/templates/plug_static_ls_direntry.html.eex
  • lib/templates/plug_static_ls_footer.html.eex

Examples

This plug can be mounted in a Plug.Builder pipeline as follows, with and after Plug.Static:

  defmodule MyPlug do
    use Plug.Builder

    plug Plug.Static,
      at: "/public",
      from: :my_app,
      only: ~w(images robots.txt)
    plug PlugStaticLs,
      at: "/public",
      from: :my_app,
      only: ~w(images)

    plug :not_found

    def not_found(conn, _) do
      send_resp(conn, 404, "not found")
    end
  end

For serving index.html for a directory name, use Plug.Static.IndexHtml.

For serving static files, use Plug.Static.

Acknowledgment

The source code is derived from Plug.Static module.

The directory listing page design is derived from Yaws Web Server.

Summary

Functions

Callback implementation for Plug.call/2

Callback implementation for Plug.init/1

Functions

call(conn, arg2)

Callback implementation for Plug.call/2.

init(opts)

Callback implementation for Plug.init/1.