model.rst 5.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148
  1. Models
  2. ======
  3. Models are defined in ``/lib/gluon/web/model``. Each model defines one or more
  4. forms to display on a page, and how the submitted form data is handled.
  5. Let's start with an example:
  6. .. code-block:: lua
  7. local f = Form(translate('Hostname'))
  8. local s = f:section(Section)
  9. local o = s:option(Value, 'hostname', translate('Hostname'))
  10. o.default = uci:get_first('system', 'system', 'hostname')
  11. function o:write(data)
  12. uci:set('system', uci:get_first('system', 'system'), 'hostname', data)
  13. uci:commit('system')
  14. end
  15. return f
  16. The toplevel element of a model is always a *Form*, but it is also possible for
  17. a model to return multiple forms, which are displayed one below the other.
  18. A *Form* has one or more *Sections*, and each *Section* has different types
  19. of options.
  20. All of these elements have an *id*, which is used to identify them in the HTML
  21. form and handlers. If no ID is given, numerical IDs will be assigned automatically,
  22. but using explicitly named elements is often advisable (and it is required if a
  23. form does not always include the same elements, i.e., some forms, sections or
  24. options are added conditionally). IDs are hierarchical, so in the above example,
  25. the *Value* would get the ID ``1.1.hostname`` (value *hostname* in first section
  26. of first form).
  27. Classes and methods
  28. -------------------
  29. - *Form* (*title*, *description*, *id*)
  30. - *Form:section* (*type*, *title*, *description*, *id*)
  31. Creates a new section of the given type (usually *Section*).
  32. - *Form:write* ()
  33. Is called after the form has beed submitted (but only if the data is valid). It
  34. is called last (after all options' *write* methods) and is usually used
  35. to commit changed UCI packages.
  36. The default implementation of *write* doesn't do anything, but it can be
  37. overridden.
  38. - *Section* (usually instanciated through *Form:section*)
  39. - *Section:option* (*type*, *id*, *title*, *description*)
  40. Creates a new option of the given type. Option types:
  41. - *Value*: simple text entry
  42. - *TextValue*: multiline text field
  43. - *ListValue*: radio buttons or dropdown selection
  44. - *DynamicList*: variable number of text entry fields
  45. - *Flag*: checkbox
  46. Most option types share the same properties and methods:
  47. - *default*: default value
  48. - *optional*: value may be empty
  49. - *datatype*: one of the types described in :ref:`web-model-datatypes`
  50. By default (when *datatype* is *nil*), all values are accepted.
  51. - *state*: has one of the values *FORM_NODATA*, *FORM_VALID* and *FORM_INVALID*
  52. when read in a form handler
  53. An option that has not been submitted because of its dependencies will have
  54. the state *FORM_NODATA*, *FORM_INVALID* if the submitted value is not valid
  55. according to the set *datatype*, and *FORM_VALID* otherwise.
  56. - *data*: can be read in form handlers to get the submitted value
  57. - *depends* (*self*, *option*, *value*): adds a dependency on another option
  58. The option will only be shown when the passed option has the given value. This
  59. is mainly useful when the other value is a *Flag* or *ListValue*.
  60. - *depends* (*self*, *deps*): adds a dependency on multiple other options
  61. *deps* must be a table with options as keys and values as values. The option
  62. will only be shown when all passed options have the corresponding values.
  63. Multiple alternative dependencies can be added by calling *depends* repeatedly.
  64. - *value* (*self*, *value*, *text*): adds a choice to a *ListValue*
  65. - *write* (*self*, *data*): is called with the submitted value when all form data is valid.
  66. Does not do anything by default, but can be overridden.
  67. The *default* value, the *value* argument to *depends* and the output *data* always have
  68. the same type, which is usually a string (or *nil* for optional values). Exceptions
  69. are:
  70. - *Flag* uses boolean values
  71. - *DynamicList* uses a table of strings
  72. Despite its name, the *datatype* setting does not affect the returned value type,
  73. but only defines a validator the check the submitted value with.
  74. For a more complete example that actually makes use of most of these features,
  75. have a look at the model of the *gluon-web-network* package.
  76. .. _web-model-datatypes:
  77. Data types
  78. ----------
  79. - *integer*: an integral number
  80. - *uinteger*: an integral number greater than or equal to zero
  81. - *float*: a number
  82. - *ufloat*: a number greater than or equal to zero
  83. - *ipaddr*: an IPv4 or IPv6 address
  84. - *ip4addr*: an IPv4 address
  85. - *ip6addr*: an IPv6 address
  86. - *wpakey*: a string usable as a WPA key (either between 8 and 63 characters, or 64 hex digits)
  87. - *range* (*min*, *max*): a number in the given range (inclusive)
  88. - *min* (*min*): a number greater than or equal to the given minimum
  89. - *max* (*max*): a number less than or equal to the given maximum
  90. - *irange* (*min*, *max*): an integral number in the given range (inclusive)
  91. - *imin* (*min*): an integral number greater than or equal to the given minimum
  92. - *imax* (*max*): an integral number less than or equal to the given maximum
  93. - *minlength* (*min*): a string with the given minimum length
  94. - *maxlength* (*max*): a string with the given maximum length
  95. Differences from LuCI
  96. ---------------------
  97. - LuCI's *SimpleForm* and *SimpleSection* are called *Form* and *Section*, respectively
  98. - Is it not possible to add options to a *Form* directly, a *Section* must always
  99. be created explicitly
  100. - Many of LuCI's CBI classes have been removed, most importantly the *Map*
  101. - The *rmempty* option attribute does not exist, use *optional* instead
  102. - Only the described data types are supported
  103. - Form handlers work completely differently (in particular, a *Form*'s *handle*
  104. method should usually not be overridden in *gluon-web*)