A controller is an interface layer between the view and model. The controller contains functions (actions) that make model functionality available to a user. The actions interpret client data from the user, call model functions, and convert the model data for display by the view.

Controller Basics

The basic function of the controller is to define what actions are available to the user. There should be one action function for each thing that the user can do, and that function should only perform that one action. The controller should not make any changes to the system, that's the function of the model. The controller should not be concerned with how to display data, that's the function of the model.

While there is usually a correspondance of one web page to one action, do not fall into the trap of thinking of an action as a web page generator. The action should not be thought of as "a function to do everything necessary for this web page", but rather "a function to perform a specific request". For example, an ACF designer may want a web page to display a list of files and a series of actions that may be done to those files. Rather than creating an action that returns a list of files and accepts commands for what to do with them, create several actions - one to simply list the files and one for each action to be done to a file. The view for the action that lists files should then generate links to each of the actions available for each file. If you would like to add some status fields to that view, rather than adding status fields to the output of the action that lists files, create another action to return status and load it as a component of the view.

MVC Functions

Each controller can define mvc functions that will be run when a controller is loaded/unloaded and before/after an action is called. The most common usage is to create an mvc.on_load function to initialize variables and control access. The controller might need to define an mvc.on_unload to free any resources loaded in mvc.on_load. More information can be found in mvc.lua example.

Default Action

While there may be many actions defined within a controller, the controller should designate one action as the default. If a user attempts to access a controller without specifying an action, the acf_www-controller will redirect them to the default action.

default_action = "status"

Inputs

When a controller is loaded by the mvc application, a table is created for the controller functions, model functions, and several other variables. This table, known as self, is the only parameter passed to each action. self also uses Lua metatables to allow the controller to access functions of acf_www-controller and mvc. The controller should not access global variables defined outside of its scope. The controller may load and use libraries.

self

The self table includes some entries that are of particular interest to controllers.

self.clientdata - The client data. Generally the information in POST or GET data from the web browser.
self.conf - The configuration data, including information about the current user request, the application, and defined directories.
self.sessiondata - The session data, containing information about user permissions, menu options, and command results.
self.model - The model table containing references to all of the model functions.

libraries

The controller has access to many libraries defined in the system. However, controller developers should be particularly interested in the controllerfunctions library. This library is designed to be a helper library for controllers, handling common functionality. If this library is used properly, most actions will only contain one line of code.

Redirection

One of the more advanced features of a controller is redirection. Using the redirect and redirect_to_referrer functions of acf_www-controller, the controller can cause the web browser to redirect to another page. The redirect function causes a simple redirect to a different page. This can be used, for example, to redirect to a listing page after successfully creating a new item using a form. The redirect_to_referrer function handles the redirection necessary for displaying forms as components and handling command actions. These are described here and here. When implementing a form or command action, you should use redirect_to_referrer.