Newer
Older
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:
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``.
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
- `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`:
.. code-block:: lua
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.
.. _web-controller-http:
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 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, potentially setting additional headers or modifying the MIME type to
accommodate browser quirks
- *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:
.. code-block:: lua
http:write('Output!')
.. _web-controller-template-renderer:
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:
.. code-block:: lua
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.