************************************
* Clearsilver README
************************************

For more information, see the website:

  http://www.clearsilver.net/

This package includes Clearsilver, the CGI kit and HTML templating
system. For information about building and installing, see the
included INSTALL file. This package also includes tools which
help you use Clearsilver, as well as a few examples.

************************************************************
*** Clearsilver

* Clearsilver - This is our html template system and cgi kit.

There are too many great things about clearsilver to list them all
here, but here are some of the salient points:

  * get the html out of your code
  * loops, conditionals, macros, and stuff
  * cgi kit unifies query variable and cookie handling
  * super-easy to go from static mockup to dynamic page
  * run multiple front-ends on the same application code
  * super-fast C-library
  * unifies Query variable and cookie handling
  * language neutral (C,C++,Python,Ruby,Perl,Java,C#)
  * nice iterative page debugging/development features
  * generate static-data-driven page content without using any code
  * did I mention super-fast?

Supported language information:

  README.python

*************************************************************
*** Tools

* trans.py

This is our transparent translation system. It's based on how we did
translation at Yahoo!. You leave all the english strings right in the
clearsilver templates. trans parses the html and extracts your
language strings into a translation database. You can then translate
the strings using any means. (it includes tools for dump and loading
per-language files for shipping to translators). Occasionally trans
isn't smart enough to find your language strings, in this case you can
manually extract them into static language string files and trans will
automatically pick them up. When it comes time to ship, trans
generates language-independent templates, and a set of language files
from your database.

*************************************************************
*** Examples

* static.cgi

This is a standalone binary which handles Clearsilver rendering of
static content. This is a great way to play with clearsilver syntax
before you start writing dynamic CGIs with it. This is also a great
way to do webpage mockups with much more power than server side
includes.  See the INSTALL file for information about configuring
this for use with apache.

************************************************************
*** Python Environment Information

* Python      - we know it and love it
* Apache      - the defacto standard

* PyApache/mod_python

Either one is fine, the goal is to load all Python code once, before
Apache forks. Then, for every web-request, Apache just makes a
function call into the Python environment which serves the page. This
is "really fast" as it gets rid of all of the parsing and loading of
Python. Various versions of PyApache and mod_python have gained and
lost and gained again the ability to do this well. We used a hacked
version of PyApache way back when, I think mod_python does this out of
the box today.



************************************************************
*** Python Tools

* CSPage.py

This is our "page rendering superclass". It's pretty simple and has
nice machinery for some of the stuff talked about on this list. For
example, it has nice debugging and redirect support, and it has a
mechanism for mapping form submit buttons to method names. Here is an
example of how the form stuff works:

 <form action="foo.py">
   <input type=submit name="Action.Foo" value="Do Foo!">
 </form>

 class MyPage(CSPage):
    def setup(self):
        # this runs before everything else
        pass
    def display(self):
        # this is a regular non-submission render
        pass
    def Action_Foo(self):
        # this is run automatically when the Foo submit button is clicked
        pass

* odb.py

This is an object to relational database mapping tool. It makes
interacting with SQL databases really easy. It gives you a place to
put all your SQL code. It also could be changed to work with flat
files as well. We have some nice hooks to connect this to Clearsilver,
so rendering database data into webpages is really easy. Here is an
example:

rows = mydb.mytable.fetchAllRows()        # fetch all rows
rows.hdfExport("CGI.tabledata",ncgi.hdf)  # export them into the dataset

# it is also really easy to change rows:

row = mydb.mytable.fetchRow( ('user', 'jeske') )
row.email = 'jeske at chat.net'
row.save()