|home | news | documentation | source | downloads | discussion | projects | license|
Comparison with PHP, ASP, JSP
Comparison with XML/XSLT
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.