Merge pull request #532 from chris5560/master
documentation/CBI.md fixed markdown formating
This commit is contained in:
Christian Schoenebeck
commit
20851933bf
2 changed files with 175 additions and 177 deletions
|
|
@ -1,248 +1,246 @@
|
|||
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.
|
||||
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]].
|
||||
|
||||
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
|
||||
# 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 />
|
||||
All CBI model files must return an object of type **luci.cbi.Map**.<br />
|
||||
For a commented example of a CBI model, see the [Writing Modules tutorial](ModulesHowTo.md#cbimodels).
|
||||
|
||||
This Reference covers *the basics* of the CBI system.
|
||||
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**
|
||||
|
||||
This Reference covers **the basics** of the CBI system.
|
||||
|
||||
|
||||
|
||||
# class Map (_config'', ''title'', ''description_)
|
||||
## class Map (_config, title, description_)
|
||||
This is the root object of the model.
|
||||
* *config*: configuration name to be mapped, see uci documentation and the files in /etc/config
|
||||
* *title*: title shown in the UI
|
||||
* *description*: description shown in the UI
|
||||
|
||||
## :section (_sectionclass_, ...)
|
||||
* **config:** configuration filename to be mapped, see [UCI documentation](http://wiki.openwrt.org/doc/uci) and the files in /etc/config
|
||||
* **title:** title shown in the UI
|
||||
* **description:** description shown in the UI
|
||||
|
||||
#### function :section (_sectionclass_, ...)
|
||||
Creates a new section
|
||||
* *sectionclass*: a class object of the section
|
||||
* **sectionclass**: a class object of the section
|
||||
* _additional parameters passed to the constructor of the section class_
|
||||
|
||||
----
|
||||
|
||||
# class NamedSection (_name'', ''type'', ''title'', ''description_)
|
||||
An object describing an UCI section selected by the name.
|
||||
Use [[#A.3Asection.28.27.27sectionclass.27.27.2C....29|Map:section(NamedSection, _name'', ''type'', ''title'', ''description_)]] to instantiate.
|
||||
* *name*: section name
|
||||
* *type*: section type
|
||||
* *title*: The title shown in the UI
|
||||
* *description*: description shown in the UI
|
||||
## class NamedSection (_name, type, title, description_)
|
||||
An object describing an UCI section selected by the name.<br />
|
||||
To instantiate use: `Map:section(NamedSection, "name", "type", "title", "description")`
|
||||
|
||||
## .addremove = false
|
||||
Allows the user to remove and recreate the configuration section
|
||||
* **name:** UCI section name
|
||||
* **type:** UCI section type
|
||||
* **title:** The title shown in the UI
|
||||
* **description:** description shown in the UI
|
||||
|
||||
## .dynamic = false
|
||||
Marks this section as dynamic. Dynamic sections can contain an undefinded number of completely userdefined options.
|
||||
|
||||
## .optional = true
|
||||
Parse optional options
|
||||
|
||||
|
||||
## :option (_optionclass_, ...)
|
||||
#### function :option(_optionclass_, ...)
|
||||
Creates a new option
|
||||
* *optionclass*: a class object of the section
|
||||
* **optionclass:** a class object of the section
|
||||
* _additional parameters passed to the constructor of the option class_
|
||||
|
||||
----
|
||||
#### property .addremove = false
|
||||
Allows the user to remove and recreate the configuration section.
|
||||
|
||||
# class TypedSection (_type'', ''title'', ''description_)
|
||||
An object describing a group of UCI sections selected by their type.
|
||||
Use [[#A.3Asection.28.27.27sectionclass.27.27.2C....29|Map:section(TypedSection, _type'', ''title'', ''description_)]] to instantiate.
|
||||
* *type*: section type
|
||||
* *title*: The title shown in the UI
|
||||
* *description*: description shown in the UI
|
||||
|
||||
## .addremove = false
|
||||
Allows the user to remove and recreate the configuration section
|
||||
|
||||
## .dynamic = false
|
||||
#### property .dynamic = false
|
||||
Marks this section as dynamic. Dynamic sections can contain an undefinded number of completely userdefined options.
|
||||
|
||||
## .optional = true
|
||||
#### property .optional = true
|
||||
Parse optional options
|
||||
|
||||
## .anonymous = false
|
||||
Do not show section names
|
||||
----
|
||||
|
||||
## class TypedSection (_type, title, description_)
|
||||
An object describing a group of UCI sections selected by their type.<br />
|
||||
To instantiate use: `Map:section(TypedSection, "type", "title", "description")`
|
||||
* **type:** UCI section type
|
||||
* **title:** The title shown in the UI
|
||||
* **description:** description shown in the UI
|
||||
|
||||
## :depends (_key'', ''value_)
|
||||
Only select those sections where the option _key'' == ''value_<br />
|
||||
If you call this function several times the dependencies will be linked with *or*
|
||||
|
||||
## .filter (_self'', ''section_) [abstract]
|
||||
You can override this function to filter certain sections that will not be parsed.
|
||||
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.
|
||||
|
||||
## :option (_optionclass_, ...)
|
||||
#### function :option(_optionclass_, ...)
|
||||
Creates a new option
|
||||
_optionclass_: a class object of the section
|
||||
additional parameters passed to the constructor of the option class
|
||||
**optionclass:** a class object of the section
|
||||
_additional parameters passed to the constructor of the option class_
|
||||
|
||||
#### function :depends(_key, value_)
|
||||
Only select those sections where _key == value_ <br />
|
||||
If you call this function several times the dependencies will be linked with **"or"**
|
||||
|
||||
#### function .filter(_self, section_) -abstract-
|
||||
You can override this function to filter certain sections that will not be parsed.
|
||||
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.
|
||||
|
||||
#### property .addremove = false
|
||||
Allows the user to remove and recreate the configuration section
|
||||
|
||||
#### property .dynamic = false
|
||||
Marks this section as dynamic. Dynamic sections can contain an undefinded number of completely userdefined options.
|
||||
|
||||
#### property .optional = true
|
||||
Parse optional options
|
||||
|
||||
#### property .anonymous = false
|
||||
Do not show UCI section names
|
||||
|
||||
----
|
||||
|
||||
# class Value (_option'', ''title'', ''description_)
|
||||
An object describing an option in a section of a UCI File. Creates a standard text field in the formular.
|
||||
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.
|
||||
* *option*: section name
|
||||
* *title*: The title shown in the UI
|
||||
* *description*: description shown in the UI
|
||||
## class Value (_option, title, description_)
|
||||
An object describing an option in a section of a UCI File. Creates a standard text field in the formular.<br />
|
||||
To instantiate use: `NamedSection:option(Value, "option", "title", "description")`<br />
|
||||
or `TypedSection:option(Value, "option", "title", "description")`
|
||||
* **option:** UCI option name
|
||||
* **title:** The title shown in the UI
|
||||
* **description:** description shown in the UI
|
||||
|
||||
## .default = nil
|
||||
The default value
|
||||
#### function :depends(key, value)
|
||||
Only show this option field if another option _key_ is set to _value_ in the same section.<br />
|
||||
If you call this function several times the dependencies will be linked with **"or"**
|
||||
|
||||
## .maxlength = nil
|
||||
The maximum length of the value
|
||||
|
||||
## .optional = false
|
||||
Marks this option as optional, implies .rmempty = true
|
||||
|
||||
## .rmempty = true
|
||||
Removes this option from the configuration file when the user enters an empty value
|
||||
|
||||
## .size = nil
|
||||
The size of the form field
|
||||
|
||||
## :value (_key'', ''value'' = ''key_)
|
||||
#### function :value(key, value)
|
||||
Convert this text field into a combobox if possible and add a selection option.
|
||||
|
||||
#### property .default = nil
|
||||
The default value
|
||||
|
||||
## :depends (_key'', ''value_)
|
||||
Only show this option field if another option _key'' is set to ''value_ in the same section.<br />
|
||||
If you call this function several times the dependencies will be linked with *or*
|
||||
#### property .maxlength = nil
|
||||
The maximum inputlength (of chars) of the value
|
||||
|
||||
#### property .optional = false
|
||||
Marks this option as optional, implies .rmempty = true
|
||||
|
||||
#### property .rmempty = true
|
||||
Removes this option from the configuration file when the user enters an empty value
|
||||
|
||||
#### property .size = nil
|
||||
The maximum number of chars displayed by form field
|
||||
|
||||
----
|
||||
|
||||
# class ListValue (_option'', ''title'', ''description_)
|
||||
An object describing an option in a section of a UCI File. Creates a list box in the formular.
|
||||
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.
|
||||
* *option*: section name
|
||||
* *title*: The title shown in the UI
|
||||
* *description*: description shown in the UI
|
||||
## class ListValue (_option, title, description_)
|
||||
An object describing an option in a section of a UCI File.<br />
|
||||
Creates a list box or list of radio (for selecting one of many choices) in the formular.<br />
|
||||
To instantiate use: `NamedSection:option(ListValue, "option", "title", "description")`<br />
|
||||
or `TypedSection:option(ListValue, "option", "title", "description")`
|
||||
* **option:** UCI option name
|
||||
* **title:** The title shown in the UI
|
||||
* **description:** description shown in the UI
|
||||
|
||||
#### function :depends(key, value)
|
||||
Only show this option field if another option _key_ is set to _value_ in the same section.<br />
|
||||
If you call this function several times the dependencies will be linked with **"or"**
|
||||
|
||||
## .default = nil
|
||||
The default value
|
||||
|
||||
## .optional = false
|
||||
Marks this option as optional, implies .rmempty = true
|
||||
|
||||
## .rmempty = true
|
||||
Removes this option from the configuration file when the user enters an empty value
|
||||
|
||||
## .size = nil
|
||||
The size of the form field
|
||||
|
||||
## .widget = "select"
|
||||
selects the form widget to be used
|
||||
|
||||
|
||||
## :depends (_key'', ''value_)
|
||||
Only show this option field if another option _key'' is set to ''value_ in the same section.<br />
|
||||
If you call this function several times the dependencies will be linked with *or*
|
||||
|
||||
## :value (_key'', ''value'' = ''key_)
|
||||
#### function :value(_key, value_)
|
||||
Adds an entry to the selection list
|
||||
|
||||
----
|
||||
#### property .widget = "select"
|
||||
**"select"** shows a selction list, **"radio"** shows a list of radio buttons inside form
|
||||
|
||||
# class Flag (_option'', ''title'', ''description_)
|
||||
An object describing an option with two possible values in a section of a UCI File. Creates a checkbox field in the formular.
|
||||
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.
|
||||
* *option*: section name
|
||||
* *title*: The title shown in the UI
|
||||
* *description*: description shown in the UI
|
||||
|
||||
## .default = nil
|
||||
#### property .default = nil
|
||||
The default value
|
||||
|
||||
## .disabled = 0
|
||||
#### property .optional = false
|
||||
Marks this option as optional, implies .rmempty = true
|
||||
|
||||
#### property .rmempty = true
|
||||
Removes this option from the configuration file when the user enters an empty value
|
||||
|
||||
#### property .size = nil
|
||||
The size of the form field
|
||||
|
||||
----
|
||||
|
||||
## class Flag (_option, title, description_)
|
||||
An object describing an option with two possible values in a section of a UCI File.<br />
|
||||
Creates a checkbox field in the formular.<br />
|
||||
To instantiate use: `NamedSection:option(Flag, "option", ""title", "description")`<br />
|
||||
or `TypedSection:option(Flag, "option", "title", "description")`
|
||||
* **option:** UCI option name
|
||||
* **title:** The title shown in the UI
|
||||
* **description:** description shown in the UI
|
||||
|
||||
#### function :depends (_key, value_)
|
||||
Only show this option field if another option _key_ is set to _value_ in the same section.<br />
|
||||
If you call this function several times the dependencies will be linked with **"or"**
|
||||
|
||||
#### property .default = nil
|
||||
The default value
|
||||
|
||||
#### property .disabled = 0
|
||||
the value that shoudl be set if the checkbox is unchecked
|
||||
|
||||
## .enabled = 1
|
||||
#### property .enabled = 1
|
||||
the value that should be set if the checkbox is checked
|
||||
|
||||
## .optional = false
|
||||
#### property .optional = false
|
||||
Marks this option as optional, implies .rmempty = true
|
||||
|
||||
## .rmempty = true
|
||||
#### property .rmempty = true
|
||||
Removes this option from the configuration file when the user enters an empty value
|
||||
|
||||
## .size = nil
|
||||
The size of the form field
|
||||
|
||||
|
||||
## :depends (_key'', ''value_)
|
||||
Only show this option field if another option _key'' is set to ''value_ in the same section.<br />
|
||||
If you call this function several times the dependencies will be linked with *or*
|
||||
|
||||
----
|
||||
|
||||
# class MultiValue (_option'', ''title'', ''description_)
|
||||
An object describing an option in a section of a UCI File. Creates several checkboxed as form fields.
|
||||
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.
|
||||
* *option*: section name
|
||||
* *title*: The title shown in the UI
|
||||
* *description*: description shown in the UI
|
||||
## class MultiValue (_option'', ''title'', ''description_)
|
||||
An object describing an option in a section of a UCI File.<br />
|
||||
Creates a list of checkboxed or a multiselectable list as form fields.<br />
|
||||
To instantiate use: `NamedSection:option(MultiValue, "option", ""title", "description")`<br />
|
||||
or `TypedSection:option(MultiValue, "option", "title", "description")`
|
||||
* **option:** UCI option name
|
||||
* **title:** The title shown in the UI
|
||||
* **description:** description shown in the UI
|
||||
|
||||
#### function :depends (_key, value_)
|
||||
Only show this option field if another option _key_ is set to _value_ in the same section.<br />
|
||||
If you call this function several times the dependencies will be linked with **"or"**
|
||||
|
||||
## .default = nil
|
||||
#### function :value(_key, value_)
|
||||
Adds an entry to the list
|
||||
|
||||
#### property .widget = "checkbox"
|
||||
**"select"** shows a selction list, **"checkbox"** shows a list of checkboxes inside form
|
||||
|
||||
#### property .delimiter = " "
|
||||
The string which will be used to delimit the values inside stored option
|
||||
|
||||
#### property .default = nil
|
||||
The default value
|
||||
|
||||
## .delimiter = " "
|
||||
The string which will be used to delimit the values
|
||||
|
||||
## .optional = false
|
||||
#### property .optional = false
|
||||
Marks this option as optional, implies .rmempty = true
|
||||
|
||||
## .rmempty = true
|
||||
#### property .rmempty = true
|
||||
Removes this option from the configuration file when the user enters an empty value
|
||||
|
||||
## .size = nil
|
||||
The size of the form field
|
||||
|
||||
## .widget = "checkbox"
|
||||
selects the form widget to be used
|
||||
|
||||
|
||||
## :depends (_key'', ''value_)
|
||||
Only show this option field if another option _key'' is set to ''value_ in the same section.<br />
|
||||
If you call this function several times the dependencies will be linked with *or*
|
||||
|
||||
## :value (_key'', ''value'' = ''key_)
|
||||
Adds an entry to the checkbox list
|
||||
#### property .size = nil
|
||||
The size of the form field (only used if property _.widget = "select"_)
|
||||
|
||||
----
|
||||
|
||||
# class DummyValue (_option'', ''title'', ''description_)
|
||||
An object describing an option in a section of a UCI File. Creates a readonly field in the form.
|
||||
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.
|
||||
* *option*: section name
|
||||
* *title*: The title shown in the UI
|
||||
* *description*: description shown in the UI
|
||||
|
||||
|
||||
|
||||
## :depends (_key'', ''value_)
|
||||
Only show this option field if another option _key'' is set to ''value_ in the same section.<br />
|
||||
If you call this function several times the dependencies will be linked with *or*
|
||||
## class StaticList (_option, title, description_)
|
||||
Similar to the MultiValue, but stores selected Values into a UCI list instead of a character-separated option.
|
||||
|
||||
----
|
||||
|
||||
## class DynamicList (_option, title, description_)
|
||||
A extensible list of user-defined values. Stores Values into a UCI list
|
||||
|
||||
# class TextValue (_option'', ''title'', ''description_)
|
||||
----
|
||||
|
||||
## class DummyValue (_option, title, description_)
|
||||
Creates a readonly text in the form. !It writes no data to UCI!<br />
|
||||
To instantiate use: `NamedSection:option(DummyValue, "option", ""title", "description")`<br />
|
||||
or `TypedSection:option(DummyValue, "option", "title", "description")`
|
||||
* **option:** UCI option name
|
||||
* **title:** The title shown in the UI
|
||||
* **description:** description shown in the UI
|
||||
|
||||
#### property :depends (_key, value_)
|
||||
Only show this option field if another option _key_ is set to _value_ in the same section.<br />
|
||||
If you call this function several times the dependencies will be linked with **"or"**
|
||||
|
||||
----
|
||||
|
||||
## class TextValue (_option, title, description_)
|
||||
An object describing a multi-line textbox in a section in a non-UCI form.
|
||||
|
||||
----
|
||||
|
||||
# class Button (_option'', ''title'', ''description_)
|
||||
## class Button (_option, title, description_)
|
||||
An object describing a Button in a section in a non-UCI form.
|
||||
|
||||
----
|
||||
|
||||
# class StaticList (_option'', ''title'', ''description_)
|
||||
Similar to the MultiValue, but stores selected Values into a UCI list instead of a space-separated string.
|
||||
|
||||
----
|
||||
|
||||
# class DynamicList (_option'', ''title'', ''description_)
|
||||
A list of user-defined values.
|
||||
|
|
|
|||
|
|
@ -101,7 +101,7 @@ Now type */cgi-bin/luci/my/new/template_' ('_[http://localhost:8080/luci/my/new/
|
|||
You may notice those fancy <% %>-Tags, these are [wiki:Documentation/Templates|template markups] used by the LuCI template processor.
|
||||
It is always good to include header and footer at the beginning and end of a template as those create the default design and menu.
|
||||
|
||||
## CBI models
|
||||
## <a name=cbimodels></a> CBI models
|
||||
The CBI is one of the uber coolest features of LuCI. It creates a formular based user interface and saves its contents to a specific UCI config file. You only have to describe the structure of the configuration file in a CBI model file and Luci does the rest of the work. This includes generating, parsing and validating a XHTML form and reading and writing the UCI file.
|
||||
|
||||
So let's be serious at least for this paragraph and create a real pratical example *_lucidir_/model/cbi/myapp-mymodule/netifaces.lua* with the following contents:
|
||||
|
|
|
|||
Loading…
Reference in a new issue