CBI

Jo-Philipp Wich edited this page Jan 15, 2016 · 1 revision

Table of Contents

Writing LuCI CBI models

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.

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)

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, ...)

Creates a new 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 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

.addremove = false

Allows the user to remove and recreate the configuration section

.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, ...)

Creates a new option

  • optionclass: a class object of the section
  • additional parameters passed to the constructor of the option class

class TypedSection (type, title, description)

An object describing a group of UCI sections selected by their type. Use 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

Marks this section as dynamic. Dynamic sections can contain an undefinded number of completely userdefined options.

.optional = true

Parse optional options

.anonymous = false

Do not show 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. Use NamedSection:option(Value, ''option'', ''title'', ''description'') or 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

The default value

.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)

Convert this text field into a combobox if possible and add a selection option.

: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 NamedSection:option(Value, ''option'', ''title'', ''description'') or 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

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.
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 NamedSection:option(Value, ''option'', ''title'', ''description'') or 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

The default value

.disabled = 0

the value that shoudl be set if the checkbox is unchecked

.enabled = 1

the value that should be set if the checkbox is checked

.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

: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 MultiValue (option, title, description)

An object describing an option in a section of a UCI File. Creates several checkboxed as form fields. Use NamedSection:option(Value, ''option'', ''title'', ''description'') or 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

The default value

.delimiter = " "

The string which will be used to delimit the values

.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 = "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 DummyValue (option, title, description)

An object describing an option in a section of a UCI File. Creates a readonly field in the form. Use NamedSection:option(Value, ''option'', ''title'', ''description'') or 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.
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)

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.