Re: Tutorials or HOWTOs

Just as a preface, though clearsilver IS going to be faster than most
templating languages written in scripting languages, chances are its not
going to be faster enough, especially if you are using it from a
scripting language.

What I mean by that is that unless you have a pretty static website, I
wouldn't expect your template rendering to be more than 20% of the time
of a web page, and possibly even less.  So, at most I'd think you could
double your page views moving from something like Perl/Mason to
Perl/ClearSilver.  You may be better off figuring out how to scale your
current solution, either by getting faster hardware or more hardware.
Granted, its possible you are rich in time and not capital...

Its also possible your site is big enough that such things matter.  For
instance, if you're using 300 machines, then maybe saving 60 machines
moving to clearsilver is worth it.

Now, assuming you've read the above and you still want to understand
ClearSilver... another caveat that perhaps someone else can answer
better than me, is I don't know how complete the Perl wrapper for
ClearSilver is.  A friend wrote it for his personal site, and I think he
eventually went back to python.  That being said, it should be
complete enough, and we do welcome patches.

ClearSilver to date has been treated more as "just" a templating
language, and not a framework.  The lack of HOWTOs represent 
"everyone uses it differently".  "Our" way of doing it (the two original
developers) is somewhat encapsulated in the example python script, in
python/examples/base/CSPage.py, but it was never really cleaned up.  At
some point, we hope to open source the "Java ClearSilver Framework" we
use at Google, which is basically a Java version of CSPage that should
be more clean.

There is a bare bones example on the web page, albeit in Python:

http://www.clearsilver.net/docs/intro_clearsilver.hdf

The first question you answer is always "how to map a url to a script".
Usually, I've used the "one url path to one class" model.  If using
CSPage, that means each "page" is a class derived from CSPage (or a
common class thats specific to your application derived from CSPage).
In CGI, you can map each page to a file, and you could even use
mod_rewrite or something to hide the .py or .pl on the end if you care.
Generally, its easy enough to eventually wrap all the classes and have
some other class (like a servlet or whatever) which does your url to
page class mapping.  Google tends to work differently then this, most
sites have just a single "path", and then one of the query arguments is
the "page" or "command".  That way, there's no complication to the
parsing and dispatch.

Typically, any given page generally has a static hdf file, a static cs
template and the script.  So, /foo page would have foo.py, foo.cs and
foo.hdf.  foo.hdf isn't generated, its the static initial data.  Your
foo.py would then creat an HDF object, and then load the static data
into it.  You'd then add more data to it based on the arguments, etc.

So: HDF files aren't generated (usually).  You do generate an HDF data
structure in memory, using setValue/etc, and then pass that to the
render methods along with the CS file.

I recommend some easy encapsulation method to make it easy to add new
pages, and to keep them separate.  So, you can either have completely
separate invocations per page, or more likely you have a single
"script", but the main part of the script is designed to parse some
arguments and then farm each different page off to a different class or
file for handling that page.

I hope this helps.

Brandon

On 05/12/07 Aaron uttered the following other thing:
> I run a gaming website (Super Duper Games) using Perl and Mason.  I
> have begun looking for faster alternatives and want to try some
> experimentation with CS.  The problem is, the documentation is void of
> any practical examples or HOWTOs.  Google isn't helping me much
> either.  Using Apache and Perl, how do I actually setup an environment
> in which I can work?  When do the HDF files get generated?  Do the
> individual CS files trigger HDF generation, or is there some explicit
> way this is to be done?  Do I point my URLs to some Perl script that
> invokes the CS framework, or is there something I do in Apache to
> process everything?  If I point things to scripts, do I just write one
> monolithic script, or separate (in this case) Perl files for each
> page?  I would really appreciate any further information you could
> provide.  I really want to give this a shot.

-- 
  "... God is an old man, up in the sky with 10 laws that if you don't
   follow, you'll burn in hell, but he loves you. "
			    -- George Carlin, PI 5/30/97
                                           http://www.fiction.net/blong/