Wapp

Check-in [ced8768917]
Login
☰Home Timeline Forum Tickets Wiki

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Documentation tweaks.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: ced87689174f7473a74b74822e29d5eeaa4f21ca06ecd7137d52cce00d2b548a
User & Date: drh 2019-03-06 22:49:09
Context
2019-03-06
23:12
More documentation tweaks. check-in: 7be9077b84 user: drh tags: trunk
22:49
Documentation tweaks. check-in: ced8768917 user: drh tags: trunk
20:47
Use the -command argument to regexp to provide wapp-subst and wapp-trim that are fast and that avoid doing command substitution outside of quoted regions. check-in: df36e56f70 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to README.md. 

54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78


To run the application as CGI, make the hello.tcl file executable and
move it into the appropriate directory of the web server.

3.0 Further information
-----------------------

  *  [Introduction To Writing Wapp Applications](/doc/trunk/docs/intro.md)

  *  [Quick Reference](/doc/trunk/docs/quickref.md)

  *  [Wapp Parameters](/doc/trunk/docs/params.md)

  *  [Wapp Commands](/doc/trunk/docs/commands.md)

  *  [URL Mapping](/doc/trunk/docs/urlmapping.md)

  *  [Security Features](/doc/trunk/docs/security.md)

  *  [How To Compile wapptclsh - Or Not](/doc/trunk/docs/compiling.md)

  *  [Limitations of Wapp](/doc/trunk/docs/limitations.md)

  *  [Example Applications](/file/examples)

  *  [Real-World Uses Of Wapp](/doc/trunk/docs/usageexamples.md)









<

<

<

<

<

<

<

<

<

>

54
55
56
57
58
59
60

61

62

63

64

65

66

67

68

69
70

To run the application as CGI, make the hello.tcl file executable and
move it into the appropriate directory of the web server.

3.0 Further information
-----------------------

  *  [Introduction To Writing Wapp Applications](/doc/trunk/docs/intro.md)

  *  [Quick Reference](/doc/trunk/docs/quickref.md)

  *  [Wapp Parameters](/doc/trunk/docs/params.md)

  *  [Wapp Commands](/doc/trunk/docs/commands.md)

  *  [URL Mapping](/doc/trunk/docs/urlmapping.md)

  *  [Security Features](/doc/trunk/docs/security.md)

  *  [How To Compile wapptclsh - Or Not](/doc/trunk/docs/compiling.md)

  *  [Limitations of Wapp](/doc/trunk/docs/limitations.md)

  *  [Example Applications](/file/examples)

  *  [Real-World Uses Of Wapp](/doc/trunk/docs/usageexamples.md)
  *  [Debugging Hints](/doc/trunk/docs/debughints.md)

Changes to docs/commands.md. 

24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


42
43
44
45
46





47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
..
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
...
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

119
120
121
122
123
124
125
126

     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.

  +  **wapp-subst** _TEXT_  
     This command appends text to the end of reply to an HTTP request.
     The _TEXT_ argument should be enclosed in {...} to prevent 
     accidental substitutions.
     The "wapp-subst" command itself will do all necessary backslash
     substitutions.  Command and variable substitutions occur within
     "%html(...)", "%url(...)", "%qp(...)", "%string(...)", and
     "%unsafe(...)".  The substitutions are escaped (except in the case of
     "%unsafe(...)") so that the result is safe for inclusion within the
     body of an HTML document, a URL, a query parameter, or a javascript or
     JSON string literal, respectively.  <b>Bug:</b> 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 "\&#91;" instead.






  +  **wapp-trim** _TEXT_  
     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](params.md) _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.
................................................................................

  +  **wapp-param-list** _NAME_  
     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 ".".

  +  **wapp-allow-xorigin-params**  
     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.

