Phoenix.Controller

Parsed documentation:
View on GitHub
Controllers are used to group common functionality in the same
(pluggable) module.

For example, the route:

    get "/users/:id", MyApp.UserController, :show

will invoke the `show/2` action in the `MyApp.UserController`:

    defmodule MyApp.UserController do
      use MyApp.Web, :controller

      plug :action

      def show(conn, %{"id" => id}) do
        user = Repo.get(User, id)
        render conn, "show.html", user: user
      end
    end

An action is just a regular function that receives the connection
and the request parameters as arguments. The connection is a
`Plug.Conn` struct, as specified by the Plug library.

## Connection

A controller by default provides many convenience functions for
manipulating the connection, rendering templates, and more.

Those functions are imported from two modules:

  * `Plug.Conn` - a bunch of low-level functions to work with
    the connection

  * `Phoenix.Controller` - functions provided by Phoenix
    to support rendering, and other Phoenix specific behaviour

## Rendering and layouts

One of the main features provided by controllers is the ability
to do content negotiation and render templates based on
information sent by the client. Read `render/3` to learn more.

It is also important to not confuse `Phoenix.Controller.render/3`
with `Phoenix.View.render/3` in the long term. The former expects
a connection and relies on content negotiation while the latter is
connection-agnostic and typically invoked from your views.

## Plug pipeline

As with routers, controllers also have their own plug pipeline.
However, different from routers, controllers have a single pipeline:

    defmodule MyApp.UserController do
      use MyApp.Web, :controller

      plug :authenticate, usernames: ["jose", "eric", "sonny"]
      plug :action

      def show(conn, params) do
        # authenticated users only
      end

      defp authenticate(conn, options) do
        if get_session(conn, :username) in options[:usernames] do
          conn
        else
          conn |> redirect(Router.root_path) |> halt
        end
      end
    end

The `:action` plug must always be invoked and it represents the action
to be dispatched to.

Check `Phoenix.Controller.Pipeline` for more information on `plug/2`
and how to customize the plug pipeline.

## Options

When used, the controller supports the following options:

  * `:namespace` - sets the namespace to properly inflect
    the layout view. By default it uses the base alias
    in your controller name.
No suggestions.
Please help! Open an issue on GitHub if this assessment is incorrect.