Note: If you plan to integrate your module into LuCI, you should read the Module Reference before.
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 if you are working with an installed version) and assume your LuCI installation is reachable through your webserver via /cgi-bin/luci.
If you are working with the development environment replace lucidir with /path/to/your/luci/checkout/applications/myapplication/luasrc (this is a default empty module you can use for your experiments) and your LuCI installation can probably be reached via http://localhost:8080/luci/ after you ran make runhttpd.
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 CGI-environment variablePATH_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
To register a function in the dispatching tree, you can use the entry-function of luci.dispatcher. entry takes 4 arguments (2 are optional):
entry(path, target, title=nil, order=nil)
You can assign more attributes by manipulating the node table returned by the entry-function. A few example attributes:
Now that you know the basics about dispatching, we can start writing modules. But before you have to choose the category and name of your new digital child.
We assume you want to create a new application "myapp" with a module "mymodule".
So you have to create a new subdirectory lucidir/controller/myapp with a file mymodule.lua with the following content:
module("luci.controller.myapp.mymodule", package.seeall) function index() end
The first line is required for Lua to correctly identify the module and create its scope. The index-Function will be used to register actions in the dispatching tree.
So it is there and has a name but it has no actions.
We assume you want to reuse your module myapp.mymodule that you begun in the last step.
Reopen lucidir/controller/myapp/mymodule.lua and just add a function to it so that its content looks like this example:
module("luci.controller.myapp.mymodule", package.seeall) function index() entry({"click", "here", "now"}, call("action_tryme"), "Click here", 10).dependent=false end function action_tryme() luci.http.prepare_content("text/plain") luci.http.write("Haha, rebooting now...") luci.sys.reboot() end
And now type /cgi-bin/luci/click/here/now ( http://localhost:8080/luci/click/here/now if you are using the development environment) in your browser.
You see these action functions simple have to be added to a dispatching entry.
As you might or might not know: CGI specification requires you to send a Content-Type header before you can send your content. You will find several shortcuts (like the one used above) as well as redirecting functions in the module luci.http
If you only want to show the user a text or some interesting familiy photos it may be enough to use a HTML-template. These templates can also include some Lua code but be aware that writing whole office suites by only using these templates might be called "dirty" by other developers.
Now let's create a little template lucidir/view/myapp-mymodule/helloworld.htm with the content:
<%+header%><%:Hello World%>
<%+footer%>
and add the following line to the index-Function of your module file.
entry({"my", "new", "template"}, template("myapp-mymodule/helloworld"), "Hello world", 20).dependent=false
Now type /cgi-bin/luci/my/new/template ( http://localhost:8080/luci/my/new/template if you are using the development environment) in your browser.
You may notice those fancy <% %>-Tags, these are markups? used by the LuCI template processor. It is always good to include header and footer at the beginning and end of a template as those create the default design and menu.
The CBI is one of the uber coolest features of LuCI. It creates a formular based user interface and saves its contents to a specific UCI config file. You only have to describe the structure of the configuration file in a CBI model file and Luci does the rest of the work. This includes generating, parsing and validating a XHTML form and reading and writing the UCI file.
So let's be serious at least for this paragraph and create a real pratical example lucidir/model/cbi/myapp-mymodule/netifaces.lua with the following contents:
m = Map("network", "Network") -- We want to edit the uci config file /etc/config/network s = m:section(TypedSection, "interface", "Interfaces") -- Especially the "interface"-sections s.addremove = true -- Allow the user to create and remove the interfaces function s:filter(value) return value ~= "loopback" and value -- Don't touch loopback end s:depends("proto", "static") -- Only show those with "static" s:depends("proto", "dhcp") -- or "dhcp" as protocol and leave PPPoE and PPTP alone p = s:option(ListValue, "proto", "Protocol") -- Creates an element list (select box) p:value("static", "static") -- Key and value pairs p:value("dhcp", "DHCP") p.default = "static" s:option(Value, "ifname", "interface", "the physical interface to be used") -- This will give a simple textbox s:option(Value, "ipaddr", translate("ip", "IP Address")) -- Ja, das ist eine i18n-Funktion ;-) s:option(Value, "netmask", "Netmask"):depends("proto", "static") -- You may remember this "depends" function from above mtu = s:option(Value, "mtu", "MTU") mtu.optional = true -- This one is very optional dns = s:option(Value, "dns", "DNS-Server") dns:depends("proto", "static") dns.optional = true function dns:validate(value) -- Now, that's nifty, eh? return value:match("[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+") -- Returns nil if it doesn't match otherwise returns match end gw = s:option(Value, "gateway", "Gateway") gw:depends("proto", "static") gw.rmempty = true -- Remove entry if it is empty return m -- Returns the map
and of course don't forget to add something like this to your module's index-Function.
entry({"admin", "network", "interfaces"}, cbi("myapp-mymodule/netifaces"), "Network interfaces", 30).dependent=false
There are many more features, see the CBI reference and the modules shipped with LuCI.
The LuCI modules are divided into several category directories, namely:
Each module goes into a subdirectory of any of this category-directories.
The contents of a module directory are as follows:
This is the module's makefile. If the module just contains Lua sourcecode or resources then the following Makefile should suffice.
include ../../build/config.mk include ../../build/module.mk
If you have C(++) code in your module your Makefile should at least contain the following things.
include ../../build/config.mk include ../../build/gccconfig.mk include ../../build/module.mk compile: # Commands to compile and link your C-code # and to install them under the dist/ hierarchy clean: luaclean # Commands to clean your compiled objects
The src directory is reserved for C sourcecode.
luasrc contains all Lua sourcecode files. These will automatically be stripped or compiled depending on the Make target and are installed in the LuCI installation directory.
lua is equivalent to luasrc but containing Lua files will be installed in the Lua document root.
All files under htdocs will be copied to the document root of the target webserver.
All directories and files under root will be copied to the installation target as they are.
dist is reserved for the builder to create a working installation tree that will represent the filesystem on the target machine. DO NOT put any files there as they will get deleted.
ipkg contains IPKG package control files, like preinst, posinst, prerm, postrm. conffiles. See IPKG documentation for details.
If you want to add your module to the LuCI OpenWRT feed you have to add several sections to the contrib/package/luci/Makefile.
For a Web UI applications this is:
A package description:
define Package/luci-app-YOURMODULE $(call Package/luci/webtemplate) DEPENDS+=+some-package +some-other-package TITLE:=SHORT DESCRIPTION OF YOURMODULE endef
A package installation target:
define Package/luci-app-YOURMODULE/install $(call Package/luci/install/template,$(1),applications/YOURMODULE) endef
A module build instruction:
ifneq ($(CONFIG_PACKAGE_luci-app-YOURMODULE),) PKG_SELECTED_MODULES+=applications/YOURMODULE endif
A build package call:
$(eval $(call BuildPackage,luci-app-YOURMODULE))