CGI Kit

There are two levels at which you can use ClearSilver. You can use the templating system by itself, in conjunction with some other CGI kit, such as cgi.py or CGI.pm, in a Java-servlet, or even in non-CGI contexts, such as expansion of configuration files, code generation, documentation, email messages, etc. Or, when it is available, you can use ClearSilver templating system through the ClearSilver CGI Kit.

The ClearSilver CGI kit provides an interface to common CGI interface which integrates with the ClearSilver template language. It preloads CGI information into your ClearSilver dataset, making that information available in a standard location in the HDF dataset.The ClearSilver CGI kit also supports RFC 2388 file uploads via HTTP, and it is one of the only interfaces which allows your CGI to retrieve upload status information via a callback.

1. Preloaded HDF Data

Several different types of data are preloaded into the HDF dataset by the Clearsilver CGI kit. This allows Clearsilver template code direct access to information such as query parmaters and Cookies. This also makes it easy for your application code to get this data from one place (the HDF context) with a single API. Because this is a terribly useful utility, environment which operate without the Clearsilver CGI kit may wish to emulate this behavior. For example, there is a Java servlet class example which will populate the apporpriate HDF elements from the Java-servlet API.

1.1. HTML Form Variables

The HTML form GET or POST variables are pre-populated into the HDF dataset at Query.*. If a paramater is specified multiple times, then the element will have subelements including the different values provided. The base variable will retain the last value provided. Here is an example of an HDF Query.* tree that might result from an HTML form:

Query.name = David
Query.email = david@neotonic.com
Query.multSelect = third value
Query.multSelect.0 = first value
Query.multSelect.1 = second value
Query.multSelect.2 = third value

1.2 Cookies

The HTTP Cookie data is provided, along with decoded versions of individual cookies. Here is an example of the HDF Cookie.* tree that might result:

Cookie = help_pos_x=461; help_pos_y=206; E=v=1&e=305,1,303; 
Cookie.help_pos_x = 461
Cookie.help_pos_y = 206
Cookie.E = v=1&e=305,1,303

1.3. HTTP headers

The following HTTP headers are mapped into HDF:

HTTP.Accept = image/gif, image/x-xbitmap, image/jpeg, image/pjpeg
HTTP.AcceptEncoding = gzip, deflate
HTTP.AcceptLanguage = en-us
HTTP.Cookie = help_pos_x=461; help_pos_y=206; E=v=1&e=305,1,303; 
HTTP.Host = jeske-dev.trakken.com
HTTP.UserAgent = Mozilla/4.0 (compatible; MSIE 6.0;)
HTTP.Referer = http://www.clearsilver.net/cgi-bin/test.py

1.4. Apache Environment

CGI.DocumentRoot = /home/jeske/htdocs
CGI.GatewayInterface = CGI/1.1
CGI.QueryString = done=1
CGI.RemoteAddress = 216.103.193.234
CGI.RemotePort = 1870
CGI.RequestMethod = GET
CGI.RequestURI = /cgi-bin/test.py?done=1
CGI.ScriptFilename = /home/jeske/htdocs/cgi-bin/test.py
CGI.ScriptName = /cgi-bin/test.py
CGI.ServerAddress = 64.167.132.245
CGI.ServerAdmin = webmaster@neotonic.com
CGI.ServerName = www.clearsilver.net
CGI.ServerPort = 80
CGI.ServerProtocol = HTTP/1.1
CGI.ServerSoftware = Apache/1.3.26 (Unix)

2. HTTP Upload

The CGI Kit also provides a facility for parsing of HTTP POST data, including multi-part file upload. It has a unique callback interface which allows you to retrieve constant status information about the progress of an ongoing upload. Handling the POST data occurs when you call cgi_parse(). You must have already setup the upload callback, either by calling setUploadCB() from a wrapper, or by setting the upload_cb value of the CGI structure from C/C++.

After parse has completed, the Query.* HDF value for your INPUT TYPE=FILE paramater will contain the filename of the file uploaded. You then provide the name of your form value to the cgi_filehandle() function to get a FILE * for an uploaded file.

3. Utility Functions

Utility functions are provided to handle redirection, as well as setting cookies. Refer to the reference for information about how to use these functions.