Tutorial: Controllers

Controllers

Controllers are the center of logic in Flitter. Routes should use controller methods to handle requests, and the controller methods should do all of the actual logic to process said requests. Controllers are defined in the app/controllers/ directory, and are made available by their canonical names through the controllers service.

Creating Controllers

Controllers are defined in the app/controllers/ directory and have the .controller.js extension. Controller classes are just normal classes with methods that take the Express request and response objects and should send a response back, but they should extend from the base libflitter/controller/Controller class. Here's an example controller file:

// app/controllers/Home.controller.js
const Controller = require('libflitter/controller/Controller')
class Home extends Controller {
    welcome(req, res){
        return res.view('welcome')
    }
    error(req, res){
        const error_string = "Uh, oh! Error."
        return res.send(error_string)
    }
}

module.exports = exports = Home

Controller classes are allowed to contain whatever methods or class variables that you want. However, methods that will be used as handlers for routes should accept the Express request and response objects as arguments and should send a response at some point, then return the status of that sending to Flitter using the built in response.view, response.error, response.page, response.send, &c. methods.

New controller files can be created from Flitter's template using the ./flitter command, like so:

./flitter new controller subdirectory:file_name

This command will create the file app/controllers/subdirectory/file_name.controller.js which can be referenced as subdirectory:file_name:

const Controller = require('libflitter/controller/Controller')

/*
 * file_name Controller
 * -------------------------------------------------------------
 * Put some description here!
 */
class file_name extends Controller {

    /*
     * Serve the main page.
     */
    main(req, res){

        /*
         * Return the main view.
         * It must be passed the response.
         * Parameters can be passed to the page method as an
         * object as an optional second argument.
         */
        return res.page('view_name')
    }
}

module.exports = exports = file_name

Dependency Injection: Using Services

Earlier in this guide, we referred to models/controllers/configs being made available via services. These services are dependencies and are made available to Injectable classes in the rest of the application by Flitter's dependency injector, flitter-di.

Controllers are Injectable classes, so you can use services provided in the rest of the application from a controller by adding the service name to the controller's static services getter like so:

const Controller = require('libflitter/controller/Controller')

/*
 * file_name Controller
 * -------------------------------------------------------------
 * Put some description here!
 */
class file_name extends Controller {
    static get services() {
        // Make sure we get any services requested by the superclasses, then request the 'configs' service.
        return [...super.services, 'configs']
    }

    /*
     * Serve the main page.
     */
    main(req, res){

        /*
         * Return the main view.
         * It must be passed the response.
         * Parameters can be passed to the page method as an
         * object as an optional second argument.
         */
        return res.page('view_name')
    }

    /*
     * Show an error
     */
    error(req, res) {
        // Now, we can access the configs service through this.configs on any instances of this controller.
        // Get the app name from the app.config.js config file.
        const app_name = this.configs.get('app.name');
        return res.send(`Uh, oh! ${app_name} ran into an error and had to stop!`)
    }
}

module.exports = exports = file_name

The available services provided by each package are documented in those packages' documentation, however some common services from libflitter are configs, models, controllers, utility, and output.

Next: The Flitter CLI