Controller

Introduction

Controllers are the “C” in the MVC paradigm. Controllers will do actual stuff. They get requests or part of requests, retrieve stuff from databases and cause Ninja to return certain results.

A really simple controller

A basic controller looks like:

package controllers;

@Singleton
public class AppController {

    public Result index() {

        return Results.html();
    }

}

The important conventions are that a controller method must return a Result. A result is in short just an object that holds response codes, content to render, headers and cookies that should be returned to the visitors of your website.

Results with the “s” at the end is a convenience class that allows you to generate a preconfigured Result. For instance Results.html() will tell Ninja to render an HTML page. But you can also render JSON and other results.

By convention controllers live in the package “controllers”.

Getting parameters into your controllers

A controller usually not only renders stuff, but also takes some inputs and does something with them.

You can get parts of the URL inside your controller via three annotations: @Param, @Params and @PathParam. Via @PathParam you can get variable parts of a route (described in more details in the routing section).

@Param allows you to get single-value Query or Form parameters. @Params allows you to get multi-value Query parameters.

Let's say and the user visits the following URL…

/user/12345/[email protected]/userDashboard?debug=false&filters=new&filters=urgent

… and we got a route definition like that:

router.GET().route("/user/{id}/{email}/userDashboard").with(AppController::userDashboard);

We can then get all variable parts of this URL via the following method controller definition:

package controllers;

@Singleton
public class AppController {

    public Result userDashboard(
            @PathParam("id") String id, 
            @PathParam("email") String email, 
            @Param("debug") Optional<String> debug,
            @Param("isAdmin") Boolean isAdmin,
            @Params("filters") String [] filters,
            @Header("user-agent") String userAgent) {

        //do something with the parameters...

    }

}

More on objects Ninja can automatically provide you at controller level

Have a look at that method:

package controllers;

@Singleton
public class ApplicationController {

    public Result index(
            @PathParam("id") String id, 
            @PathParam("email") String email, 
            @Param("debug") Optional<String> debug,
            @Param("isAdmin") Boolean isAdmin,
            Context context,
            MyObject myObject) {

        //do something with the parameters...
    }

}

Ninja can not only inject @PathParam and @Param objects. But also the Context. The context is a request scoped object that holds all information of the current request - parameters, headers and so on…

Even better: Ninja will parse an arbitrary object given in the method. In the above case MyObject will be automatically parsed by Ninja. The way it will parsed (JSON, XML, POST form) will be determined via the “Content-Type” request header.

If you are using the POST form way, this object can contains any parameter type listed in the Argument extractors chapter (or custom ones, as described in the same chapter). Custom objects contained in this arbitrary object can also be parsed if they have a constructor without arguments.

public class Address {
    String street;
}

public class User {
    Address address;
}

Assuming your controller method want to receive a User object, your HTML form can send a field value for the key address.street.

If your custom object has a date/timestamp field, first make sure that you use the java.util.Date type and when you pass some date to the controller pass in the format accepted by Joda Time library, or implement your own ParamParser for a java.util.Date.

A note about null and Optional

ninja.strict_argument_extractors=false        # accepts null 

ninja.strict_argument_extractors=true         # redirects to Bad Request page if parameter is null 

ninja.strict_argument_extractors=true         # redirects to Bad Request page if parameter is null 

Ninja and content negotiation

In the last section we have already seen that parsing of objects works via content negotiation.

Rendering of objects works the same way and evaluates the “Accept” request header for that.

Therefore a controller method like…

public void Result getUser() {
    User user = userDao.getUser();
    return Results.ok().render(user);
}

…will render XML when the “Accept” request header is “application/xml” or JSON when the “Accept” header is “application/json”.

While content negotiation is pretty cool it sometimes breaks down in reality.

Especially if clients send strange headers or if you want to be sure that a certain controller method always renders a return format.

Then you can simply call use return Results.json().render(user) or return Results.xml().render(user) to enforce the rendering of a certain return format.

Rendering HTML

Rendering by convention has been already explained in the getting started part. But in short consider the following class:

package controllers;

public class ApplicationController {       

    public Result index() {
        return Results.html();

    }
}

This renders by convention a view in directory views/ApplicationController/index.ftl.html.

But you can specify your own HTML view, too:

package controllers;

public class ApplicationController {       

    public Result index() {
        return Results.html().template("views/AnotherController/anotherview.ftl.html");

    }
}

In conclusion you can use convention over configuration in most cases - but you can also specify a view to render explicitly.