Ewebmachine.Builder.Resources (ewebmachine v2.3.3)

View Source

use this module will use Plug.Builder (so a plug pipeline described with the plug module_or_function_plug macro), but gives you a :resource_match local function plug which matches routes declared with the resource/2 macro and execute the plug defined by its body.

See Ewebmachine.Builder.Handlers documentation to see how to contruct these modules (in the after block)

Below a full example :


defmodule FullApi do
  use Ewebmachine.Builder.Resources
  if Mix.env == :dev, do: plug Ewebmachine.Plug.Debug
  # pre plug, for instance you can put plugs defining common handlers
  plug :resource_match
  plug Ewebmachine.Plug.Run
  # customize ewebmachine result, for instance make an error page handler plug
  plug Ewebmachine.Plug.Send
  # plug after that will be executed only if no ewebmachine resources has matched

  resource "/hello/:name" do %{name: name} after
    plug SomeAdditionnalPlug
    content_types_provided do: ['application/xml': :to_xml]
    defh to_xml, do: "<Person><name>#{state.name}</name>"
  end

  resource "/*path" do %{path: Enum.join(path,"/")} after
    resource_exists do:
      File.regular?(path state.path)
    content_types_provided do:
      [{state.path|>Plug.MIME.path|>default_plain,:to_content}]
    defh to_content, do:
      File.stream!(path(state.path),[],300_000_000)
    defp path(relative), do: "#{:code.priv_dir :ewebmachine_example}/web/#{relative}"
    defp default_plain("application/octet-stream"), do: "text/plain"
    defp default_plain(type), do: type
  end
end

Common Plugs macro helper

As the most common use case is to match resources, run the webmachine automate, then set a 404 if no resource match, then handle error code, then send the response, the resources_plugs/1 macro allows you to do that.

For example, if you want to convert all HTTP errors as Exceptions, and consider that all path must be handled and so any non matching path should return a 404 :

resources_plugs error_as_exception: true, nomatch_404: true

is equivalent to

plug :resource_match
plug Ewebmachine.Plug.Run
plug :wm_notset_404
plug Ewebmachine.Plug.ErrorAsException
plug Ewebmachine.Plug.Send

defp wm_notset_404(%{state: :unset}=conn,_), do: resp(conn,404,"")
defp wm_notset_404(conn,_), do: conn

Another example, following plugs must handle non matching paths and errors should be converted into GET /error/:status that must be handled by following plugs :

resources_plugs error_forwarding: "/error/:status"

is equivalent to

plug :resource_match
plug Ewebmachine.Plug.Run
plug Ewebmachine.Plug.ErrorAsForward, forward_pattern: "/error/:status"
plug Ewebmachine.Plug.Send

Summary

Functions

resource(route, list)
resource(arg, route, list)

Create a webmachine handler plug and use it on :resource_match when path matches

resource_quote(wm_module, route, init_block, body)
resources_plugs(opts \\ [])

Functions

resource(route, list)

(macro)

resource(arg, route, list)

(macro)

Create a webmachine handler plug and use it on :resource_match when path matches

  • the route will be the matching spec (see Plug.Router.match, string spec only)
  • do_block will be called on match (so matching bindings will be available) and should return the initial state
  • after_block will be the webmachine handler plug module body (wrapped with use Ewebmachine.Builder.Handlers and plug :add_handlers to clean the declaration.
resource "/my/route/:commaid" do
  id = string.split(commaid,",")
  %{foo: id}
after
  plug someadditionnalplug
  resource_exists do: state.id == ["hello"]
end

resource ShortenedRouteName, "/my/route/that/would/generate/a/long/module/name/:commaid" do
  id = String.split(commaid,",")
  %{foo: id}
after
  plug SomeAdditionnalPlug
  resource_exists do: state.id == ["hello"]
end

resource_quote(wm_module, route, init_block, body)

resources_plugs(opts \\ [])

(macro)