Controllers

Controllers live in the controller subdirectory of a gluon-web application (/lib/gluon/config-mode/controller for the config mode, /lib/gluon/status-page/controller for the status page). They define which pages (“routes”) exist under the application base URL, and what code is run when these pages are requested.

Controller scripts usually start with a package declaration, followed by calls to the entry function, which each define one route:

package 'gluon-web-admin'

entry({"admin"}, alias("admin", "info"), _("Advanced settings"), 10)
entry({"admin", "info"}, template("admin/info"), _("Information"), 1)

package defines the translation namespace for the titles of the defined pages as well as the referenced views and models. The entry function expects 4 arguments:

  • path: Components of the path to define a route for.

    The above example defines routes for the paths admin and admin/info.

  • target: Dispatcher for the route. See the following section for details.

  • title: Page title (also used in navigation). The underscore function is used to mark the strings as translatable for i18n-scan.pl.

  • order: Sort index in navigation (defaults to 100)

Navigation indexes are automatically generated for each path level. Pages can be hidden from the navigation by setting the hidden property of the node object returned by entry:

entry({"hidden"}, alias("foo"), _("I'm hidden!")).hidden = true

Dispatchers

  • alias (path, …): Redirects to a different page. The path components are passed as individual arguments.

  • call (func, …): Runs a Lua function for custom request handling. The given function is called with the HTTP object and the template renderer as first two arguments, followed by all additional arguments passed to call.

  • template (view): Renders the given view. See Views.

  • model (name): Displays and evaluates a form as defined by the given model. See the Models page for an explanation of gluon-web models.

The HTTP object

The HTTP object provides information about the HTTP requests and allows to add data to the reply. Using it directly is rarely necessary when gluon-web models and views are used.

Useful functions:

  • getenv (key): Returns a value from the CGI environment passed by the webserver.

  • formvalue (key): Returns a value passed in a query string or in the content of a POST request. If multiple values with the same name have been passed, only the first is returned.

  • formvaluetable (key): Similar to formvalue, but returns a table of all values for the given key.

  • status (code, message): Writes the HTTP status to the reply. Has no effect if a status has already been sent or non-header data has been written.

  • header (key, value): Adds an HTTP header to the reply to be sent to the client. Has no effect when non-header data has already been written.

  • prepare_content (mime): Sets the Content-Type header to the given MIME type

  • write (data, …): Sends the given data to the client. If headers have not been sent, it will be done before the data is written.

HTTP functions are called in method syntax, for example:

http:write('Output!')

The template renderer

The template renderer allows to render templates (views). The most useful functions are:

  • render (view, scope, pkg): Renders the given view, optionally passing a table with additional variables to make available in the template. The passed package defines the translation namespace.

  • render_string (str, scope, pkg): Same as render, but the template is passed directly instead of being loaded from the view directory.

The renderer functions are called in property syntax, for example:

renderer.render('layout')

Differences from LuCI

  • Controllers must not use the module function to define a Lua module (gluon-web will set up a proper environment for each controller itself)

  • Entries are defined at top level, not inside an index function

  • The alias dispatcher triggers an HTTP redirect instead of directly running the dispatcher of the aliased route.

  • The call dispatcher is passed a function instead of a string with a function name.

  • The cbi dispatcher of LuCI has been renamed to model.

  • The HTTP POST handler support the multipart/form-data encoding only, so enctype="multipart/form-data" must be included in all <form> HTML elements.

  • Other dispatchers like form are not provided.