3 See [online wiki](https://github.com/openwrt/luci/wiki/LuCI-0.10) for latest version.
5 This document describes new features and incompatibilities to LuCI 0.9.x.
6 It is targeted at module authors developing external addons to LuCI.
12 The call conventions for the i18n api changed, there is no dedicated translation
13 key anymore and the english text is used for lookup instead. This was done to
14 ease the maintenance of language files.
16 Code that uses `translate()` or `i18n()` must be changed as follows:
20 translate("some_text", "Some Text")
21 translatef("some_format_text", "Some formatted Text: %d", 123)
24 translate("Some Text")
25 translatef("Some formatted Text: %d", 123)
28 Likewise for templates:
32 <%:some_text Some Text%>
38 If code must support both LuCI 0.9.x and 0.10.x versions, it is suggested to write the calls as follows:
40 translate("Some Text", "Some Text")
43 An alternative is wrapping translate() calls into a helper function:
46 return translate(key) or translate(alt) or alt
50 ... which is used as follows:
52 tr("some_key", "Some Text")
55 ### Translation File Format
57 Translation catalogs are now maintained in `*.po` format files.
58 During build those get translated into [*.lmo archives](https://github.com/openwrt/luci/wiki/LMO).
60 #### Components built within the LuCI tree
62 If components using translations are built along with the LuCI tree, the newly added *.po file are automatically
63 compiled into *.lmo archives during the build process. In order to bundle the appropriate *.lmo files into the
64 corresponding *.ipk packages, component Makefiles must include a "PO" variable specifying the files to include.
66 Given a module `applications/example/` which uses `po/en/example.po` and `po/en/example-extra.po`,
67 the `applications/example/Makefile` must be changed as follows:
70 PO = example example-extra
72 include ../../build/config.mk
73 include ../../build/module.mk
76 #### Standalone components
78 Authors who externally package LuCI components must prepare required `*.lmo` archives themselves.
79 To convert existing Lua based message catalogs to the `*.po` format, the `build/i18n-lua2po.pl` helper script can be used.
80 In order to convert `*.po` files into `*.lmo` files, the standalone `po2lmo` utility must be compiled as follows:
83 $ svn co http://svn.luci.subsignal.org/luci/branches/luci-0.10/libs/lmo
86 $ ./src/po2lmo translations.po translations.lmo
89 Note that at the time of writing, the utility program needs Lua headers installed on the system in order to compile properly.
95 The server side UVL validation has been dropped to reduce space requirements on the target.
96 Instead it is possible to define datatypes for CBI widgets now:
99 opt = section:option(Value, "optname", "Title Text")
100 opt.datatype = "ip4addr"
103 User provided data is validated once on the frontend via JavaScript and on the server side prior to saving it.
104 A list of possible datatypes can be found in the [luci.cbi.datatypes](https://github.com/openwrt/luci/blob/master/modules/luci-compat/luasrc/cbi/datatypes.lua) class.
108 Server-side validator functions can now return custom error messages to provide better feedback on invalid input.
111 opt = section:option(Value, "optname", "Title Text")
113 function opt.validate(self, value, section)
114 if input_is_valid(value) then
117 return nil, "The value is invalid because ..."
124 It is now possible to break up CBI sections into multiple tabs to better organize longer forms.
125 The TypedSection and NamedSection classes gained two new functions to define tabs, `tab()` and `taboption()`.
128 sct = map:section(TypedSection, "name", "type", "Title Text")
130 sct:tab("general", "General Tab Title", "General Tab Description")
131 sct:tab("advanced", "Advanced Tab Title", "Advanced Tab Description")
133 opt = sct:taboption("general", Value, "optname", "Title Text")
136 The `tab()` function declares a new tab and takes up to three arguments:
137 * Internal name of the tab, must be unique within the section
138 * Title text of the tab
139 * Optional description text for the tab
141 The `taboption()` function wraps `option()` and assigns the option object to the given tab.
142 It takes up to five arguments:
144 * Name of the tab to assign the option to
145 * Option type, e.g. Value or DynamicList
147 * Title text of the option
148 * Optional description text of the option
150 If tabs are used within a particular section, the `option()` function must not be used,
151 doing so results in undefined behaviour.
155 The CBI gained support for `hooks` which can be used to trigger additional actions during the
159 map = Map("config", "Title Text")
161 function map.on_commit(self)
162 -- do something if the UCI configuration got committed
166 The following hooks are defined:
168 * `on_cancel`: The user pressed cancel within a multistep Delegator or a SimpleForm instance
169 * `on_init`: The CBI is about to render the Map object
170 * `on_parse`: The CBI is about to read received HTTP form values
171 * `on_save`, `on_before_save`: The CBI is about to save modified UCI configuration files
172 * `on_after_save`: Modified UCI configuration files just got saved
173 * `on_before_commit`: The CBI is about to commit the changes
174 * `on_commit`, `on_after_commit`, `on_before_apply`: Modified configurations got committed and the CBI is about to restart associated services
175 * `on_apply`, `on_after_apply`: All changes where completely applied (only works on Map instances with the apply_on_parse attribute set)
179 TypedSection instances which use the `cbi/tblsection` template may now use a new attribute `sortable` to allow the user to reorder table rows.
182 sct = map:section(TypedSection, "name", "type", "Title Text")
183 sct.template = "cbi/tblsection"
189 The LuCI 0.10 branch introduced a new JavaScript file `xhr.js` which provides support routines for `XMLHttpRequest` operations.
190 Each theme must include this file in the `<head>` area of the document for forms to work correctly.
192 It should be included like this:
195 <script type="text/javascript" src="<%=resource%>/xhr.js"></script>