phoenix v0.5.0 → Overview → Phoenix → Controller

Phoenix.Controller

Controllers are used to group common functionality in the same (pluggable) module.

For example, the route:

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

will invoke the show/2 action in the UserController:

defmodule UserController do
  use Phoenix.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:

Rendering and layouts

TODO: documentation.

Plug pipeline

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

defmodule UserController do
  use Phoenix.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.

Summary
↑

layout_module(controller_module)

Finds Layout View module based on Controller Module
render_view(conn, view_mod, layout_mod, template, assigns \\ [])

Renders View with template based on Mime Accept headers
view_module(controller_module)

Finds View module based on controller_module

Functions

layout_module(controller_module)
(function) # ↑

Finds Layout View module based on Controller Module

Examples

iex> Controller.layout_module(MyApp.UserController)
MyApp.LayoutView
render_view(conn, view_mod, layout_mod, template, assigns \\ [])
(function) # ↑

Renders View with template based on Mime Accept headers

  • conn - The Plug.Conn struct
  • view_mod - The View module to call render/2 on
  • layout_mod - The Layout module to render

  • template - The String template name, ie “show”, “index”.

    An empty list `[]` from `plug :render` automatically assigns
       the template as the action_name of the connection
  • assigns - The optional dict assigns to pass to template when rendering

Examples

# Explicit rendering

defmodule MyApp.UserController do
  use Phoenix.Controller

  def show(conn) do
    render conn, "show", name: "José"
  end
end

# Automatic rendering with `plug :render`

defmodule MyApp.UserController do
  use Phoenix.Controller

  plug :action
  plug :render

  def show(conn) do
    assign(conn, :name, "José")
  end
end
view_module(controller_module)
(function) # ↑

Finds View module based on controller_module

Examples

iex> Controller.view_module(MyApp.UserController)
MyApp.UserView

iex> Controller.view_module(MyApp.Admin.UserController)
MyApp.Admin.UserView