................................................................................
     is run automatically if the "wapp-start" command is invoked with a --lint
     option.

  +  **wapp-cache-control** _CONTROL_  
     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.

  +  **wapp-content-security-policy** _POLICY_  
     Set the Content Security Policy (hereafter "CSP") to _POLICY_.  The
     default CSP is _default\_src 'self'_, which is very restrictive.  The
     default CSP disallows (a) loading any resources from other origins,
     (b) the use of eval(), and (c) in-line javascript or CSS of any kind.
     Set _POLICY_ to "off" to completely disable the CSP mechanism.  Or
     specify some other policy suitable for the needs of the application.


  +  **wapp-debug-env**  
     This routine returns text that describes all of the Wapp parameters.
     Use it to get a parameter dump for troubleshooting purposes.

  +  **wapp** _TEXT_  
     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.








|









|
>
>


|


>
>
>
>
>









|







 







|







 







|







>
|








24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
..
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
...
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

     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.

  +  <a name='wapp-subst'></a>**wapp-subst** _TEXT_  
     This command appends text to the end of reply to an HTTP request.
     The _TEXT_ argument should be enclosed in {...} to prevent 
     accidental substitutions.
     The "wapp-subst" command itself will do all necessary backslash
     substitutions.  Command and variable substitutions occur within
     "%html(...)", "%url(...)", "%qp(...)", "%string(...)", and
     "%unsafe(...)".  The substitutions are escaped (except in the case of
     "%unsafe(...)") so that the result is safe for inclusion within the
     body of an HTML document, a URL, a query parameter, or a javascript or
     JSON string literal, respectively. 

> >  <b>Caution #1:</b> 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 "\&#91;" instead.

> >  <b>Caution #2:</b> 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.

  +  **wapp-trim** _TEXT_  
     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.

  +  <a name='wapp-param'></a>**wapp-param** _NAME_ _DEFAULT_  
     Return the value of the [Wapp parameter](params.md) _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.
................................................................................

  +  **wapp-param-list** _NAME_  
     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 ".".

  +  <a name='allow-xorigin'></a>**wapp-allow-xorigin-params**  
     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.

................................................................................
     is run automatically if the "wapp-start" command is invoked with a --lint
     option.

  +  **wapp-cache-control** _CONTROL_  
     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.

  +  <a name='csp'></a>**wapp-content-security-policy** _POLICY_  
     Set the Content Security Policy (hereafter "CSP") to _POLICY_.  The
     default CSP is _default\_src 'self'_, which is very restrictive.  The
     default CSP disallows (a) loading any resources from other origins,
     (b) the use of eval(), and (c) in-line javascript or CSS of any kind.
     Set _POLICY_ to "off" to completely disable the CSP mechanism.  Or
     specify some other policy suitable for the needs of the application.


  +  <a name="debug-env"></a>**wapp-debug-env**  
     This routine returns text that describes all of the Wapp parameters.
     Use it to get a parameter dump for troubleshooting purposes.

  +  **wapp** _TEXT_  
     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.

Added docs/debughints.md. 

























































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

Hints For Debugging Wapp Applications
=====================================

Here are some suggestions for debugging Wapp applications:

  +  If it seems like the [wapp-param](#wapp-param) command is not 
     working correctly, that might be because the same-origin policy
     is preventing query parameters from being parsed.
     Try adding this command to the top of the page generator proc, at
     least temporarily to see if that clears the problem.

  +  If parts of your webpage do not appear to be working, that might
     be due to the restrictive default 
     [Content Security Policy (CSP)](https://en.wikipedia.org/wiki/Content_Security_Policy)
     that Wapp uses.  Try temporarily disabling the CSP using a command
     like <blockquote><b>wapp-content-security-policy off</b></blockquote>
     near the top of your page-generator proc.

  +  Temporarily insert the output of the 
     [wapp-debug-env](commands.md#debug-env) command in your output to see
     what is going on.  Example:
     
> > 
    wapp-trim {
      <h1>Environment</h1>
      <pre>%html([wapp-debug-env])</pre>
    }

This page was generated in about 0.006s by Fossil 2.10 [3e183bfad8] 2019-08-21 19:18:06