luci-base: consider empty parameters as well when testing POST requirement
[project/luci.git] / 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.