documentation/CBI.md fixed markdown formating 532/head
authorChristian Schoenebeck <christian.schoenebeck@gmail.com>
Sun, 1 Nov 2015 16:57:08 +0000 (17:57 +0100)
committerChristian Schoenebeck <christian.schoenebeck@gmail.com>
Sun, 1 Nov 2015 16:57:19 +0000 (17:57 +0100)
CBI.md: fixed markdown formating
ModulesHowTo.md: fixed to make link inside CBI.md work.

Signed-off-by: Christian Schoenebeck <christian.schoenebeck@gmail.com>
documentation/CBI.md
documentation/ModulesHowTo.md

index 0b47c2248bc6f3f2f43df717394d5e856606ce5c..4ebc08af098aa7ceee521ea9eee18598578a6e2b 100644 (file)
-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
+
+#### 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.<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
 
-## :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"**
 
-# 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_<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_, ...)
-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.<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
 
-----
+#### 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"**
 
-# 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.<br />
-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.<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"**
 
-# 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.<br />
-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.<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
 
-## .default = nil
+#### 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
 
-## .disabled = 0
+#### 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
+----
 
+## 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
 
-## :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*
+#### 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"**
 
-----
+#### 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.<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
+## 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!<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
 
-## :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 :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_)
+## 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.
index 3f70b788c5ddf8a00c855023d5373334d8b5b5ed..c4dbb982058c0d200da3f44cb7ab55a4226f909d 100644 (file)
@@ -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: