API

API Reference

The Clearsilver programming API can be used from several programming languages, including C/C++, Python, Perl, and Java. The wrapper APIs are designed to be nearly the same from all languages, so that no additional learning is necessary when transitioning from one programming language to another.

However, there are differences between the different wrappers. When appropriate, the wrappers will contain features which make accessing Clearsilver more natural from the host language. In some cases, features are not available for all wrappers. For example, the Clearsilver CGI kit can be optionally used instead of other CGI handlers in C/C++, and Python. However, because of how widespread the Java-servlet standard is, the Clearsilver CGI kit is not provided under Java. Instead there is emulation for some useful features of the Clearsilver CGI Kit inside the Java-servlet environment.

API Concepts

The clearsilver API is separated into three componenents: HDF Objects, CS Objects, and the CGI Kit.

1. HDF Objects

The Hierarchial Data Format (HDF) is managed by HDF Objects. These objects provide an API to load, save, read, and change HDF datasets. Because of the direct naming scheme used in HDF, interacting with this dataset is generally much easier than with DOM datasets such as XML. For more information about HDF read the HDF Concepts. However, keep in mind that HDF datasets are always organized in insertion order. The following simple Java example should give you an idea of how to create and access HDF datasets. See the language-specific documentation for more specific information.

HDF hdf = new HDF();
hdf.setValue("A.B.C","1");
hdf.writeFile("myhdffile.hdf");

HDF hdf2 = new HDF();
hdf2.readFile("myhdffile.hdf");
String val = hdf2.getValue("A.B.C","default string");

// val == "1"

More complex HDF operations are available, such as walking the HDF tree, and copying HDF datasets from one place to another.

2. CS Objects

The Clearsilver template rendering is managed by CS objects. These objects are handed an HDF dataset environment, and a set of clearsilver template fragments, either from strings or files. The objects parse the run the template fragments and ultimately produce a formatted output string. The following simple Java example should give you an idea of how to render a template using HDF and CS objects together.

// create a new simple dataset
HDF hdf = new HDF();
hdf.setValue("A.B.C","Hello World");

// create a rendering context
CS cs = new CS(hdf);

// define and parse a template string
String template = "  ";
cs.parseString(template);

// render the template
String output = cs.render();

3. CGI Kit

The CGI Kit is optional and handles form get or post query parsing, redirects, and other CGI functions. It is designed to fit well into an apache CGI or apache module environment. In addition to performing the functions you expect of other CGI handling systems, this kit also pre-populates information into the HDF dataset. For example, HTTP query variables are put in the dataset as Query.varname. This allows CS Templates to get access to query variables in a standard way without any additional code.

Some environments supply their own CGI handling, such as Perl's CGI.pm or Python's cgi.py. Clearsilver's implementation has several advantages, including form upload callbacks, and hooks for operating as an apache module. Other environments, such as Java's Servlet container interface, will require you to use the native CGI environment. For convenience, the Clearsilver Java connector comes with a Servlet extension which pre-populates the HDF dataset in a manner similar to the Clearsilver CGI Kit.