[luci] Starting into creating new webpages and modules, at the foot of the learning curve..

[Jo-Philipp Wich]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi Paul.

First of all, sorry for the late reply, I'm pretty busy atm.

> Thanks for your prompt reply on the dev. environment issue -  I have now
> moved onto actually running openWRT with LuCi on a target, a Danube
> reference design board.

No problem. A good starting point for learning Lua is the Lua Users Directory:
http://lua-users.org/wiki/LuaDirectory

And of course the reference manual:
http://www.lua.org/manual/5.1/

> I think this is a very exciting project, and  I should wish you
> guys Happy Anniversary, as it was only March last year that LuCi was
> founded, correct?

Thank you. Yes, the first anniversary is coming, at least the initial
checkins were nearly a year ago :)

> I even had a go at adding my own theme - and was successful in doing so, but
> fell into the same trap I think a couple of people did before; I was
> confused about where to put the theme folder - ended up adding it manually
> to the /build_dir/../luci..  although I had updated the Makefile in the
> ./feeds/ folder.  I did afterwards catch on after reading the forum mail
> from August that I should have used the ../feeds/ folder, but I was being
> expediant and not patient enough!

Yes - others already pointed out that the documentation is a bit abstract in certain ways
and that some stuff could be outlined in a better way and more explicitly.

> I am now looking at adding my own webpages, but have a bit of a learning
> curve to travel as I do not know LUA and am not familiar with the UCI. I
> have started reading into the HowTos and reviewing the existing code but was
> wondering if yourself or others could give me the basic logical steps to
> summarise the best approach to develope the following - just looking for a
> simple 'step1..step2..', not a rewrite of existing howTo's, to get me
> started - what I want to do is :
> 
> 
>    - have a new node appear in the navigation menu bar 'Network..System...'

Menu entries are defined in the controllers, which can be found in
/usr/lib/lua/luci/controller/ on the target system. Usually a menu entry is defined within
the index() function by using entry() - e.g. the following statement:

  entry({"admin", "stuff"}, cbi("my_model"), "My Stuff", 30)

... would create a new top-level menu point labeled "My Stuff" with a sort index of 30.
Notice that "admin" is the root level of the administration ui, "mini" would be the root
level node of the essentials mode. For example the "system.lua" controller defines the
whole "System" menu (0).

>    - the drop down will link to my webpage

This is controlled by the second argument (the action) of entry(). In the example above we
tell the dispatcher to link the "My Stuff" menu point to a cbi model "my_model" which is
expected in /usr/lib/lua/luci/model/cbi/my_model.lua . Other possible actions are "call()"
to invoke a function, "form()" to render a special form or "template()" to render a template.

>    - the webpage will have a <form> with a table of 10 rows

We need to clarify the meaning of "table" here. Do you mean a data table or a form with
ten different fields?

There are multiple possible ways to achieve that, you could use a template and write
custom html code there (1) or use a cbi model which renders the table, either uci-driven
(2) or by manually feeding it with data (3).

>    - each row has a number of different input elements

For tables this is not possible with the cbi model approach since tables in cbi are just
repetitions of uci sections. Assuming you mean a form, then it's as easy as declaring a
map and assign options to it (4).

>    - maintain the link for the internationalstions feature

I18n on options can happen either explicit or implicit. The explicit variant is to assign
the texts yourself, like this:

m = Map("configfile", translate("title_of_form", "Fallback Title"),
    translate("description_of_form", "Fallback Description"))

If you omit the texts entirely, the cbi will try to resolve the appropriate strings by
itself. For the above example it would look for "configfile" as title and
"configfile_desc" as description key in the i18n strings pool.

> At this stage the application behind the webpage will not have a UCI API -
> so am I correct in saying that I can start with a basic HTML webpage,
> calling into a LUA module Interface and then need to rewrite this if I want
> to go with UCI calls?

Yes. There are some examples of non-uci pages in the source. (5) (6)
Basically you could define an entry like:

  entry({"admin", "my_stuff"}, template("my_template"), "My Application", 30)

... which would attempt to render /usr/lib/lua/luci/view/my_template.htm .
The template is preprocessed before it's sent to the browser, so you can embed Lua code
blocks which have access to the whole LuCI api (7), it's like programming php then.


HTH,
JoW

(0)http://luci.subsignal.org/trac/browser/luci/trunk/modules/admin-full/luasrc/controller/admin/system.lua
(1)http://luci.subsignal.org/trac/browser/luci/trunk/modules/admin-full/luasrc/view/admin_status/iptables.htm
(2)http://luci.subsignal.org/trac/browser/luci/trunk/modules/admin-full/luasrc/model/cbi/admin_network/hosts.lua
(3)http://luci.subsignal.org/trac/browser/luci/trunk/modules/admin-full/luasrc/model/cbi/admin_system/processes.lua
(4)http://luci.subsignal.org/trac/browser/luci/trunk/modules/admin-full/luasrc/model/cbi/admin_network/wifi.lua
(5)http://luci.subsignal.org/trac/browser/luci/trunk/applications/luci-statistics/luasrc/view/admin_statistics/networkplugins.htm
(6)http://luci.subsignal.org/trac/browser/luci/trunk/applications/luci-livestats/luasrc/view/livestats/loadavg.htm
(7)http://dev.luci.freifunk-halle.net/luci-doc/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkm33ogACgkQdputYINPTPMOywCcCf8KDyb4t101jUNbr2qpyHi2
NbUAoKR4E/JyVwvHlicDH/EEAu8NF9Xu
=7n3o
-----END PGP SIGNATURE-----