diff options
| -rw-r--r-- | docs/ModulesHowTo.md | 30 | ||||
| -rw-r--r-- | docs/README.md | 20 | ||||
| -rw-r--r-- | docs/i18n.md | 18 |
3 files changed, 39 insertions, 29 deletions
diff --git a/docs/ModulesHowTo.md b/docs/ModulesHowTo.md index ce9b8e5550..75b7e75307 100644 --- a/docs/ModulesHowTo.md +++ b/docs/ModulesHowTo.md @@ -1,4 +1,4 @@ -# HowTo: Write Modules +# HowTo: Write Lua based Modules (deprecated for client side modules) See [online wiki](https://github.com/openwrt/luci/wiki/ModulesHowTo) for latest version. @@ -7,34 +7,34 @@ See [online wiki](https://github.com/openwrt/luci/wiki/ModulesHowTo) for latest This tutorial describes how to write your own modules for the LuCI WebUI. For this tutorial we refer to your LuCI installation directory as `lucidir` (`/usr/lib/lua/luci` on your OpenWRT device) and assume your LuCI installation is reachable through your webserver via `http://192.168.1.1/cgi-bin/luci`. -The recommended way to set up development environment: +The recommended way to set up a development environment: -Install OpenWRT on your router/device (You could use a QEMU or VirtualBox image instead) +- Install OpenWRT on your router/device (You could use a QEMU or VirtualBox image instead) -Install SSHFS on your host +- Install SSHFS on your host -Mount your routers' root (/) someplace on your development host (eg. /mnt/router) +- Mount your routers' root (`/`) someplace on your development host (eg. `/mnt/router`) -Then open /mnt/router/(lucidir) in your favorite development studio +- Then open `/mnt/router/(lucidir)` in your favorite development studio -Extra: Add configurations to your dev studio which will delete the luci cache (detailed below) and then open a browser window to your routers' configuration page in order to see your module/application. +Extra: +- Add configurations to your dev studio which will delete the luci cache (detailed below) and then open a browser window to your routers' configuration page in order to see your module/application. When testing, if you have edited index files, be sure to remove the folder `/tmp/luci-modulecache/*` and the file(s) `/tmp/luci-indexcache*`, then refresh the LUCI page to see your edits. -## Show me the way (The dispatching process) -To write a module you need to understand the basics of the dispatching process in LuCI. -LuCI uses a dispatching tree that will be built by executing the index-Function of every available controller. +## The dispatching process +LuCI uses a dispatching tree that is built by executing the index-Function of every available controller. The CGI-environment variable `PATH_INFO` will be used as the path in this dispatching tree, e.g.: `/cgi-bin/luci/foo/bar/baz` -will be resolved to `foo.bar.baz` +resolves to `foo.bar.baz`. -To register a function in the dispatching tree, you can use the `entry`-function of `luci.dispatcher`. It takes 4 arguments (2 are optional): +To register a function in the dispatching tree, use the `entry`-function of `luci.dispatcher`. It takes 4 arguments (2 are optional): ```lua entry(path, target, title=nil, order=nil) ``` * `path` is a table that describes the position in the dispatching tree: For example a path of `{"foo", "bar", "baz"}` would insert your node in `foo.bar.baz`. -* `target` describes the action that will be taken when a user requests the node. There are several predefined ones of which the 3 most important (call, template, cbi) are described later on this page +* `target` describes the action that will be taken when a user requests the node. There are several predefined actions, of which the 3 most important (call, template, cbi) are described later on this page * `title` defines the title that will be visible to the user in the menu (optional) * `order` is a number with which nodes on the same level will be sorted in the menu (optional) @@ -46,8 +46,8 @@ You can assign more attributes by manipulating the node table returned by the en * `sysauth` requires the user to authenticate with a given system user account -# It's all about names (Naming and the module file) -Now that you know the basics about dispatching, we can start writing modules. Now, choose the category and name of your new digital child. +# Naming and the module file +Now we can start writing modules. Choose the category and name of your new digital child. Let's assume you want to create a new application `myapp` with a module `mymodule`. diff --git a/docs/README.md b/docs/README.md index c64cf9405e..eeb5d0ead4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,5 +4,21 @@ See Wiki [LuCI Technical Reference](https://openwrt.org/docs/techref/luci) ## API Reference - - [Client side JavaScript APIs](jsapi/) - - [Server side Lua APIs](api/index.html) +- [Client side JavaScript APIs](jsapi/) +- [How to i18n your module](i18n): internationalization via \*.po and \*.pot files +- [How to make LuCI JS Modules](https://github.com/openwrt/luci/tree/master/applications/luci-app-example): see the luci-app-example in the repo +- [How to use the JSON-RPC](JsonRpcHowTo) +- [How to make themes](ThemesHowTo) +- [LuCI Modules Reference](Modules): can be JS based or Lua (deprecated) + +## Deprecated API Reference (older Lua based APIs) + +- [CBI models reference](CBI):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 +- [How to make LuCI Lua Modules](ModulesHowTo): No new Lua modules for client side display are accepted, but some server side things are still done in Lua +- [LMO - Lua Machine Objects](LMO): to pack language strings into a more efficient form for Lua +- [Server side Lua APIs](api/index.html) +- [Templates](Templates): template processor which parses HTML-files to Lua functions and allows to store precompiled template files + +## Archived + +- [LuCI-0.10](LuCI-0.10): No longer used, but useful reference if you encounter older LuCI versions.
\ No newline at end of file diff --git a/docs/i18n.md b/docs/i18n.md index c91f29e63d..a9ba01314b 100644 --- a/docs/i18n.md +++ b/docs/i18n.md @@ -6,7 +6,7 @@ See [online wiki](https://github.com/openwrt/luci/wiki/i18n) for latest version. ### Translations in JavaScript -Wrap translatable strings with `_()` e.g. `_('string to translate')` and the `i18n-scan.pl` and friends will correctly identify these strings as they do with all the existing translations. +Wrap translatable strings with `_()` e.g. `_('string to translate')` and the `i18n-scan.pl` and friends will correctly identify these strings for translation. If you have multi line strings you can split them with concatenation: ```js @@ -23,25 +23,19 @@ var mystr = _('this string will translate \ a multi line string'); ``` -Usually if you have multiple sentences you may need to use a line break then use the `<br />` HTML tag: -```js -var mystr = _('Port number.<br />' + - 'E.g. 80 for HTTP'); -``` - -To simplify a job for translators it may be better to split into separate keys without the `<br />`: +Usually if you have multiple sentences you may need to use a line break. Use the `<br />` HTML tag like so: ```js var mystr = _('Port number.') + '<br />' + _('E.g. 80 for HTTP'); ``` -Please use `<br />` and **not** `<br>` or `<br/>`. +Use `<br />` and **not** `<br>` or `<br/>`. -If you have a link inside a translation then try to move its attributes out of a translation key like: +If you have a link inside a translation, move its attributes out of a translation key: ```js var mystr = _('For further information <a %s>check the wiki</a>') .format('href="https://openwrt.org/docs/" target="_blank" rel="noreferrer"') ``` -This will generate a full link with HTML `For further information <a href="https://openwrt.org/docs/" target="_blank" rel="noreferrer">check the wiki</a>`. The `noreferrer` is important when making a link that is opened in a new tab (`target="_blank"`). +This will generate a full link with HTML `For further information <a href="https://openwrt.org/docs/" target="_blank" rel="noreferrer">check the wiki</a>`. The `noreferrer` is important so that it is opened in a new tab (`target="_blank"`). ### Translations in LuCI lua+html templates Use the `<%: text to translate %>` as documented on [Templates](./Templates.md) @@ -54,7 +48,7 @@ In most controller contexts, this is already available for you, but if necessary ## Translation files Translations are saved in the folder `po/` within each individual LuCI component directory, e.g. `applications/luci-app-acl/po/`. The template is in `po/templates/<package>.pot`. -The actual translation files can be found at `po/[lang]/[package].po`. +The individual language translation files can be found at `po/[lang]/[package].po`. In order to use the commands below you need to have the `gettext` utilities (`msgcat`, `msgfmt`, `msgmerge`) installed on your system. On Debian/Ubuntu, install them with `sudo apt install gettext`. |