Programmer's Guide to awx
From X-Wrt
The awx functionality and this guide are deprecated!
The X-Wrt's web interface is called Webif^2. Webif^2 and is based on Openwrt's web administration tool, Webif, which was standard in Whiterussian.
Webif is not in the standard installation of Kamikaze at time of writing, and Webif^2 has also come a long way since it's birth.
Webif^2 can be installed via ipkg if one is using a "standard" Kamikaze.
Using the Busy Box http server, it is possible to write awx cgi scripts to create user friendly web based solutions for OpenWrt.
'awx' extends awk by a few common functions that make writing web pages easier, so even the developers can be happy.
Creating a web development framework, awx is designed for small embedded systems and tries to cut down on the amount of redundant code that is typically written for embedded web interfaces. To make web pages more readable, it encourages separating the html code from the web logic, config interaction, etc and encouraging the use of function libraries so code can be reused and bugs can be more quickly found.
awx is now the preferred method contra haserl/webif-page/ash, used now and in earlier Webif^2 releases, for creating web content for OpenWrt. Both the shell and the awx methods will coexist. The awx is still developed and it may not provide the necessary framework or speed enhancements for every task. The developer will select which method will be more suitable for his/her particular task.
You can provide us with the feedback via forum thread: http://forum.x-wrt.org/index.php/topic,492.0.html.
For information concerning improvements in awx, see http://wiki.x-wrt.org/index.php/Talk:Programmer%27s_Guide_to_awx
Contents |
[edit] In the beginning ...
You have a "clean" Kamikaze and make the user friendly decision to install Webif^2: ipkg install webif
- Installing webif ...
- Installing haserl ...
- Reinit httpd ...
OK, you probably didn't know you already had a httpd server in Kamikaze, but you did/do.
What you didn't have was an index.html in the /www folder, now you have!
And what does it do?
- Redirecting to <a href="cgi-bin/webif/info.awx">main page</a></p>
Finally, we find out that awx is used as a cgi program.
So the following information tries to look at awx from a beginners point of view (mine) and with some nice input (yours).
[edit] What is an awx page?
Take a quick look at the info.awx you have on your system, we just clip it a bit here:
#!/usr/bin/awx
BEGIN {
CATEGORY="Info"
include("/usr/lib/webif/common.awx")
getline < "/www/.version"
rev=$0
}
# some nice functions and code
# - but with html codes that mean I can't just cut and paste so I'll have to get back to this
##WEBIF:name:Info:001:System
##WEBIF:name:Info:950:About:aboutinfo
The first line introduces the binary program /usr/bin/awx - awx is linked: /usr/bin/awx -> ../../bin/busybox
For the interested, a link to the code of awx: https://dev.openwrt.org/browser/trunk/package/busybox/patches/920-awx.patch (as you can see, it is a patch of busybox).
The file closes with a cryptic ##WEBIF: which is used as housekeeping for the menu structure of Webif. /www/cgi-bin/.categories contains the order of categories. These should have been coded out but have remained due to lack of time - so will probably change at some point
##WEBIF:category:Info ##WEBIF:category:Graphs ##WEBIF:category:Status ##WEBIF:category:Log ##WEBIF:category:- ##WEBIF:category:System ##WEBIF:category:Network ##WEBIF:category:VPN ##WEBIF:category:- ##WEBIF:category:Logout
By the way, when you were looking at the info.awk, did you look at the other files in /www/cgi-bin/webif?
- you may have noticed that there are only a few awx files, the others are good old webif-page files (There is another programmers guide for them).
But lets leave info.awx, it's big even though it's one of the smaller awx files, and go quickly on to the next section with a smaller program ...
[edit] Example: Hello world!
Here, we take a quick look an example by the author of awx.
Let's see how awx can:
".. make web pages more readable, it encourages separating the html code from the web logic, config interaction, etc "
Lets start with something we can recognise, html code, in this file we will call: views/layout.ahtml:
<html> <head><title><% TITLE %></title></head> <body> <h1><% TITLE %></h1> <p> <% render(RENDER) %> </p> </body> </html>
The only things to notice are of course the TITLE and render(RENDER)
These new elements can be found again in helloworld.awx, which would be found in the /www directory.
BEGIN {
TITLE="A simple test page"
RENDER="views/helloworld.ahtml"
}
function handle_default() {
# do not display any message in the default handler
}
function handle_time() {
"date" | getline
message="Current Date/Time: " $0
}
function handle_version() {
getline < "/proc/version"
message = "Kernel version: " $0
}
There are clearly functional logic in the file, and with no HTML. The TITLE is set in the BEGIN area, so all we have to do now is look at the file RENDER referances: views/helloworld.ahtml
<h2>Hello world!</h2> <a href="<% ENVIRON["SCRIPT_NAME"] %>?action=time">Show Date/Time</a> | <a href="<% ENVIRON["SCRIPT_NAME"] %>?action=version">Show Kernel version</a><br /> <br /> <% message %>
So, views/helloworld.ahtml gives a bit of an overview, because we can read HTML. We can see that it is the main meat of the page, with use for two interactions tieing up with helloworld.awk logic in a views/layout.ahtml envelope.
".. make web pages more readable, it encourages separating the html code from the web logic, config interaction, etc "
[edit] Original awx documentation
Let us now finish by reading the original awx documentation
As you can see in this example, awx makes a few assumptions of how your web pages are structured.
This allows you to skip some code that you would otherwise have to write (e.g. include a header,
include a footer, if/else chain to check a cgi variable for which action should be run).
Typically you will want to use a common layout for almost all pages, so awx uses 'views/layout.ahtml'
as the default for that. You can override this by changing the LAYOUT variable either from the
BEGIN{} section or the handler itself.
Pages are processed in the following order:
1. BEGIN{}
- will be run for all 'actions' of the script. can set up common defaults like page title, layout, etc.
2. The action handler
- awx will check the contents of the ACTION variable, which can be set in the BEGIN{} section. If this
variable is unset, it will use the contents of the cgi parameter 'action' or (if that one is empty as
well) simply fall back to 'default'
- when calling the action, it gets a prefix of 'handle_', so that you can't call arbitrary awk functions
by overriding the CGI parameter
3. The page view
- The page view typically contains the HTML formatting of the page. It can be selected using the RENDER
variable.
CGI parameters will be processed at the first attempt of reading a variable, either explicitly from BEGIN{}
or implicitly when looking for the page action to call
awx extends awk by a few common functions that make writing web pages easier:
- include(file): includes an awk file and executes its BEGIN{} section
- must not contain any line handlers for input files
- render(file): show a file and substitute all <% %> parts
- typically done implicitly for LAYOUT and RENDER, but can be used explicitly as well
- getvar(name): get the contents of a CGI variable
---------------
i have @if with @else and @for fully working
so you can do
<% @for i in items %> Item <% i %>: <% items[i] %>
<% @end %>
it even handles translations like @TR<<<% foo %>>>
rewritten template parser for awx - uses @for, @if, @else, @end for basic flow control
[edit] Diverse
Well, start reading your awk up ... http://www.gnu.org/manual/gawk/html_node/index.html
However, BusyBox awk could be a slimmed down version of gawk: investigating
