|
Documentation
|
|
|
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.
|