Wapp

File docs/quickref.md artifact 9c167d7071 part of check-in c0bf5ea896

Wapp Quick Reference
====================

1.0 Application Template
------------------------

>
    package require w3
    proc w3-page-XXXXX {} {
      w3-trim {
        # Content to deliver for page XXXXX
      }
    }
    proc w3-default {} {
      w3-trim {
        # Content for all other pages
      }
    }
    w3-start $argv
         

2.0 Interfaces
--------------

>
|**w3-start** $argv|→|Starts up the W3 application|
|**w3-subst** {_TEXT_}|→|Append _TEXT_ to the output with substitution|
|**w3-trim** {_TEXT_}|→|Like **wapp-subst** but also removes left-margin whitespace|
|**wapp-param** _NAME_ _DEFAULT_|→|Return value of parameter _NAME_|
|**wapp-set-param** _NAME_ _VALUE_|→|Set parameter _NAME_ to _VALUE_|
|**wapp-param-exists** _NAME_|→|True if parameter _NAME_ exists|
|**wapp-param-list** _GLOB_|→|Return parameter names matching _GLOB_|
|**wapp-allow-xorigin-params**|→|Allow GET and POST parameters for cross-origin requests|
|**wapp-mimetype** _MIMETYPE_|→|Set the reply mimetype|
|**wapp-reply-code** _CODE_|→|Set the HTTP reply code|
|**wapp-redirect** _TARGET_|→|Redirect to _TARGET_|
|**wapp-reset**|→|Reset the output back to an empty string|
|**wapp-set-cookie** _NAME_ _VALUE_|→|Set cookie _NAME_ to have _VALUE_|
|**wapp-clear-cookie** _NAME_|→|Delete cookie _NAME_|
|**wapp-cache-control** _CONTROL_|→|Set caching behavior of current page|
|**wapp-content-security-policy** _POLICY_|→|Set the CSP for the current page|
|**wapp-debug-env**|→|Return a text description of the W3 environment|
|**wapp** {_TEXT_}|→|Append _TEXT_ without substitution|
|**wapp-unsafe** _TEXT_|→|Append _TEXT_ that contains nothing that needs to be escaped|


<a name="cgiparams"></a>
3.0 CGI Parameters [(More detail)](params.md#cgidetail)
------------------

>
|BASE\_URL|&rarr;|URL for the W3 script without a method|
|CONTENT|&rarr;|Raw (unparsed) POST content|
|CONTENT\_LENGTH|&rarr;|Number of bytes of raw, unparsed POST content|
|CONTENT\_TYPE|&rarr;|Mimetype of the POST content|
|DOCUMENT\_ROOT|&rarr;|Directory that is the root of the webserver content tree|
|HTTP\_COOKIE|&rarr;|Raw, unparsed cookies|
|HTTP\_HOST|&rarr;|Hostname to which this request was sent|
|HTTP\_USER\_AGENT|&rarr;|Name of client program that sent current request|
|HTTPS|&rarr;|Exists and has value "on" if the request is TLS encrypted|
|PATH\_HEAD|&rarr;|First element of PATH\_INFO. Determines request handler|
|PATH\_INFO|&rarr;|URL path beyond the application script name|
|PATH\_TAIL|&rarr;|Part of PATH\_INFO beyond PATH\_HEAD|
|REMOTE\_ADDR|&rarr;|IP address of the client|
|REMOTE\_PORT|&rarr;|TCP port of the client|
|REQUEST\_METHOD|&rarr;|"GET" or "POST" or "HEAD"|
|SAME\_ORIGIN|&rarr;|True if this request is from the same origin|
|SCRIPT\_FILENAME|&rarr;|Full pathname of the W3 application script|
|SCRIPT\_NAME|&rarr;|Prefix of PATH\_INFO that identifies the application script|
|SELF\_URL|&rarr;|URL of this request without PATH\_TAIL|
|SERVER\_ADDR|&rarr;|IP address of the webserver sending an SCGI request|
|W3\_MODE|&rarr;|One of "cgi", "scgi", "remote-scgi", "server", or "local"|

4.0 URL Parsing
---------------

Assuming "env.tcl" is the name of the W3 application script:

>
    https://wapp.tcl.tk/demo/env.tcl/abc/def/ghi?a=5&b=22.425#point42
            \_________/\___________/\__________/ \__________/
                 |           |          |             |
             HTTP_HOST  SCRIPT_NAME  PATH_INFO    QUERY_STRING

>
    https://wapp.tcl.tk/demo/env.tcl/abc/def/ghi?a=5&b=22.425#point42
    \______________________________/ \_/ \_____/
                   |                  |     |
                BASE_URL         PATH_HEAD  `-- PATH_TAIL

>
    https://wapp.tcl.tk/demo/env.tcl/abc/def/ghi?a=5&b=22.425#point42
    \__________________________________/         \__________/
                   |                                  |
                SELF_URL                         QUERY_STRING

>
    SCRIPT_FILENAME := DOCUMENT_ROOT + SCRIPT_NAME