Plug_Static_Ls v0.4.0 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 frompriv/static
), or a tuple containing the application name and the directory to serve assets from (besidespriv/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, ifonly: ["dir1", "dir2"]
is specified, only files under the “dir1” and “dir2” directories will be served byPlugStaticLs
. Defaults tonil
(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 tonil
(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
Related modules
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
.