Wapp

     Examine all TCL procedures in the application and report errors about
     unsafe usage of "wapp".

  +  **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-debug-env**  
     This routine returns text that describes all of the Wapp parameters.
     Use it to get a parameter dump for troubleshooting purposes.


The following additional interfaces are envisioned, but are not yet
implemented:

  +  **wapp-send-hex** _HEX_  
     Cause the HTTP reply to be binary that is constructed from the
     hexadecimal text in the _HEX_ argument.  Whitespace in _HEX_ is ignored.

  +  **wapp-escape-url** _TEXT_  
     Add _TEXT_ to the web page under construction after first escaping any
     characters so that the result is safe to include as the value of a
     query parameter on a URL.  This command is equivalent to
     "wapp-subst {%url(_TEXT_)}".


6.0 Developing Applications Using Wapp
--------------------------------------

You can use whatever development practices you are comformable with.  But
if you want some hints for getting started, consider the following:

  1.  Compile the "wapptclsh" executable.  You do not need a separate
      interpreter to run Wapp.  A standard "tclsh" will work fine.  But
      "wapptclsh" contains the a built-in copy of "wapp.tcl" and it
      has SQLite compiled in.  We find it convenient to use.  The sequel
      will assume you have "wapptclsh" somewhere on your $PATH.

  2.  Seed your application using one of the short scripts shown above,
      or perhaps one of the [examples](/file/examples) in this repository.

  3.  Make a few simple changes to the code.

  4.  Run "wapptclsh yourcode.tcl" to test your changes.

  5.  Goto 3.  Continue until your application is working.

  6.  Move the "yourcode.tcl" file to your server for deployment.

During the loop between steps (3) and (5), there is no web server sitting
in between the application and your browser, which means there is no
translation or interpretation of traffic.  This can help make debugging
easier.  Also, you can add "puts" commands to the application to get
interactive debugging information on your screen while the application
is running.

7.0 Limitations
---------------

Each Wapp process is single-threaded.
The fileevent command is used to allow accepting multiple simultaneous
HTTP requests.  However, as soon as a complete request is received, and
the "wapp-page-NAME" proc runs, all other processing is suspended until 
that proc completes.

The POST data parser for Wapp currently only understands
application/x-www-form-urlencoded content.  Wapp does not (currently)
have a decoder for multipart/form-data content.  A multipart/form-data
decoder might be added in the future.  Or, individual applications can
implement their own multipart/form-data decoder using the raw POST data
held in the CONTENT parameter.

As a defense against
[Cross-Site Request Forgery (CSRF)](https://en.wikipedia.org/wiki/Cross-site_request_forgery)
attacks, Wapp refuses to parse any POST query parameters unless there
is a Referer entry in the header that matches the request URI.  In other
words, Wapp assumes that POST requests originate from itself and any other
POST requests are treated as an attack and ignored.

8.0 Design Rules
----------------

All global procs and variables used by Wapp begin with the four character
prefix "wapp".  Procs and variable intended for internal use begin with
the seven character prefix "wappInt".

# This script is a template used for testing.
#
# After making modifications to this script to test out bits of HTML
# (or not - the script works fine as it is), invoke the script using
#
#   wapptclsh env.tcl
#
# All web pages show the Wapp execution environment, which includes
# CGI-line environment variables, decoded query and POST parameters, and 
# decoded cookies.
#
package require wapp
proc wapp-default {} {

  wapp-trim {
    <h1>Wapp Environment</h1>
    <pre>%html([wapp-debug-env])</pre>
  }





}
wapp-start $argv

# This script demonstrates how to send form data from the client browser
# back up to the server using an XMLHttpRequest with JSON content.
#
package require wapp
proc wapp-default {} {
  wapp-trim {
    <h1>Example Of Sending Form Data As JSON Using AJAX</h1>
    <form id="nameForm">
    <table border="0">

# This script demonstrates how to send form data from the client browser
# back up to the server using an XMLHttpRequest with 
# application/x-www-form-urlencoded content.
#
package require wapp
proc wapp-default {} {
  wapp-trim {
    <h1>Example Of Sending application/x-www-form-urlencoded Using AJAX</h1>
    <form id="nameForm">
    <table border="0">

      xhttp.send(jx);
      return false
    }
    </script>
  }
}
proc wapp-page-acceptjson {} {

  puts "Accept Callback"
  puts "mimetype: [list [wapp-param CONTENT_TYPE]]"
  puts "content: [list [wapp-param CONTENT]]"
  foreach var [lsort [wapp-param-list]] {
    if {![regexp {^[a-z]} $var]} continue
    puts "$var = [list [wapp-param $var]]"
  }
}
wapp-start $argv

# This script demonstrates how to receive bulk HTML content
# (such as a complete <table>) and insert it in the middle
# of the DOM using XMLHttpRequest
#
package require wapp
proc wapp-default {} {
  wapp-trim {
    <html>
    <body>