# Usage

## Requirements

- Elixir >=1.11
- Phoenix >= 1.6.0
- Phoenix LiveView >= 0.16 (optional)


## Installation

You can install this library by adding it to your list of dependencies in `mix.exs`. (use `mix hex.info routex` to find the latest version):

```diff
def deps do
  [
     ...other deps
+    {:routex, ">= 0.0.0"}
  ]
end
```

Modify the entrypoint of your web interface definition.
```diff
# file: lib/example_web.ex

+  use Routex.Router  # always before Phoenix Router
   use Phoenix.Router, helpers: false

# in controller
   unquote(verified_routes())
+  unquote(routex_helpers())

# in live_view
      unquote(html_helpers())
+     on_mount(unquote(__MODULE__).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 unquote(__MODULE__).Router.RoutexHelpers, only: :macros
+      alias unquote(__MODULE__).Router.RoutexHelpers, as: Routes
+    end
+  end
```

### About the on_mount hook

The `on_mount` hook is generated by Routex in a module created during compilation.
It attaches a `handle_param` which in turn assigns a few (helper) values
to the connection and/or socket. This includes the current url and assigns added
by Routex Extensions.

## Configuration

To use `Routex`, a module that calls `use Routex.Backend` (referred to below as a
"backend") has to be defined. It includes a list with extensions and
configuration of extensions.

```elixir
defmodule ExampleWeb.RoutexBackend do
use Routex.Backend,
  extensions: [
  Routex.Extension.AttrGetters,  # required
  # ...other extensions...
  ],
end
```

## Extensions

Routex is merely a framework and 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 them.

## 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)

```diff
# 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](docs/TROUBLESHOOTING.md)