home | news | documentation | downloads | discussion | projects | license  

Why Clearsilver?
Clearsilver Basics
   HDF Dataset
   Template Syntax
   CGI Kit
      Config Vars
API Reference
   C API
   Python API
   Perl API
   Java API

Comparison with PHP, ASP, JSP
Comparison with XML/XSLT


The following HDF variables are used by the ClearSilver CGI Kit:

Changing the output

cgiout.Location, cgiout.Status, cgiout.ContentType, cgiout.other.*
This variable tree is used to send extra HTTP & CGI headers during cgi_display(). Location, Status and ContentType are the known values. These are mapped directly to the Location, Status and Content-Type headers. cgi_display() will also walk the cgiout.other.* vars, using the value as output. Ie, cgiout.other.encoding = Content-Encoding: gzip will add a Content-Encoding: gzip header to the output.

If Config.NoCache is set, then the following headers will be added during cgi_display():
  Pragma: no-cache
  Expires: Fri, 01 Jan 1990 00:00:00 GMT
  Cache-control: no-cache, must-revalidate, no-cache="Set-Cookie", private
These headers are designed to attempt to prevent all browsers and proxies from caching the page. This is generally a very evil thing to do, as it means any page render, including the user pressing the back button, for some browsers this will also include printing, viewing page source, etc.

If this is set to a positive integer, and the output is HTML, then cgi_display will gzip compress the output for browsers which support it.

By default, cgi_display will add an "execution time" html comment to the end of the rendered page if the page output type is text/html. The format of the comment is <!-- 0.5:1 --> where the first number is the total time between the call to cgi_init and the call to cgi_display, and the number after the colon is 1 if the output is compressd, and 0 if not.

This variable indicates the amount of whitespace stripping that is applied to html output in cgi_display. ClearSilver has a tendency to add lots of whitespace to your output unless you are very careful with the formatting of your clearsilver commands. This is because all whitespace is included in the output, which includes and space you use to indent your clearsilver commands, and any newlines you add. There are three levels available. 0 is no whitespace stripping. 1 is a somewhat "minimal" whitespace stripping that attempts to just remove extra lines but leave your formatting mostly the same. 2 is designed to strip all extra whitespace. The default is level 1. If you are compressing your output, you probably don't need to remove the whitespace.


Where the PUT handler and the RFC2388 multipart/form-data POST handler create temporary files that are uploaded to the server. The default value is /var/tmp.

By default, the PUT handler, and the RFC2388 multipart/form-data POST file handler unlink the files they create in cgi_parse as soon as they create them, but keep the file handle open to the files. This means that as soon as the files are closed, they will be removed. If the CGI prematurely exits, the files will automatically be removed. If this is set to 0, the files will not be unlinked immediately. This would allow you to access the files directly from your CGI, instead of only accessing them through the existing filehandle returned by cgi_filehandle. The files will be in Config.Upload.TmpDir and be named cgi_upload.XXXXXX as created by mkstemp(). The files will be removed in cgi_destroy(), but if the CGI exits prematurely, the files will not be removed. You will need to have a periodic job cleanup old files to prevent your filesystem from filling up.

A cookie authority is the domain for which a cookie is said to be valid. Ie, if your CGI is running on www.neotonic.com, and you want your cookie to be valid for all neotonic.com domains, the authority is .neotonic.com. If your CGI is responding to multiple domains, the easiest way to handle this is to have a list of domain authorities, and use the cgi_cookie_authority call to determine what domain authority to use in the cgi_cookie_set call. The CookieAuthority.* variables each contain a single authority, ie:
    CookieAuthority.0 = .neotonic.com
    CookieAuthority.1 = .neotonic.co.uk
    CookieAuthority.1 = .neotonic.jp
So, the cookie will be valid on www.neotonic.com and www1.neotonic.com.

This variable is not specific to the CGI Kit. You can set this variable to change the clearsilver command. By default, all clearsilver commands are enclosed in <?cs ... ?>. You can replace the cs portion of this with another tag using the Config.TagStart variable.

This variable is not specific to the CGI Kit. This variable must be set before the call to cs_init() (which is done in cgi_display() if using the CGI Kit). This variable sets the default escape mode for all var: commands. Currently, possible values are none, script, url, and html.

Debug Variables

Query.debug, Config.DebugPassword, Config.DebugEnabled
If Config.DebugEnabled is set to 1, and if Query.debug is non-empty and matches Config.DebugPassword, then cgi_display with add debug output to the end of the rendered page. This output is subject to change, but currently includes the environment variables and the full HDF dump.

Query.debug, Config.DumpPassword, Config.DebugEnabled
If Config.DebugEnabled is set to 1, and if Query.debug is non-empty and matches Config.DumpPassword, then cgi_display will dump the HDF and the CS parse tree as text/plain instead of rendering the page.

Query.debug_pause, Config.DebugPassword, Config.DebugEnabled
If Config.DebugEnabled is set to 1, and if Query.debug_pause is non-empty and matches Config.DebugPassword, then cgi_init will call sleep(20). This will cause the CGI to pause for 20 seconds, allowing you to attach to the running CGI will a debugger, strace, truss, or other debugging aid.

Query.xdisplay, Config.Displays.*, Config.Debugger
Used during cgi_init(). If you specify a form value of xdisplay=yourmachine:0 to a CGI, cgi_init() check your display against the list of allowed displays in Config.Displays (ie, Config.Displays.0 = yourmachine:0, and if it matches, it will launch the debugger specified by Config.Debugger against the currently running CGI. This allows you to use an X based debugger on a currently running CGI. The default Config.Debugger is
/usr/local/bin/sudo /usr/local/bin/ddd -display %s %s %d
Where the first %s will get the value of Query.xdisplay, the second %s gets the argv[0] (ie, the path to the currently running program) and the %d is the PID of the running program.

Java Variables

The Java JNI wrapper does not use the CGI Kit, but it does have a couple variables of its own to control the CS.render output.
If this variable is set to 1, then render will include a dump of the HDF contents at the end of the rendered page.

This is used the same as the Config.WhiteSpaceStrip variable in the CGI Kit.

Previous: The CGI Kit Next: FAQ

Copyright © 2009 Brandon Long, All rights reserved.