126 lines
4.9 KiB
ReStructuredText
126 lines
4.9 KiB
ReStructuredText
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:
|
|
|
|
.. code-block:: lua
|
|
|
|
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`:
|
|
|
|
.. 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
|
|
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.
|