Documentation

You are viewing the documentation for the 2.9.x release series. The latest stable release series is 3.0.x.

§Actions, Controllers and Results

§What is an Action?

Most of the requests received by a Play application are handled by an Action.

A play.api.mvc.Action is basically a (play.api.mvc.Request => play.api.mvc.Result) function that handles a request and generates a result to be sent to the client.

def echo: Action[AnyContent] = Action { request => Ok("Got request [" + request + "]") }

An action returns a play.api.mvc.Result value, representing the HTTP response to send to the web client. In this example Ok constructs a 200 OK response containing a text/plain response body.

§Building an Action

Within any controller extending BaseController, the Action value is the default action builder. This action builder contains several helpers for creating Actions.

The first simplest one just takes as argument an expression block returning a Result:

Action {
  Ok("Hello world")
}

This is the simplest way to create an Action, but we don’t get a reference to the incoming request. It is often useful to access the HTTP request calling this Action.

So there is another Action builder that takes as an argument a function Request => Result:

Action { request => Ok("Got request [" + request + "]") }

It is often useful to mark the request parameter as implicit so it can be implicitly used by other APIs that need it:

Action { implicit request => Ok("Got request [" + request + "]") }

If you have broken up your code into methods, then you can pass through the implicit request from the action:

def action: Action[AnyContent] = Action { implicit request =>
  anotherMethod("Some para value")
  Ok("Got request [" + request + "]")
}

def anotherMethod(p: String)(implicit request: Request[_]) = {
  // do something that needs access to the request
}

The last way of creating an Action value is to specify an additional BodyParser argument:

Action(parse.json) { implicit request => Ok("Got request [" + request + "]") }

Body parsers will be covered later in this manual. For now you just need to know that the other methods of creating Action values use a default Any content body parser.

§Controllers are action generators

A controller in Play is nothing more than an object that generates Action values. Controllers are typically defined as classes to take advantage of Dependency Injection.

Note: Keep in mind that defining controllers as objects will not be supported in future versions of Play. Using classes is the recommended approach.

The simplest use case for defining an action generator is a method with no parameters that returns an Action value:

package controllers

  import javax.inject.Inject

  import play.api.mvc._

  class Application @Inject() (cc: ControllerComponents) extends AbstractController(cc) {
    def index = Action {
      Ok("It works!")
    }
  }

Of course, the action generator method can have parameters, and these parameters can be captured by the Action closure:

def hello(name: String) = Action {
  Ok("Hello " + name)
}

§Simple results

For now we are just interested in simple results: an HTTP result with a status code, a set of HTTP headers and a body to be sent to the web client.

These results are defined by play.api.mvc.Result:

import play.api.http.HttpEntity

def index = Action {
  Result(
    header = ResponseHeader(200, Map.empty),
    body = HttpEntity.Strict(ByteString("Hello world!"), Some("text/plain"))
  )
}

Of course there are several helpers available to create common results such as the Ok result in the sample above:

def index = Action {
  Ok("Hello world!")
}

This produces exactly the same result as before.

Here are several examples to create various results:

val ok           = Ok("Hello world!")
val notFound     = NotFound
val pageNotFound = NotFound(<h1>Page not found</h1>)
val badRequest   = BadRequest(views.html.form(formWithErrors))
val oops         = InternalServerError("Oops")
val anyStatus    = Status(488)("Strange response type")

All of these helpers can be found in the play.api.mvc.Results trait and companion object.

§Redirects are simple results too

Redirecting the browser to a new URL is just another kind of simple result. However, these result types don’t take a response body.

There are several helpers available to create redirect results:

def index = Action {
  Redirect("/user/home")
}

The default is to use a 303 SEE_OTHER response type, but you can also set a more specific status code if you need one:

def index = Action {
  Redirect("/user/home", MOVED_PERMANENTLY)
}

§TODO dummy page

You can use an empty Action implementation defined as TODO: the result is a standard ‘Not implemented yet’ result page:

def index(name: String) = TODO

Next: HTTP Routing

Found an error in this documentation? The source code for this page can be found here. After reading the documentation guidelines, please feel free to contribute a pull request. Have questions or advice to share? Go to our community forums to start a conversation with the community.