documentation/CBI.md

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