![]() |
![]() |
![]() |
home | news | documentation | source | downloads | discussion | projects | license |
![]() |
![]() |
![]() |
![]() Overview Why Clearsilver? Clearsilver Basics HDF Dataset Template Syntax Expressions Macros Functions CGI Kit Config Vars FAQ API Reference API Concepts C API Python API Introduction Perl API Java API Tools odb.py Comparison with PHP, ASP, JSP Comparison with XML/XSLT |
![]() |
Introduction to CGI Programming with ClearSilver & PythonThis document is meant to be a fairly complete tutorial on how to write some dynamic web pages using a webserver that supports CGI. In order to use this tutorial, the following assumptions are made:
What is CGI?CGI, or the Common Gateway Interface, is the lowest common denominator for writing dynamic web pages. It is a very simple interface by which a web server can launch a program which generates a web page.
In general, there are very few things that you'll need access to from the client:
This interface is not meant to be high performance, it isn't meant to be complicated, but it works. If your CGI is written in C, you can easily do 500k pageviews a day on a single server. In general, languages with more start-up overhead such as interpreted languages like Perl & Python, or JIT languages like C# and Java, will seem sluggish as they take longer to start up. For those languages, you probably want to use something more long running, such as PyApache, mod_python, mod_perl, or mod_jk. Trakken is a fairly complicated Python web application with lots of dependent modules that need to be loaded. In production, we run Trakken under PyApache, but in development we run it as regular CGI. The start-up overhead is about 0.5s in CGI mode. Since our goal is all pages less than 0.2s, that was obviously too long, and besides all that parsing and byte-compiling is work the machine doesn't need to do continuously. If you are running in CGI mode, you'll want to make sure that the webserver can write to the directory containing your python code so that it can create pre-compiled .pyc files. I'll leave the obvious security implications of that up to you.
ClearSilver CGI BasicsThe ClearSilver CGI Kit works by adding an interface layer between the standard CGI interface and your code. This works by taking the information from the CGI interface, and adding it to the HDF dataset. Your program then continues to fill in the dataset based on the data in the dataset. Finally, your program chooses a template, and asks the CGI Kit to display the template with your dataset. The CGI Kit then takes care of formatting the output in a manner that the CGI interface expects.Client \ Webserver \ CGI \ ClearSilver HDF \ Your program ClearSilver HDF / + ClearSilver Template CGI / Webserver / Client /Because of this separation, you can easily move your program to different environments. By creating an analog interface, you can replace CGI with something else, such as PyApache or mod_python. You can rewrite your program in a different language. As long as it took the same inputs into HDF and wrote the same outputs back into HDF, the whole thing should just work. Starting with Hello WorldHello world doesn't actually require any program beyond the includedstatic.cgi . The static.cgi program included with
ClearSilver is almost the most basic ClearSilver CGI program: it merely
uses the URL information in the HDF to choose a template, and then
asks the CGI kit to display that template. This entire website, my
personal website (including my
blog) is just static.cgi with the right templates and the right HDF
data files.
But, let's do the Hello World anyways. Here's the
And the hello.cst template:
Of course, that's not particularly interesting without actually modifying the generated code, so this time let's load some static HDF data and display that. Here is the hello.hdf file:
Now, let's modify hello.py to load our static data:
And add to hello.cst to use the Hello
variable:
Or, to display the days of the week:
Now, without modifying the program, you can use the form variables, so rewrite your URL to: /cgi-bin/hello.py?day=1 , and use this
hello.cst
See how the day variable is available in the HDF data set as Query.day ? That variable is URL decoded. Of course, if
you are going to use the variables directly, you need to be careful to
prevent HTML errors and Cross-Site scripting attacks by encoding it, for
instance: /cgi-bin/hello.py?name=Brandon%20Long :
html_escape is one of the filters available to manipulate string
expressions.
One last piece to complete the puzzle, and that's manipulating variables
from python. Let's modify our hello world to display a file:
And our hello.cst
Now, call this with /cgi-bin/hello.py?file=hello.py
|
![]() |