diff options
Diffstat (limited to 'documentation')
| -rw-r--r-- | documentation/CBI.md | 302 | ||||
| -rw-r--r-- | documentation/ModulesHowTo.md | 2 | ||||
| -rw-r--r-- | documentation/SubmitPatchesHowTo:.md | 33 | ||||
| -rw-r--r-- | documentation/api/modules/luci.jsonc.parser.html | 35 | ||||
| -rw-r--r-- | documentation/api/modules/luci.model.uci.html | 8 |
5 files changed, 193 insertions, 187 deletions
diff --git a/documentation/CBI.md b/documentation/CBI.md index 0b47c2248b..4ebc08af09 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.<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. diff --git a/documentation/ModulesHowTo.md b/documentation/ModulesHowTo.md index 3f70b788c5..c4dbb98205 100644 --- a/documentation/ModulesHowTo.md +++ b/documentation/ModulesHowTo.md @@ -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: diff --git a/documentation/SubmitPatchesHowTo:.md b/documentation/SubmitPatchesHowTo:.md deleted file mode 100644 index cdd15524a5..0000000000 --- a/documentation/SubmitPatchesHowTo:.md +++ /dev/null @@ -1,33 +0,0 @@ -# Checkout svn - - svn co http://svn.luci.subsignal.org/luci/trunk - -and change to that directory: - - cd trunk - -# Make your changes - -Edit the files you want to change. If you add some new files you need to add them to the svn tree: - - svn add <dir/files> - -Where <dir/files> are the directories/files you have added. Its possible to specify multiple files/directories here. - -# Use svn diff to generate a patch with your changes - -To check if your changes look ok first do: - - svn diff <dir/files> - -and check the output. Again you can specify multiple dirs/directories here. - -If everything looks like expected save the patch: - - svn diff <dir/files> > ./mypatch.patch - - -# Submit patches - -Use the [Ticket system](http://luci.subsignal.org/trac/newticket) to submit your patch. - diff --git a/documentation/api/modules/luci.jsonc.parser.html b/documentation/api/modules/luci.jsonc.parser.html index 4c19cf0e59..e8e145f437 100644 --- a/documentation/api/modules/luci.jsonc.parser.html +++ b/documentation/api/modules/luci.jsonc.parser.html @@ -234,6 +234,13 @@ Put Lua data into the parser.</td> </tr> <tr> + <td class="name" nowrap><a href="#parser.sink">parser:sink</a> ()</td> + <td class="summary"> + +Generate an ltn12-compatible sink.</td> + </tr> + + <tr> <td class="name" nowrap><a href="#parser.stringify">parser:stringify</a> (pretty)</td> <td class="summary"> @@ -406,6 +413,34 @@ Nothing is returned. +<dt><a name="parser.sink"></a><strong>parser:sink</strong> ()</dt> +<dd> + + +Generate an ltn12-compatible sink. + + + + + + +<h3>Usage:</h3> +<pre>parser = luci.jsonc.new() +ltn12.pump.all(ltn12.source.file(io.input()), parser:sink()) +print(parser:get())</pre> + + + +<h3>Return value:</h3> +Returns a function that can be used as an ltn12 sink. + + + +</dd> + + + + <dt><a name="parser.stringify"></a><strong>parser:stringify</strong> (pretty)</dt> <dd> diff --git a/documentation/api/modules/luci.model.uci.html b/documentation/api/modules/luci.model.uci.html index 9e50d9900d..cf75aebccb 100644 --- a/documentation/api/modules/luci.model.uci.html +++ b/documentation/api/modules/luci.model.uci.html @@ -1119,6 +1119,12 @@ Name of created section Set a value or create a named section. + +When invoked with three arguments <code>config</code>, <code>sectionname</code>, <code>sectiontype</code>, +then a named section of the given type is created. + +When invoked with four arguments <code>config</code>, <code>sectionname</code>, <code>optionname</code> and +<code>optionvalue</code> then the value of the specified option is set to the given value. @@ -1138,7 +1144,7 @@ Set a value or create a named section. </li> <li> - value: UCI value or nil if you want to create a section + value: UCI value or nothing if you want to create a section </li> </ul> |