LuCI-0.10.md

   1 # New in LuCI 0.10
   2
   3 See [online wiki](https://github.com/openwrt/luci/wiki/LuCI-0.10) for latest version.
   4
   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.
   7
   8 ## I18N Changes
   9
  10 ### API
  11
  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.
  15
  16 Code that uses `translate()` or `i18n()` must be changed as follows:
  17
  18 ```lua
  19 -- old style:
  20 translate("some_text", "Some Text")
  21 translatef("some_format_text", "Some formatted Text: %d", 123)
  22
  23 -- new style:
  24 translate("Some Text")
  25 translatef("Some formatted Text: %d", 123)
  26 ```
  27
  28 Likewise for templates:
  29
  30 ```html
  31 <!-- old style: -->
  32 <%:some_text Some Text%>
  33
  34 <!-- new style: -->
  35 <%:Some Text%>
  36 ```
  37
  38 If code must support both LuCI 0.9.x and 0.10.x versions, it is suggested to write the calls as follows:
  39 ```lua
  40 translate("Some Text", "Some Text")
  41 ```
  42
  43 An alternative is wrapping translate() calls into a helper function:
  44 ```lua
  45 function tr(key, alt)
  46     return translate(key) or translate(alt) or alt
  47 end
  48 ```
  49
  50 ... which is used as follows:
  51 ```lua
  52 tr("some_key", "Some Text")
  53 ```
  54
  55 ### Translation File Format
  56
  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).
  59
  60 #### Components built within the LuCI tree
  61
  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.
  65
  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:
  68
  69 ```Makefile
  70 PO = example example-extra
  71
  72 include ../../build/config.mk
  73 include ../../build/module.mk
  74 ```
  75
  76 #### Standalone components
  77
  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:
  81
  82 ```
  83 $ svn co http://svn.luci.subsignal.org/luci/branches/luci-0.10/libs/lmo
  84 $ cd lmo/
  85 $ make
  86 $ ./src/po2lmo translations.po translations.lmo
  87 ```
  88
  89 Note that at the time of writing, the utility program needs Lua headers installed on the system in order to compile properly.
  90
  91 ## CBI
  92
  93 ### Datatypes
  94
  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:
  97
  98 ```lua
  99 opt = section:option(Value, "optname", "Title Text")
 100 opt.datatype = "ip4addr"
 101 ```
 102
 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.
 105
 106 ### Validation
 107
 108 Server-side validator functions can now return custom error messages to provide better feedback on invalid input.
 109
 110 ```lua
 111 opt = section:option(Value, "optname", "Title Text")
 112
 113 function opt.validate(self, value, section)
 114     if input_is_valid(value) then
 115         return value
 116     else
 117         return nil, "The value is invalid because ..."
 118     end
 119 end
 120 ```
 121
 122 ### Tabs
 123
 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()`.
 126
 127 ```lua
 128 sct = map:section(TypedSection, "name", "type", "Title Text")
 129
 130 sct:tab("general", "General Tab Title", "General Tab Description")
 131 sct:tab("advanced", "Advanced Tab Title", "Advanced Tab Description")
 132
 133 opt = sct:taboption("general", Value, "optname", "Title Text")
 134 ```
 135
 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
 140
 141 The `taboption()` function wraps `option()` and assigns the option object to the given tab.
 142 It takes up to five arguments:
 143
 144   * Name of the tab to assign the option to
 145   * Option type, e.g. Value or DynamicList
 146   * Option name
 147   * Title text of the option
 148   * Optional description text of the option
 149
 150 If tabs are used within a particular section, the `option()` function must not be used,
 151 doing so results in undefined behaviour.
 152
 153 ### Hooks
 154
 155 The CBI gained support for `hooks` which can be used to trigger additional actions during the
 156 life-cycle of a map:
 157
 158 ```lua
 159 map = Map("config", "Title Text")
 160
 161 function map.on_commit(self)
 162     -- do something if the UCI configuration got committed
 163 end
 164 ```
 165
 166 The following hooks are defined:
 167
 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)
 176
 177 ### Sortable Tables
 178
 179 TypedSection instances which use the `cbi/tblsection` template may now use a new attribute `sortable` to allow the user to reorder table rows.
 180
 181 ```lua
 182 sct = map:section(TypedSection, "name", "type", "Title Text")
 183 sct.template = "cbi/tblsection"
 184 sct.sortable = true
 185 ```
 186
 187 ## JavaScript
 188
 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.
 191
 192 It should be included like this:
 193
 194 ```html
 195 <script type="text/javascript" src="<%=resource%>/xhr.js"></script>
 196 ```