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 = email@example.com Query.multSelect = third value Query.multSelect.0 = first value Query.multSelect.1 = second value Query.multSelect.2 = third value
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 = 184.108.40.206 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 = 220.127.116.11 CGI.ServerAdmin = firstname.lastname@example.org 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.