# `Hypa.Conn`
[🔗](https://code.cosmicrose.dev/rosa/hypa)

Utilities to work with `Plug.Conn` structs that make it easier to use
[htmx](https://htmx.org).

## Response headers

This module provides functions to add all [htmx response
headers](https://htmx.org/docs/#response-headers).

| Header | Function |
|--------|----------|
| `HX-Location` | `put_hx_location/2` |
| `HX-Push-Url` | `put_hx_push_url/2` |
| `HX-Redirect` | `put_hx_redirect/2` |
| `HX-Refresh` | `put_hx_refresh/2` |
| `HX-Replace-Url` | `put_hx_replace_url/2` |
| `HX-Reswap` | `put_hx_reswap/2` |
| `HX-Retarget` | `put_hx_retarget/2` |
| `HX-Reselect` | `put_hx_reselect/2` |
| `HX-Trigger` | `put_hx_trigger/2` |
| `HX-Trigger-After-Settle` | `put_hx_trigger_after_settle/2` |
| `HX-Trigger-After-Swap` | `put_hx_trigger_after_swap/2` |

# `put_hx_location`
*since 0.3.0* 

```elixir
@spec put_hx_location(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Adds the `HX-Location` response header which allows you to do a client-side
redirect that does not do a full page reload.

See the [htmx docs](https://htmx.org/headers/hx-location/) for more details.

## Examples

    iex> conn(:get, "/foo")
    ...> |> Hypa.Conn.put_hx_location("/bar")
    ...> |> get_resp_header("hx-location")
    ["/bar"]

# `put_hx_push_url`
*since 0.3.0* 

```elixir
@spec put_hx_push_url(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Adds the `HX-Push-Url` response header which pushes a new URL into the history
stack.

See the [htmx docs](https://htmx.org/headers/hx-push-url/) for more details.

## Examples

    iex> conn(:get, "/foo")
    ...> |> Hypa.Conn.put_hx_push_url("/bar")
    ...> |> get_resp_header("hx-push-url")
    ["/bar"]

# `put_hx_redirect`
*since 0.3.0* 

```elixir
@spec put_hx_redirect(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Adds the `HX-Redirect` response header which can be used to do a client-side
redirect to a new location.

See the [htmx docs](https://htmx.org/headers/hx-redirect/) for more details.

## Examples

    iex> conn(:get, "/foo")
    ...> |> Hypa.Conn.put_hx_redirect("/bar")
    ...> |> get_resp_header("hx-redirect")
    ["/bar"]

# `put_hx_refresh`
*since 0.3.0* 

```elixir
@spec put_hx_refresh(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Adds the `HX-Refresh` response header which, when set to `"true"`, will do a
client-side full refresh of the page.

## Examples

    iex> conn(:get, "/foo")
    ...> |> Hypa.Conn.put_hx_refresh(true)
    ...> |> get_resp_header("hx-refresh")
    ["true"]

# `put_hx_replace_url`
*since 0.3.0* 

```elixir
@spec put_hx_replace_url(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Adds the `HX-Replace-Url` response header which will replace the current URL
in the location bar.

See the [htmx docs](https://htmx.org/headers/hx-replace-url/) for more details.

## Examples

    iex> conn(:get, "/foo")
    ...> |> Hypa.Conn.put_hx_replace_url("/bar")
    ...> |> get_resp_header("hx-replace-url")
    ["/bar"]

# `put_hx_reselect`
*since 0.3.0* 

```elixir
@spec put_hx_reselect(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Adds the `HX-Reselect` response header which is a CSS selector that allows you
to choose which part of the response is used to be swapped in. It overrides an
existing [`hx-select`](https://htmx.org/attributes/hx-select/) on the
triggering element.

## Examples

    iex> conn(:get, "/foo")
    ...> |> Hypa.Conn.put_hx_reselect("#myelement")
    ...> |> get_resp_header("hx-reselect")
    ["#myelement"]

# `put_hx_reswap`
*since 0.3.0* 

```elixir
@spec put_hx_reswap(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Adds the `HX-Reswap` response header which allows you to specify how the
response will be swapped.

See the [htmx docs](https://htmx.org/attributes/hx-swap/) for more details.

## Examples

    iex> conn(:get, "/foo")
    ...> |> Hypa.Conn.put_hx_reswap("outerHTML")
    ...> |> get_resp_header("hx-reswap")
    ["outerHTML"]

# `put_hx_retarget`
*since 0.3.0* 

```elixir
@spec put_hx_retarget(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Adds the `HX-Retarget` response header which is a CSS selector that updates
the target of the content update to a different element on the page.

## Examples

    iex> conn(:get, "/foo")
    ...> |> Hypa.Conn.put_hx_retarget("#myelement")
    ...> |> get_resp_header("hx-retarget")
    ["#myelement"]

# `put_hx_trigger`
*since 0.3.0* 

```elixir
@spec put_hx_trigger(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Adds the `HX-Trigger` response header which allows you to trigger client-side
events.

See the [htmx docs](https://htmx.org/headers/hx-trigger/) for more details.

## Examples

    iex> conn(:get, "/foo")
    ...> |> Hypa.Conn.put_hx_trigger("firstevent, secondevent")
    ...> |> get_resp_header("hx-trigger")
    ["firstevent, secondevent"]

# `put_hx_trigger_after_settle`
*since 0.3.0* 

```elixir
@spec put_hx_trigger_after_settle(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Adds the `HX-Trigger-After-Settle` response header which allows you to trigger
client-side events after the settle step.

See the [htmx docs](https://htmx.org/headers/hx-trigger-after-settle/) for more details.

## Examples

    iex> conn(:get, "/foo")
    ...> |> Hypa.Conn.put_hx_trigger_after_settle("firstevent, secondevent")
    ...> |> get_resp_header("hx-trigger-after-settle")
    ["firstevent, secondevent"]

# `put_hx_trigger_after_swap`
*since 0.3.0* 

```elixir
@spec put_hx_trigger_after_swap(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Adds the `HX-Trigger-After-Swap` response header which allows you to trigger
client-side events after the swap step.

See the [htmx docs](https://htmx.org/headers/hx-trigger-after-swap/) for more details.

## Examples

    iex> conn(:get, "/foo")
    ...> |> Hypa.Conn.put_hx_trigger_after_swap("firstevent, secondevent")
    ...> |> get_resp_header("hx-trigger-after-swap")
    ["firstevent, secondevent"]

---

*Consult [api-reference.md](api-reference.md) for complete listing*