view.rst 2.3 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455
  1. Views
  2. =====
  3. The template parser reads views from ``/lib/gluon/web/view``. Writing own view
  4. should be avoided in favour of using :doc:`model` with their predefined views.
  5. Views are partial HTML pages, with additional template tags that allow
  6. to embed Lua code and translation strings. The following tags are defined:
  7. - ``<%`` ... ``%>`` evaluates the enclosed Lua expression.
  8. - ``<%=`` ... ``%>`` evaluates the enclosed Lua expression and prints its value.
  9. - ``<%+`` ... ``%>`` includes another template.
  10. - ``<%:`` ... ``%>`` translates the enclosed string using the loaded i18n catalog.
  11. - ``<%_`` ... ``%>`` translates the enclosed string *without escaping HTML entities*
  12. in the translation. This only makes sense when the i18n catalog contains HTML code.
  13. - ``<%#`` ... ``%>`` is a comment.
  14. All of these also come in the whitespace-stripping variants ``<%-`` and ``-%>`` that
  15. remove all whitespace before or after the tag.
  16. Complex combinations of HTML and Lua code are possible, for example:
  17. .. code-block:: text
  18. <div>
  19. <% if foo then %>
  20. Content
  21. <% end %>
  22. </div>
  23. Variables and functions
  24. -----------------------
  25. Many call sites define additional variables (for example, model templates can
  26. access the model as *self* and a unique element ID as *id*), but the following
  27. variables and functions should always be available for the embedded Lua code:
  28. - *renderer*: :ref:`web-controller-template-renderer`
  29. - *http*: :ref:`web-controller-http`
  30. - *request*: Table containing the path components of the current page
  31. - *url* (*path*): returns the URL for the given path, which is passed as a table of path components.
  32. - *attr* (*key*, *value*): Returns a string of the form ``key="value"``
  33. (with a leading space character before the key).
  34. *value* is converted to a string (tables are serialized as JSON) and HTML entities
  35. are escaped. Returns an empty string when *value* is *nil* or *false*.
  36. - *include* (*template*): Includes another template.
  37. - *node* (*path*, ...): Returns the controller node for the given page (passed as
  38. one argument per path component).
  39. Use ``node(unpack(request))`` to get the node for the current page.
  40. - *pcdata* (*str*): Escapes HTML entities in the passed string.
  41. - *urlencode* (*str*): Escapes the passed string for use in an URL.
  42. - *translate*, *_translate* and *translatef*: see :doc:`i18n`