CLASS CGI_OBJECT

    ATTRIBUTES:
    
    HDF_DATASET:hdf 

       This is an hdf dataset. See the neo_util module documentation
       for a description of the HDF_DATASET class. 

    METHODS:

    parse()

      This causes the Clearsilver CGI kit to parse standard
      input, including any HTTP post data. If you want to
      be notified of upload progress, you'll want to call 
      setUploadCB() first.

    setUploadCB(OBJ:state_holder,FUNC:event_fn)

      If you call this before calling parse, then Clearsilver
      will call back your event_fn periodically during upload.
      This allows you to get progress information about the
      HTTP upload and stuff it somewhere. This has been used to
      build an HTTP upload progress bar in HTML. The upload CGI 
      itself just squirrils away the progress of the upload, which
      another CGI periodically checks and displays to the user.

      Your function should have the following prototype:

        INT:event_fn(OBJ:state_holder,INT:bytes_read,INT:bytes_expected)

      NOTE: Your function must return "0" to continue the upload, or "-1" 
      to abort the upload.

      state_holder is the same object you handed into the 
      setUploadCB function, and is just for you to be able to
      store state across calls to your callback. The bytes_read 
      and bytes_expected are for the entire upload. If it is 
      a multipart upload of three files, each 1k. Then bytes_expected
      will be 3k, and the bytes_read will progress through
      the entire 3k. The upload callback does not distinguish
      between files.

      The callback is called every successful read off standard in,
      which is dependent on Clearsilver's input buffer size.
      (4k? 8k? 64k? see the source luke)

      Returning a non-zero value will cause the upload to cancel with a
      CGIUploadCancelled exception.  This can be used to limit upload
      sizes, for instance, but I would recommend looking at the
      CGI.ContentLength before the call to parse(), instead. 
      Use of this call back can add significant overhead - on a 50MB
      upload, this call back will be called over 10,000 times.

    error(STRING:error_string)
  
       Causes Clearsilver to return a HTTP status 500 error 
       message to standard out, including the error_string.

    display(STRING:template_name)
       
       Causes Clearsilver to parse and render the CS Template 
       template_name to stdout. This includes sending the
       appropriate HTTP headers. This also does the magic of
       deciding to gzip the output, and sends the appropriate
       encoding headers to tell the client browser about this
       gzip encoding. If you want to set any cookies, be sure
       to call the cookie calls before you call display.
       

    redirect(STRING:path_url)

       This takes a simple path url. For example "/mypage.py",
       and builds the full "http://hostname/mypage.py" string
       for you automagically. It immediately sends the redirect
       to standard out, so you're done if you call this.

    redirectUri(STRING:url)

       This is just like redirect, but it takes a URL
       and passes it unaltered to the client. Technically, you're
       supposed to redirect to a full URL, but most modern browsers
       are tolorant enough to let you put a relative path into
       a redirect. At any rate, if you use just a path, you should
       use redirect() instead.

    STRING:cookieAuthority(STRING:host)

       This is a utility function for determining the most general
       cookie authority host which applies. Basically, you setup
       your valid cookie authority in the HDF dataset, and then
       provide the specific host you're handling a request for,
       and it'll use the properly general cookie authority.

       Ex: HDF contains CookieAuthority.0 = neotonic.com
           call cookieAuthority("jeske.neotonic.com")
 
       Result: Clearsilver will return "neotonic.com" as the
         most general valid domain.

    cookieSet(STRING:name,STRING:value,
              STRING:path="/",STRING:domain="",
              STRING:time_str="",INT:persist=0)

       This sets the cookie "name" to the value "value". The rest of
       the arguments are optional. If you would like the cookie to
       persist for a year, you want to set persist=1 and then a
       set time_str to a standard RFC850 timeformat string a year
       in the future.

    cookieClear(STRING:name,STRING:domain="",STRING:path="/")

       This will clear the named cookie for the given path. Keep
       in mind that some browser can have cookies exist at
       multiple paths and domains at the same time, and that 
       the brilliant designers of HTTP didn't have the forethought
       to have HTTP tell you what paths and domains the cookies
       were coming from. This can lead to problems clearing cookies
       if you don't use the same ones that were used originally.

       Despite the futility of trying to fight this brokkenness,
       cookieClear() does send several different cookie clear
       requests to attempt to clear as many versions of your named
       cookie as possible.

    FILE:filehandle(STRING:form_var_name)

       This is used to retrieve the contents of file upload data.
       The form_var_name is the name of the form variable. You can
       retrieve other information about the file by looking in
       the HDF dataset at "Query.form_var_name".

       During upload Clearsilver just writes the file upload data 
       into temp files, so when you call filehandle, Clearsilver
       opens that temp file and gives you a handle to it.

neo_cgi - Clearsilver CGI Kit

neo_cs - Clearsilver Templates