mirror of
https://git.openwrt.org/project/luci.git
synced 2025-10-31 10:49:03 +08:00
docs: structuring and overhaul
Signed-off-by: Paul Donald <newtwen@gmail.com>
This commit is contained in:
Paul Donald
@ -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`.
|
||||
|
||||
|
||||
@ -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.
|
||||
18
docs/i18n.md
18
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`.
|
||||
|
||||
Reference in New Issue
Block a user