sqr is a library which adds functions to Sysquake Remote, such as support for forms.
To have the functions defined in sqr always available, add the following directive to the Apache configuration file:
SQRStartup use sqr;
Alternatively (or in addition), you can have the following statement in a <?sqr...?> block of SQR files which use the library:
use sqr
Obtain and process form data submitted by the browser.
(s, err) = processhtmlform(format, fieldnames, s0)
processhtmlform(format,fieldnames,s0) obtains data submitted by the user with methods GET or POST. For each field recognized, it replaces the corresponding value in structure s0. Then it returns the modified structure as the first output argument. The input arguments are the same as those expected by displayhtmlform.
The optional second output argument is an error string which is empty if no error occurred, or an error message otherwise. It is not considered to be an error when the data submitted by the browser does not match what is expected.
processhtmlform can be called before displayhtmlform in order to display again the data submitted by the user. In this case, the first time the page is processed, processhtmlform leaves the structure s0 unmodified.
Display an HTML form.
(s, err) = displayhtmlform(format, fieldnames, s) (s, err) = displayhtmlform(format, fieldnames, s, method) (s, err) = displayhtmlform(format, fieldnames, s, method, action)
displayhtmlform(format,fieldnames,s) produces the HTML code required to display a form, i.e. a set of text fields and controls which the user can fill or change. The form contents are based on the value of the fields of structure s. The way the form is displayed is based on string format, which has the same role as the format string of fprintf. List s maps each control specified in format to a field of s.
A fourth input argument can specify the method, usually 'POST or 'GET' (the default is 'POST'). If it is the empty string, form tags <form ...> and </form> are not produced by displayhtmlform; they should be output explicitly. This permits to insert other <input> tags which are not supported directly, such as interactive images; or to specify other form attributes.
A fifth input argument can specify the action (the target page). By default, or with an empty string, submitted form data are sent to the same page.
displayhtmlform scans format and display most of its characters unmodified. It recognizes the sequences of characters in the table below, which it replaces with HTML code.
| Sequence | Meaning | Field value |
|---|---|---|
| %{size}n | number (size char. in text field) | real scalar number |
| %c | checkbox | logical scalar value |
| %{size}s | string (size char. in text field) | string |
| %{size}p | password (size char. in password field) | string |
| %{r,c}t | textarea of r rows and c columns | string |
| %f | file | string (output only) |
| %F | filename | string (input only) |
| %{e1,e2,...}m | menu with comma-separated entries | selected entry as an index or a string |
| %h | hidden field | string |
| %{label}R | reset button | (none) |
| %{label,name}S | submit button | true if clicked, false otherwise |
| %{e1,e2,...}r | radio buttons with comma-separated entries | selected button as an index or a string |
| %% | character % | (none) |
| \t | next column (see below) | (none) |
| \n | line break (<br /> in HTML) or next row | (none) |
When the format string contains tabs ('\t'), the form is placed in a table. In the format string, rows are separated with line feeds ('\n') and columns with tabs. This permits the vertical alignment of elements, for instance when text fields follow labels.
A form with different types of inputs and two submit buttons is displayed and processed. Processing is done before display, so that settings which have just been changed are used to set input values accordingly.
use sqr;
format = ['x: %n\n', ...
'str: %50s\n', ...
'b: %c\n', ...
'r: %{alpha,beta,gamma}r\n', ...
'Select: %{one,two,three,four,five}m\n', ...
'%{Revert}R%{Submit #1,submit1}S%{Submit #2,submit2}S'];
names = {'x','s','b','r','m'};
s0 = struct('x',123.456, 's','foo', 'b',true, 'r','alpha', 'm',2);
s = processhtmlform(format, names, s0);
displayhtmlform(format, names, s, 'GET');
A login form with fields for a name and a password, with vertical alignment given by tabs:
format = 'Name:\t%20s\nPassword:\t%20p';
names = {'name', 'pass'};
s0 = struct('name', '', 'pass', '');
displayhtmlform(format, names, s0, 'POST');