View Source Usage
requirements
Requirements
- Elixir >=1.11
- Phoenix >= 1.6.0
- Phoenix LiveView >= 0.16 (optional)
installation
Installation
You can install this library by adding it to your list of dependencies in mix.exs
:
def deps do
[
...other deps
+ {:routex, ">= 0.0.0"}
]
end
Modify the entrypoint your web interface definition.
# file: lib/example_web.ex
+ use Routex.Router # always before Phoenix Router
use Phoenix.Router, helpers: true
# in controller
unquote(verified_routes())
+ unquote(routex_helpers())
# in live_view
unquote(html_helpers())
+ on_mount(ExampleWeb.Router.RoutexHelpers)
# in view_helpers or html_helpers
unquote(verified_routes())
+ unquote(routex_helpers())
# insert new private function
+ defp routex_helpers do
+ quote do
+ import ExampleWeb.Router.RoutexHelpers
+ end
+ end
The on_mount hook is used to attach a handle_param
hook that assigns a few
(helper) values to the connection or socket. This includes the current url and
any assigns created by Routex Extensions. When you want to have full control over
these hooks, you can use something like the snippet below instead.
def on_mount(_, params, session, socket) do
socket =
Phoenix.LiveView.attach_hook(socket, :set_rtx, :handle_params, fn _params, url, socket ->
attrs = ExampleWeb.Route.RoutexHelpers.attrs(url)
rtx_assigns = [url: url, __order__: attrs.__order__] ++ Map.to_list(attrs.assigns)
{:cont,Phoenix.LiveView.assign( socket, rtx_assigns)}
end)
{:cont, socket}
end
configuration
Configuration
To use Routex
, a module that calls use Routex
(referred to below as a
"backend") has to be defined. It includes a list with extensions and
configuration of extensions.
defmodule ExampleWeb.RoutexBackend do
use Routex,
extensions: [
# ...list of extensions...
],
end
extensions
Extensions
Routex relies on extensions to provide features. Each extension provides a single feature. The extensions have their own documentation which specifies how to configure and use the extension.
preprocess-routes-with-routex
Preprocess routes with Routex
Routex
will preprocess any route wrapped in a preprocess_using
block;
either direct or indirect. It uses the backend passed as the first argument.
This allows the use of multiple backends (e.g. to use different extensions for
admin routes)
# file: router.ex
scope "/", ExampleWeb, host: "admin.", as: :admin do
pipe_through :browser
+ preprocess_using ExampleWeb.RoutexBackendAdmin do
# [...routes...]
+ end
end
+ preprocess_using ExampleWeb.RoutexBackend do
scope "/", ExampleWeb do
pipe_through [:browser, :redirect_if_user_is_authenticated]
# [...routes...]
end
scope "/", ExampleWeb do
pipe_through [:browser, :require_authenticated_user]
# [...routes...]
end
+ end
When you run into issues, please have a look at the Troubleshooting