X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=documentation%2FCBI.md;h=e937fe6048a84cb7a75442e0e1203f9302e0bebd;hb=b86ed10f849c442cc57e531dd75e87e4499a1118;hp=0b47c2248bc6f3f2f43df717394d5e856606ce5c;hpb=4b11843e4ce3e7636d67cf3e987ae94ca8c8977d;p=oweals%2Fluci.git
diff --git a/documentation/CBI.md b/documentation/CBI.md
index 0b47c2248..e937fe604 100644
--- a/documentation/CBI.md
+++ b/documentation/CBI.md
@@ -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.
+All CBI model files must return an object of type **luci.cbi.Map**.
+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.
+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
+
+#### function :option(_optionclass_, ...)
+Creates a new option
+* **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.
-## .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
+----
+
+## class TypedSection (_type, title, description_)
+An object describing a group of UCI sections selected by their type.
+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
-## :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_
+If you call this function several times the dependencies will be linked with **"or"**
-# 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
+#### 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.
-## .addremove = false
+#### property .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
-
+#### property .anonymous = false
+Do not show UCI section names
-## :depends (_key'', ''value_)
-Only select those sections where the option _key'' == ''value_
-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_, ...)
-Creates a new option
- _optionclass_: a class object of the section
- additional parameters passed to the constructor of the option class
+## 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.
+To instantiate use: `NamedSection:option(Value, "option", "title", "description")`
+ or `TypedSection:option(Value, "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.
+If you call this function several times the dependencies will be linked with **"or"**
-# 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
+#### function :value(key, value)
+Convert this text field into a combobox if possible and add a selection option.
-## .default = nil
+#### property .default = nil
The default value
-## .maxlength = nil
-The maximum length of the value
+#### property .maxlength = nil
+The maximum inputlength (of chars) of the value
-## .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
-
-## :value (_key'', ''value'' = ''key_)
-Convert this text field into a combobox if possible and add a selection option.
+#### property .size = nil
+The maximum number of chars displayed by form field
+----
-## :depends (_key'', ''value_)
-Only show this option field if another option _key'' is set to ''value_ in the same section.
-If you call this function several times the dependencies will be linked with *or*
+## class ListValue (_option, title, description_)
+An object describing an option in a section of a UCI File.
+Creates a list box or list of radio (for selecting one of many choices) in the formular.
+To instantiate use: `NamedSection:option(ListValue, "option", "title", "description")`
+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.
+If you call this function several times the dependencies will be linked with **"or"**
-# 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
+#### 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
-## .default = nil
+#### property .default = nil
The default value
-## .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
+#### property .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.
-If you call this function several times the dependencies will be linked with *or*
-
-## :value (_key'', ''value'' = ''key_)
-Adds an entry to the selection list
-
----
-# 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
+## 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.
+To instantiate use: `NamedSection:option(Flag, "option", ""title", "description")`
+ or `TypedSection:option(Flag, "option", "title", "description")`
+* **option:** UCI option name
+* **title:** The title shown in the UI
+* **description:** description shown in the UI
-## .default = nil
+#### function :depends (_key, value_)
+Only show this option field if another option _key_ is set to _value_ in the same section.
+If you call this function several times the dependencies will be linked with **"or"**
+
+#### property .default = nil
The default value
-## .disabled = 0
-the value that shoudl be set if the checkbox is unchecked
+#### property .disabled = 0
+the value that should 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
+----
+## class MultiValue (_option'', ''title'', ''description_)
+An object describing an option in a section of a UCI File.
+Creates a list of checkboxed or a multiselectable list as form fields.
+To instantiate use: `NamedSection:option(MultiValue, "option", ""title", "description")`
+ or `TypedSection:option(MultiValue, "option", "title", "description")`
+* **option:** UCI option 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.
-If you call this function several times the dependencies will be linked with *or*
+#### function :depends (_key, value_)
+Only show this option field if another option _key_ is set to _value_ in the same section.
+If you call this function several times the dependencies will be linked with **"or"**
-----
+#### function :value(_key, value_)
+Adds an entry to the list
-# 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
+#### 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
-## .default = nil
+#### 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
+#### property .size = nil
+The size of the form field (only used if property _.widget = "select"_)
-## .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.
-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
+## class StaticList (_option, title, description_)
+Similar to the MultiValue, but stores selected Values into a UCI list instead of a character-separated option.
----
-# 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
+## class DynamicList (_option, title, description_)
+A extensible list of user-defined values. Stores Values into a UCI list
+----
+## class DummyValue (_option, title, description_)
+Creates a readonly text in the form. !It writes no data to UCI!
+To instantiate use: `NamedSection:option(DummyValue, "option", ""title", "description")`
+ or `TypedSection:option(DummyValue, "option", "title", "description")`
+* **option:** UCI option 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.
-If you call this function several times the dependencies will be linked with *or*
+#### property :depends (_key, value_)
+Only show this option field if another option _key_ is set to _value_ in the same section.
+If you call this function several times the dependencies will be linked with **"or"**
----
-
-# class TextValue (_option'', ''title'', ''description_)
+## 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.