docs: add documentation for gluon-web (WIP)

docs/dev/web/controller.rst

@@ -0,0 +1,117 @@
+Controllers
+===========
+
+Controllers live in ``/lib/gluon/web/controller``. They define which pages ("routes")
+exist under the ``/cgi-bin/gluon`` path, and what code is run when these pages are requested.
+
+Controller scripts mostly consist of calls of the `entry` function, which each define
+one route:
+
+.. code-block:: lua
+
+  entry({"admin"}, alias("admin", "info"), _("Advanced settings"), 10)
+  entry({"admin", "info"}, template("admin/info"), _("Information"), 1)
+
+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
+
+  - `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*): Renders the given view, optionally passing a table
+    with additional variables to make available in the template.
+  - *render_string* (*str*, *scope*): 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.

docs/dev/web/model.rst

@@ -0,0 +1,5 @@
+Models
+======
+
+Models are defined in ``/lib/gluon/web/model``. Each model defines one or more
+forms to display on a page, and how the submitted form data is handled.

docs/dev/web/view.rst

@@ -0,0 +1,53 @@
+Views
+=====
+
+The template parser reads views from ``/lib/gluon/web/view``. Views are partial
+HTML pages, with additional template tags that allow to embed Lua code and
+translation strings. The following tags are defined:
+
+  - ``<%`` ... ``%>`` evaluates the enclosed Lua expression.
+  - ``<%=`` ... ``%>`` evaluates the enclosed Lua expression and prints its value.
+  - ``<%+`` ... ``%>`` includes another template.
+  - ``<%:`` ... ``%>`` translates the enclosed string using the loaded i18n catalog.
+  - ``<%_`` ... ``%>`` translates the enclosed string *without escaping HTML entities*
+    in the translation. This only makes sense when the i18n catalog contains HTML code.
+  - ``<%#`` ... ``%>`` is a comment.
+
+All of these also come in the whitespace-stripping variants ``<%-`` and ``-%>`` that
+remove all whitespace before or after the tag.
+
+Complex combinations of HTML and Lua code are possible, for example:
+
+.. code-block:: text
+
+  <div>
+    <% if foo then %>
+      Content
+    <% end %>
+  </div>
+
+
+Variables and functions
+-----------------------
+
+Many call sites define additional variables (for example, model templates can
+access the model as *self* and an unique element ID as *id*), but the following
+variables and functions should always be available for the embedded Lua code:
+
+  - *renderer*: :ref:`web-controller-template-renderer`
+  - *http*: :ref:`web-controller-http`
+  - *request*: Table containing the path components of the current page
+  - *url* (*path*): returns the URL for the given path, which is passed as a table of path components.
+  - *attr* (*key*, *value*): Returns a string of the form ``key="value"``
+    (with a leading space character before the key).
+
+    *value* is converted to a string (tables are serialized as JSON) and HTML entities
+    are escaped. Returns an empty string when *value* is *nil* or *false*.
+  - *include* (*template*): Includes another template.
+  - *node* (*path*, ...): Returns the controller node for the given page (passed as
+    one argument per path component).
+
+    Use ``node(unpack(request))`` to get the node for the current page.
+  - *pcdata* (*str*): Escapes HTML entities in the passed string.
+  - *urlencode* (*str*): Escapes the passed string for use in an URL.
+  - *translate* and *translatef*: see :doc:`i18n`

docs/index.rst

@@ -41,11 +41,21 @@ Developer Documentation
    dev/basics
    dev/hardware
    dev/upgrade
-   dev/configmode
    dev/wan
-   dev/i18n
    dev/mac_addresses
 
+gluon-web Reference
+^^^^^^^^^^^^^^^^^^^
+
+.. toctree::
+   :maxdepth: 1
+
+   dev/web/controller
+   dev/web/model
+   dev/web/view
+   dev/web/i18n
+   dev/web/config-mode
+
 Packages
 --------