diff options
Diffstat (limited to 'documentation/LuCI-0.10.md')
| -rw-r--r-- | documentation/LuCI-0.10.md | 202 |
1 files changed, 202 insertions, 0 deletions
diff --git a/documentation/LuCI-0.10.md b/documentation/LuCI-0.10.md new file mode 100644 index 0000000000..5db9895e58 --- /dev/null +++ b/documentation/LuCI-0.10.md @@ -0,0 +1,202 @@ +[[PageOutline(2-5, Table of Contents, floated)]] + + +This document describes new features and incompatibilities to LuCI 0.9.x. +It is targeted at module authors developing external addons to LuCI. + +# I18N Changes + +## API + +The call conventions for the i18n api changed, there is no dedicated translation +key anymore and the english text is used for lookup instead. This was done to +ease the maintenance of language files. + +Code that uses _translate()'' or ''i18n()_ must be changed as follows: + + + -- old style: + translate("some_text", "Some Text") + translatef("some_format_text", "Some formatted Text: %d", 123) + + -- new style: + translate("Some Text") + translatef("Some formatted Text: %d", 123) + + +Likewise for templates: + + + <!-- old style: --> + <%:some_text Some Text%> + + <!-- new style: --> + <%:Some Text%> + + +If code must support both LuCI 0.9.x and 0.10.x versions, it is suggested to write the calls as follows: + + translate("Some Text", "Some Text") + + +An alternative is wrapping translate() calls into a helper function: + + function tr(key, alt) + return translate(key) or translate(alt) or alt + end + + +... which is used as follows: + + tr("some_key", "Some Text") + + +## Translation File Format + +Translation catalogs are now maintained in *.po format files. During build those get translated +into [*.lmo archives](http://luci.subsignal.org/trac/wiki/Documentation/LMO). + +LuCI ships a [utility script](http://luci.subsignal.org/trac/browser/luci/branches/luci-0.10/build/i18n-lua2po.pl) +in the build/ directory to convert old Lua translation files to the *.po format. The generated *.po files should +be placed in the appropriate subdirectories within the top po/ file in the LuCI source tree. + +### Components built within the LuCI tree + +If components using translations are built along with the LuCI tree, the newly added *.po file are automatically +compiled into *.lmo archives during the build process. In order to bundle the appropriate *.lmo files into the +corresponding *.ipk packages, component Makefiles must include a "PO" variable specifying the files to include. + +Given a module _applications/example/'' which uses ''po/en/example.po'' and ''po/en/example-extra.po_, +the _applications/example/Makefile_ must be changed as follows: + + + PO = example example-extra + + include ../../build/config.mk + include ../../build/module.mk + + +### Standalone components + +Authors who externally package LuCI components must prepare required *.lmo archives themselves. +To convert existing Lua based message catalogs to the *.po format, the build/i18n-lua2po.pl helper script can be used. +In order to convert *.po files into *.lmo files, the standalone "po2lmo" utility must be compiled as follows: + + + $ svn co http://svn.luci.subsignal.org/luci/branches/luci-0.10/libs/lmo + $ cd lmo/ + $ make + $ ./src/po2lmo translations.po translations.lmo + + +Note that at the time of writing, the utility program needs Lua headers installed on the system in order to compile properly. + +# CBI + +## Datatypes + +The server side UVL validation has been dropped to reduce space requirements on the target. +Instead it is possible to define datatypes for CBI widgets now: + + + opt = section:option(Value, "optname", "Title Text") + opt.datatype = "ip4addr" + + +User provided data is validated once on the frontend via JavaScript and on the server side prior to saving it. +A list of possible datatypes can be found in the [luci.cbi.datatypes](http://luci.subsignal.org/trac/browser/luci/branches/luci-0.10/libs/web/luasrc/cbi/datatypes.lua#L26) class. + +## Validation + +Server-sided validator function can now return custom error messages to provide better feedback on invalid input. + + + opt = section:option(Value, "optname", "Title Text") + + function opt.validate(self, value, section) + if input_is_valid(value) then + return value + else + return nil, "The value is invalid because ..." + end + end + + +## Tabs + +It is now possible to break up CBI sections into multiple tabs to better organize longer forms. +The TypedSection and NamedSection classes gained two new functions to define tabs, _tab()'' and ''taboption()_. + + + sct = map:section(TypedSection, "name", "type", "Title Text") + + sct:tab("general", "General Tab Title", "General Tab Description") + sct:tab("advanced", "Advanced Tab Title", "Advanced Tab Description") + + opt = sct:taboption("general", Value, "optname", "Title Text") + ... + + +The _tab()_ function is declares a new tab and takes up to three arguments: + * Internal name of the tab, must be unique within the section + * Title text of the tab + * Optional description text for the tab + +The _taboption()'' function wraps ''option()_ and assigns the option object to the given tab. +It takes up to five arguments: + + * Name of the tab to assign the option to + * Option type, e.g. Value or DynamicList + * Option name + * Title text of the option + * Optional description text of the option + +If tabs are used within a particular section, the _option()_ function must not be used, +doing so results in undefined behaviour. + +## Hooks + +The CBI gained support for _hooks_ which can be used to trigger additional actions during the +life-cycle of a map: + + + map = Map("config", "Title Text") + + function map.on_commit(self) + -- do something if the UCI configuration got committed + end + + +The following hooks are defined: + +|| on_cancel || The user pressed cancel within a multi-step Delegator or a SimpleForm instance || +|| on_init || The CBI is about to render the Map object || +|| on_parse || The CBI is about to read received HTTP form values || +|| on_save, on_before_save || The CBI is about to save modified UCI configuration files || +|| on_after_save || Modified UCI configuration files just got saved +|| on_before_commit || The CBI is about to commit the changes || +|| on_commit, on_after_commit, on_before_apply || Modified configurations got committed and the CBI is about to restart associated services || +|| on_apply, on_after_apply || All changes where completely applied (only works on Map instances with the apply_on_parse attribute set) || + +## Sortable Tables + +TypedSection instances which use the "cbi/tblsection" template may now use a new attribute _sortable_ to allow the user to reorder table rows. + + + sct = map:section(TypedSection, "name", "type", "Title Text") + sct.template = "cbi/tblsection" + sct.sortable = true + + ... + + +# JavaScript + +The LuCI 0.10 branch introduced a new JavaScript file _xhr.js_ which provides support routines for XMLHttpRequest operations. +Each theme must include this file in the <head> area of the document for forms to work correctly. + +It should be included like this: + + + <script type="text/javascript" src="<%=resource%>/xhr.js"></script> +
\ No newline at end of file |