![]() |
CGILua 5.0 |
Scripts |
This page describes the workings of CGILua scripting. There are two ways to CGILua scripting: using Lua scripts or Lua Pages. Lua scripts provide expression power while Lua Pages provide design independence.
CGILua decodes all information provided by the web client such
as URL parameters, form fields and file uploads. All this information is
available as a Lua table called cgi
.
Lua scripts are text files containing valid sentences in the Lua language. This kind of usage adopts a "traditional" form of programming, where a program is responsible for the entire generation of the resulting page.
To generate a valid web document (HTML, XML, WML, CSS etc) the script must follow an order to produce its output, first sending the correct header and then sending the actual document contents.
CGILua offers some functions to ease these tasks. The most common
is cgilua.htmlheader
that
produce the header for a HTML document (see Headers for a complete list). The
function used to send the document's contents (or part of it) is cgilua.put
.
For example, a HTML document which displays the sentence "Hello World!" can be generated with the following Lua script:
cgilua.htmlheader() cgilua.put([[ <html> <head><title>Hello World</title></head> <body> <b>Hello World!</b> </body> </html> ]])
It should be noted that the above example generates a "fixed" page: even though the page is generated at execution time there is no "variable" information. The very same document could be generated directly with a simple HTML file. However, Lua scripts become especially useful when the document contains information which is not known beforehand, and it is necessary to generate a "dynamic" page.
Another easy example can be shown, this time using a Lua control structure, variables, and the concatenation operator:
cgilua.htmlheader() cgilua.put('<html>') if cgi.language == 'english' then greeting = 'Hello World!' elseif cgi.language == 'portuguese' then greeting = 'Olá Mundo!' else greeting = '[unknown language]' end cgilua.put('<head><title>'..greeting..'</title></head>') cgilua.put('<body>') cgilua.put('<b>'..greeting..'</b>') cgilua.put('</body>') cgilua.put('</html>')
The use of cgi.language
indicates that a
variable named "language" was passed to the script as a CGI
parameter, coming from a HTML form field (via POST) or from the URL used to
activate it (via GET). CGILua automatically decodes such variables.
A Lua Page is a text template file which will be processed by CGILua before the HTTP server sends it to the client. CGILua does not process the text itself but it searches some special markups that include Lua code into the file. After all those markups are processed, the resulting file is sent to the client.
Lua Pages have a default .lp
extension. They are a simpler
way to make a dynamic page because there is no need to send the HTTP header,
usually Lua Pages are HTML pages so CGILua sends the HTML header automatically.
But there are some restrictions on the use of Lua Pages and and sometimes
a Lua Script will have to be used.
The fundamental markups is:
<?lua
Lua chunk
?>
There are also some alternatives accepted:
<?lua= Lua expression ?>
<% Lua chunk %>
<%= Lua expression %>
The example on the previous section could be written using a Lua Page:
<html>
<?lua
if cgi.language == 'english' then
greeting = 'Hello World!'
elseif cgi.language == 'portuguese' then
greeting = 'Olá Mundo!'
else
greeting = '[unknown language]'
end
?>
<head><title><%= greeting %></title></head>
<body>
<b><%= greeting %></b>
</body>
</html>
As on other template languages, it's considered a best practice to not use explicit Lua logic on Lua Pages, the recommended aproach is to use only function calls that returns chunks of the page
cgi
tableCGILua has an unified way of accessing data passed to the script despite the HTTP method used (GET or POST). No matter which method was used on the client, all parameters will be provided inside the cgi table.
Almost all types of parameters will be available as strings. Even if the value of a parameter is a number, it will be converted to its string representation.
There are only two exceptions where the value will be a Lua table. The first case occurs on file uploads, where the table will have the following fields:
The other case that uses Lua tables occurs when
there is more than one value associated with the same parameter
name. This happens in the case of a selection list with multiple values; but it
also occurs when the form (of the referrer) had two or more
elements with the same name
attribute (maybe because one was on a
form and another was in the query string). All values will be inserted
in an indexed table in the order in which they are treated.