Difuse/luci
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

docs: structuring and overhaul

Browse source 
Signed-off-by: Paul Donald <newtwen@gmail.com>
This commit is contained in:
Paul Donald 2024-02-15 18:09:10 +01:00
parent 6644f90e9c
commit 1635bbfad4
3 changed files with 39 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
docs/ModulesHowTo.md
View file

@ -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. 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. 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`. 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. 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) ## 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 is built by executing the index-Function of every available controller.
LuCI uses a dispatching tree that will be 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` 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 ```lua
entry(path, target, title=nil, order=nil) 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`. * `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) * `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) * `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 * `sysauth` requires the user to authenticate with a given system user account
# It's all about names (Naming and the module file) # 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. 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`. Let's assume you want to create a new application `myapp` with a module `mymodule`.

20
docs/README.md
View file

@ -4,5 +4,21 @@ See Wiki [LuCI Technical Reference](https://openwrt.org/docs/techref/luci)
## API Reference ## API Reference
- [Client side JavaScript APIs](jsapi/) - [Client side JavaScript APIs](jsapi/)
- [Server side Lua APIs](api/index.html) - [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
View file

@ -6,7 +6,7 @@ See [online wiki](https://github.com/openwrt/luci/wiki/i18n) for latest version.
### Translations in JavaScript ### 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: If you have multi line strings you can split them with concatenation:
```js ```js
@ -23,25 +23,19 @@ var mystr = _('this string will translate \
a multi line string'); a multi line string');
``` ```
Usually if you have multiple sentences you may need to use a line break then use the `<br />` HTML tag: 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');
```
To simplify a job for translators it may be better to split into separate keys without the `<br />`:
```js ```js
var mystr = _('Port number.') + '<br />' + var mystr = _('Port number.') + '<br />' +
_('E.g. 80 for HTTP'); _('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 ```js
var mystr = _('For further information <a %s>check the wiki</a>') var mystr = _('For further information <a %s>check the wiki</a>')
.format('href="https://openwrt.org/docs/" target="_blank" rel="noreferrer"') .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 ### Translations in LuCI lua+html templates
Use the `<%: text to translate %>` as documented on [Templates](./Templates.md) 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 ## Translation files
Translations are saved in the folder `po/` within each individual LuCI component directory, e.g. `applications/luci-app-acl/po/`. 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 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. 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`. On Debian/Ubuntu, install them with `sudo apt install gettext`.