Wapp really just a collection of TCL procs. All procs are in a single file named "wapp.tcl".
The procs that form the public interface for Wapp begin with "wapp-". The implementation uses various private procedures that have names beginning with "wappInt-". Applications should use the public interface only.
The most important Wapp interfaces are:
- wapp-subst and wapp-trim
Understand the four interfaces above, and you will have a good understanding of Wapp. The other interfaces are merely details.
The following is a complete list of the public interface procs in Wapp:
Start up the application. ARGLIST is typically the value of $::argv, though it might be some subset of $::argv if the containing application has already processed some command-line parameters for itself. By default, this proc never returns, and so it should be very last command in the application script. To embed Wapp in a larger application, include the -nowait option in ARGLIST and this proc will return immediately after setting up all necessary file events.
Caution #1: When using Tcl 8.6 or earlier, command substitution, but not variable substitution, occurs outside of the quoted regions. This problem is fixed using the new "-command" option to the regsub command in Tcl 8.7. Nevertheless, it is suggested that you avoid using the "[" character outside of the %-quotes. Use "[" instead.
Caution #2: The %html() and similar %-substitutions are parsed using a regexp, which means that they cannot do matching parentheses. The %-substitution is terminated by the first close parenthesis, not the first matching close-parenthesis.
Just like wapp-subst, this routine appends TEXT to the web page under construction, using the %html, %url, %qp, %string, and %unsafe substitutions. The difference is that this routine also removes surplus whitespace from the left margin, so that if the TEXT argument is indented in the source script, it will appear at the left margin in the generated output.
wapp-param NAME DEFAULT
Return the value of the Wapp parameter NAME, or return DEFAULT if there is no such query parameter or environment variable. If DEFAULT is omitted, then it is an empty string.
wapp-set-param NAME VALUE
Change the value of parameter NAME to VALUE. If NAME does not currently exist, it is created.
Return true if and only if a parameter called NAME exists for the current request.
Return a TCL list containing the names of all parameters for the current request. Note that there are several parameters that Wapp uses internally. Those internal-use parameters all have names that begin with ".".
Query parameters and POST parameters are usually only parsed and added to the set of parameters available to "wapp-param" for same-origin requests. This restriction helps prevent cross-site request forgery (CSRF) attacks. Query-only web pages for which it is safe to accept cross-site query parameters can invoke this routine to cause query parameters to be decoded.
Set the MIME-type for the generated web page. The default is "text/html".
Set the reply-code for the HTTP request. The default is "200 Ok".
Cause an HTTP redirect to TARGET-URL.
Reset the web page under construction back to an empty string.
wapp-set-cookie NAME VALUE
Cause the cookie NAME to be set to VALUE.
Erase the cookie NAME.
Examine all TCL procedures in the application and return a text string containing warnings about unsafe usage of Wapp commands. This command is run automatically if the "wapp-start" command is invoked with a --lint option.
The CONTROL argument should be one of "no-cache", "max-age=N", or "private,max-age=N", where N is an integer number of seconds.
Add TEXT to the web page output currently under construction. TEXT must not contain any TCL variable or command substitutions. This command is rarely used.
Add TEXT to the web page under construction even though TEXT does contain TCL variable and command substitutions. The application developer must ensure that the variable and command substitutions does not allow XSS attacks. Avoid using this command. The use of "wapp-subst" is preferred in most situations.