CBI.md

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