Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nshafer/plug_assign
A simple plug to allow setting variables in a connection.
https://github.com/nshafer/plug_assign
Last synced: 15 days ago
JSON representation
A simple plug to allow setting variables in a connection.
- Host: GitHub
- URL: https://github.com/nshafer/plug_assign
- Owner: nshafer
- License: mit
- Created: 2015-10-14T21:43:52.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2024-01-30T16:58:38.000Z (10 months ago)
- Last Synced: 2024-10-12T07:25:25.141Z (about 1 month ago)
- Language: Elixir
- Size: 85.9 KB
- Stars: 7
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Plug.Assign
A simple plug to allow setting variables in a connection. For example, as a way to set default variables for a controller, view or template to use in a Phoenix app.
## Installation
The package can be installed from Hex:
Add plug_assign to your list of dependencies in `mix.exs`:
```elixir
def deps do
[{:plug_assign, "~> 2.0.2"}]
end
```
Fetch and install the dependencies
```sh
$ mix deps.get
```
## Basic Usage
Define assigns as part of any plug stack.
```elixir
plug Plug.Assign, foo: "bar", bar: true, baz: 42
```
This will set the given key/value pairs in the `assigns` map of the Plug.Conn, for you to use
in controllers, views, and templates.
One way to use this is to set variables so you can quickly determine where you are in your app.
```elixir
pipeline :browser do
...
plug Plug.Assign, admin: false
end
pipeline :admin do
plug Plug.Assign, admin: true
end
```
And then use that in a template, such as your layout.
```html
<%= if @admin do %>
Hello, Administrator
<% end %>
```
Since you can use this anywhere you can use a plug, you can also use it in a Phoenix Controller.
```elixir
defmodule HelloWeb.Admin.PostController do
use HelloWeb, :controller
plug Plug.Assign, section: :posts
...
end
```
```html
<%= @section %>
```
If you want to only assign a variable for certain actions, you can use the `plug ... when` format,
but be careful that bare keyword lists are only accepted as the last arguments of a macro call,
which is no longer the case with a `when` clause, so add the square brackets `[]` around your
assigns, or use a map instead.
```elixir
defmodule HelloWeb.Admin.PostController do
use HelloWeb, :controller
plug Plug.Assign, [read_request: true] when action in [:index, :show]
plug Plug.Assign, %{write_request: true} when action in [:edit, :new, :create, :update, :delete]
...
end
```
## Accessing in templates
If you're using an assign in a template that may not have been set, you can't use the
`@variable` format without throwing an error, so use one of the following techniques instead:
- Access shortcut: `assigns[:admin]` - Returns `nil` if not set.
- Map.get/2: `Map.get(assigns, :admin)` - Returns `nil` if not set.
- Map.get/3: `Map.get(assigns, :admin, false) - `Returns `false` if not set.
```html
<%= if assigns[:admin] do %>
Hello, Administrator
<% end %>
```
## Assignment formats
Assigns can be either a keyword list
```elixir
plug Plug.Assign, foo: "bar", bar: true, baz: 42
```
Or a map, as long as the keys are atoms.
```elixir
plug Plug.Assign, %{foo: "foo", bar: true, baz: 42}
plug Plug.Assign, %{:foo => "foo", :bar => true, :baz => 42}
```
Any attempt to pass it anything else will throw an exception.
```bash
** (ArgumentError) Invalid assignment, must be a keyword list or map with all keys as atoms
```
## Generate documentation
```bash
mix docs
```