documentation/CBI.md

   1 CBI models are Lua files describing the structure of an UCI config file and the resulting HTML form to be evaluated by the CBI parser.
   2 All CBI model files must return an object of type *luci.cbi.Map*. For a commented example of a CBI model, see the [[Documentation/ModulesHowTo#CBImodels|Writing Modules tutorial]].
   3
   4 The scope of a CBI model file is automatically extended by the contents of the module *luci.cbi_' and the '_translate* function from luci.i18n
   5
   6 This Reference covers *the basics* of the CBI system.
   7
   8
   9
  10 # class Map (_config'', ''title'', ''description_)
  11 This is the root object of the model.
  12 * *config*: configuration name to be mapped, see uci documentation and the files in /etc/config
  13 * *title*: title shown in the UI
  14 * *description*: description shown in the UI
  15
  16 ## :section (_sectionclass_, ...)
  17 Creates a new section
  18 * *sectionclass*: a class object of the section
  19 * _additional parameters passed to the constructor of the section class_
  20
  21 ----
  22
  23 # class NamedSection (_name'', ''type'', ''title'', ''description_)
  24 An object describing an UCI section selected by the name.
  25 Use [[#A.3Asection.28.27.27sectionclass.27.27.2C....29|Map:section(NamedSection, _name'', ''type'', ''title'', ''description_)]] to instantiate.
  26 * *name*: section name
  27 * *type*: section type
  28 * *title*: The title shown in the UI
  29 * *description*: description shown in the UI
  30
  31 ## .addremove = false
  32 Allows the user to remove and recreate the configuration section
  33
  34 ## .dynamic = false
  35 Marks this section as dynamic. Dynamic sections can contain an undefinded number of completely userdefined options.
  36
  37 ## .optional = true
  38 Parse optional options
  39
  40
  41 ## :option (_optionclass_, ...)
  42 Creates a new option
  43 * *optionclass*: a class object of the section
  44 * _additional parameters passed to the constructor of the option class_
  45
  46 ----
  47
  48 # class TypedSection (_type'', ''title'', ''description_)
  49 An object describing a group of UCI sections selected by their type.
  50 Use [[#A.3Asection.28.27.27sectionclass.27.27.2C....29|Map:section(TypedSection, _type'', ''title'', ''description_)]] to instantiate.
  51 * *type*: section type
  52 * *title*: The title shown in the UI
  53 * *description*: description shown in the UI
  54
  55 ## .addremove = false
  56 Allows the user to remove and recreate the configuration section
  57
  58 ## .dynamic = false
  59 Marks this section as dynamic. Dynamic sections can contain an undefinded number of completely userdefined options.
  60
  61 ## .optional = true
  62 Parse optional options
  63
  64 ## .anonymous = false
  65 Do not show section names
  66
  67
  68 ## :depends (_key'', ''value_)
  69 Only select those sections where the option _key'' == ''value_<br />
  70 If you call this function several times the dependencies will be linked with *or*
  71
  72 ## .filter (_self'', ''section_) [abstract]
  73 You can override this function to filter certain sections that will not be parsed.
  74 The filter function will be called for every section that should be parsed and returns *nil* for sections that should be filtered. For all other sections it should return the section name as given in the second parameter.
  75
  76 ## :option (_optionclass_, ...)
  77 Creates a new option
  78  _optionclass_: a class object of the section
  79  additional parameters passed to the constructor of the option class
  80
  81 ----
  82
  83 # class Value (_option'', ''title'', ''description_)
  84 An object describing an option in a section of a UCI File. Creates a standard text field in the formular.
  85 Use [[#A.3Aoption.28.27.27optionclass.27.27.2C....29|NamedSection:option(Value, _option'', ''title'', ''description'')]] or [[#A.3Aoption.28.27.27optionclass.27.27.2C....29-1|TypedSection:option(Value, ''option'', ''title'', ''description_)]] to instantiate.
  86 * *option*: section name
  87 * *title*: The title shown in the UI
  88 * *description*: description shown in the UI
  89
  90 ## .default = nil
  91 The default value
  92
  93 ## .maxlength = nil
  94 The maximum length of the value
  95
  96 ## .optional = false
  97 Marks this option as optional, implies .rmempty = true
  98
  99 ## .rmempty = true
 100 Removes this option from the configuration file when the user enters an empty value
 101
 102 ## .size = nil
 103 The size of the form field
 104
 105 ## :value (_key'', ''value'' = ''key_)
 106 Convert this text field into a combobox if possible and add a selection option.
 107
 108
 109 ## :depends (_key'', ''value_)
 110 Only show this option field if another option _key'' is set to ''value_ in the same section.<br />
 111 If you call this function several times the dependencies will be linked with *or*
 112
 113 ----
 114
 115 # class ListValue (_option'', ''title'', ''description_)
 116 An object describing an option in a section of a UCI File. Creates a list box in the formular.
 117 Use [[#A.3Aoption.28.27.27optionclass.27.27.2C....29|NamedSection:option(Value, _option'', ''title'', ''description'')]] or [[#A.3Aoption.28.27.27optionclass.27.27.2C....29-1|TypedSection:option(Value, ''option'', ''title'', ''description_)]] to instantiate.
 118 * *option*: section name
 119 * *title*: The title shown in the UI
 120 * *description*: description shown in the UI
 121
 122
 123 ## .default = nil
 124 The default value
 125
 126 ## .optional = false
 127 Marks this option as optional, implies .rmempty = true
 128
 129 ## .rmempty = true
 130 Removes this option from the configuration file when the user enters an empty value
 131
 132 ## .size = nil
 133 The size of the form field
 134
 135 ## .widget = "select"
 136 selects the form widget to be used
 137
 138
 139 ## :depends (_key'', ''value_)
 140 Only show this option field if another option _key'' is set to ''value_ in the same section.<br />
 141 If you call this function several times the dependencies will be linked with *or*
 142
 143 ## :value (_key'', ''value'' = ''key_)
 144 Adds an entry to the selection list
 145
 146 ----
 147
 148 # class Flag (_option'', ''title'', ''description_)
 149 An object describing an option with two possible values in a section of a UCI File. Creates a checkbox field in the formular.
 150 Use [[#A.3Aoption.28.27.27optionclass.27.27.2C....29|NamedSection:option(Value, _option'', ''title'', ''description'')]] or [[#A.3Aoption.28.27.27optionclass.27.27.2C....29-1|TypedSection:option(Value, ''option'', ''title'', ''description_)]] to instantiate.
 151 * *option*: section name
 152 * *title*: The title shown in the UI
 153 * *description*: description shown in the UI
 154
 155 ## .default = nil
 156 The default value
 157
 158 ## .disabled = 0
 159 the value that shoudl be set if the checkbox is unchecked
 160
 161 ## .enabled = 1
 162 the value that should be set if the checkbox is checked
 163
 164 ## .optional = false
 165 Marks this option as optional, implies .rmempty = true
 166
 167 ## .rmempty = true
 168 Removes this option from the configuration file when the user enters an empty value
 169
 170 ## .size = nil
 171 The size of the form field
 172
 173
 174 ## :depends (_key'', ''value_)
 175 Only show this option field if another option _key'' is set to ''value_ in the same section.<br />
 176 If you call this function several times the dependencies will be linked with *or*
 177
 178 ----
 179
 180 # class MultiValue (_option'', ''title'', ''description_)
 181 An object describing an option in a section of a UCI File. Creates several checkboxed as form fields.
 182 Use [[#A.3Aoption.28.27.27optionclass.27.27.2C....29|NamedSection:option(Value, _option'', ''title'', ''description'')]] or [[#A.3Aoption.28.27.27optionclass.27.27.2C....29-1|TypedSection:option(Value, ''option'', ''title'', ''description_)]] to instantiate.
 183 * *option*: section name
 184 * *title*: The title shown in the UI
 185 * *description*: description shown in the UI
 186
 187
 188 ## .default = nil
 189 The default value
 190
 191 ## .delimiter = " "
 192 The string which will be used to delimit the values
 193
 194 ## .optional = false
 195 Marks this option as optional, implies .rmempty = true
 196
 197 ## .rmempty = true
 198 Removes this option from the configuration file when the user enters an empty value
 199
 200 ## .size = nil
 201 The size of the form field
 202
 203 ## .widget = "checkbox"
 204 selects the form widget to be used
 205
 206
 207 ## :depends (_key'', ''value_)
 208 Only show this option field if another option _key'' is set to ''value_ in the same section.<br />
 209 If you call this function several times the dependencies will be linked with *or*
 210
 211 ## :value (_key'', ''value'' = ''key_)
 212 Adds an entry to the checkbox list
 213
 214 ----
 215
 216 # class DummyValue (_option'', ''title'', ''description_)
 217 An object describing an option in a section of a UCI File. Creates a readonly field in the form.
 218 Use [[#A.3Aoption.28.27.27optionclass.27.27.2C....29|NamedSection:option(Value, _option'', ''title'', ''description'')]] or [[#A.3Aoption.28.27.27optionclass.27.27.2C....29-1|TypedSection:option(Value, ''option'', ''title'', ''description_)]] to instantiate.
 219 * *option*: section name
 220 * *title*: The title shown in the UI
 221 * *description*: description shown in the UI
 222
 223
 224
 225 ## :depends (_key'', ''value_)
 226 Only show this option field if another option _key'' is set to ''value_ in the same section.<br />
 227 If you call this function several times the dependencies will be linked with *or*
 228
 229 ----
 230
 231
 232 # class TextValue (_option'', ''title'', ''description_)
 233 An object describing a multi-line textbox in a section in a non-UCI form.
 234
 235 ----
 236
 237 # class Button (_option'', ''title'', ''description_)
 238 An object describing a Button in a section in a non-UCI form.
 239
 240 ----
 241
 242 # class StaticList (_option'', ''title'', ''description_)
 243 Similar to the MultiValue, but stores selected Values into a UCI list instead of a space-separated string.
 244
 245 ----
 246
 247 # class DynamicList (_option'', ''title'', ''description_)
 248 A list of user-defined values.