CLASS CS_OBJECT
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.