Config Vars

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.

Config.NoCache

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.

Config.CompressionEnabled

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.

Config.TimeFooter

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.

Config.WhiteSpaceStrip

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.

Configuration

Config.Upload.TmpDir

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.

Config.Upload.Unlink

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.

CookieAuthority.*

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.

Config.TagStart

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.

Config.VarEscapeMode

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.

ClearSilver.DisplayDebug

If this variable is set to 1, then render will include a dump of the HDF contents at the end of the rendered page.

ClearSilver.WhiteSpaceStrip

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