Controllers

Controllers are declarative way to write route handlers in Jaguar (as an alternative to mux-based routing). Each route handler is implemented as a method in the Controller class. The route handlers shall be annotated with one of the HTTP method annotations for Jaguar to recognize them. The controller class itself shall be annotated with GenController.

@GenController(path: '/library')
class LibraryApi extends Controller {
  @Get(path: '/all')
  Future<List<Book>> getAll(Context ctx) => books;

  @Post(path: '/add')
  Future<void> add(Context ctx) {
    // TODO
  }
}

Interceptors

Controller class's before method is called before any of the route handlers in the controller is executed. Here, you can directly execute other interceptors, register interceptors to be executed before or after the route handler execution using before and after methods of Context class.

@GenController(path: '/library')
class LibraryApi extends Controller {
  @Get(path: '/all')
  Future<List<Book>> getAll(Context ctx) => books;

  Future<void> before(Context ctx) async {
    await mongoPool(ctx);
    await Authorizer.authorize(ctx);
    ctx.after((_) => print("After"));
  }
}

Adding your controller to the server

There are two ways to add your controller class to Jaguar server:

1. Reflected
2. Source generated

Reflection is easier of the two methods to add Controllers to Jaguar server, so it is best to use when you are getting started with Jaguar. Source generated method however performs slightly better.

Reflected

jaguar_reflect package provides reflect method which can be used to compile Route specs from your controller class. The returned Route specs can be added to Jaguar server using the add method.

import 'package:jaguar_reflect/jaguar_reflect';

main() async {
  final server = Jaguar();
  server.add(reflect(LibraryApi()));
  await server.serve()
}

Source generated

Source generation method uses Dart's build system to generate Route spec for your Controller.

Add dependencies:

jaguar_generator package is used to source generate Route spec for your controller using build_runner package.

pubspec.yaml:

dependencies:
  jaguar:

dev_dependencies:
  build_runner:
  jaguar_generator:

Add part directive

The generated file shall be included using the part directive. The generated file will be named same as the original file with the extension .jroutes.dart.

lib/example.dart:

part 'example.jroutes.dart';

Generate Controller installer

Run build_runner to generate.

pub run build_runner build

A file named lib/example.jroutes.dart will be generated with Controller installer class _$LibraryApi. Extend LibraryApi from _$LibraryApi (alternatively, it can be mixed in). The generated _$LibraryApi class contains install method that can be used to add the routes to the server.

main() async {
  final server = Jaguar();
  LibraryApi().install(server);
  await server.serve()
}

Examples and tutorials

• Controllers example using reflection