controller.rst
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
andadmin/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 :doc:`view`.
- model (name): Displays and evaluates a form as defined by the given model. See the :doc:`model` 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!')