FLATE Library (Fast Template 2.0.1)
(c) Fabien MENEMENLIS (firstname.lastname@example.org)
This program is released under the LGPL License. For copying information
see the file COPYING.
FLATE is a library used to handle HTML template files outside C code as well as
basic CGI input/output such as retrieving variables from HTML forms or cookies.
Template files can be manipulated from the C code with various functions to
change variables and display or hide part of the HTML code. The best way to
sum it up would be that printf("hello"); is now history.
Simply do a "make" in the root directory of the archive. The resulting library
should be linked with your C cgi:
gcc cgi.c -o cgi -L/path/to/Flate -I/path/to/Flate -lflate
Flate 2.0 breaks compatibility with version 1.4 as it can now handle more than
a template file in memory at a time. Perl support has also been removed due to
my lack of interest for this language.
4.1. HTML Code
A few extensions have been added to the HTML language so that you can easily
modify the code from your C application.
##variable## is a text zone that will be replaced by the value you want when you
call flateSetVar(f, "variable", "value");
zone that will be hidden until you call flateSetVar(f, "myzone", "");
is a zone
that will be displayed as many times as you call the function
4.2 Sample HTML code
The following events are recorded in your database:
You can nest tables inside tables, variables and zones inside other zones etc.
You can use the tool "checktpl" to check if your HTML template is valid
(when the code gets complex it's easy to mispell a zone or table name: this
would result in the page not being displayed correctly, or even not at all).
You can also include external template files using
Note that that path is relative to the SERVER_ROOT variable set in your
Apache/web server environment (this wasn't true with Flate 1.4).
4.3. Template functions
You first need to include "flate.h" in your program.
Each template in memory will be allocated in a Flate structure that you have
Flate *f = NULL;
It must be set to NULL, or the function freeing the structure will be called,
leading to a crash if *f points to a random pointer.
will load the file into memory and initialize the f template.
flateSetVar(f, "variable", "value");
will set ##variable## in the HTML template to "value".
flateSetVar(f, "myzone", "");
will display the block between
will print the zone between #BEGINTABLE and #ENDTABLE, with the variables
set before. Once printed, the variables are set to NULL again, you can
reuse flateSetVar(f, "variable", "value"); to set them for the next
Once you're done, you can use:
this will output the whole page (the result) to stdout with the given content
You can also populate a buffer with char *buf = flatePage(f);
this will dump the output in a buffer pointed by buf. You need to free(buf);
after using this function.
will free all memory used by the f template.
4.4. Form reading
Flate 2.0 can easily retrieve variables from HTML Forms passed with the GET or
POST method indifferently.
You must first declare a FlateForm structure:
FlateForm *form = NULL;
You have then two methods to pass the variables you want to retrieve:
- add them one by one with the flateAddForm() function:
form = firstfield = flateAddForm(form, "variable", 50, isalnum);
"variable" is the variable name in the HTML Form, 50 the maximum length of
the string and isalnum a function called to check the validity of the
characters passed in the form, or NULL if you don't want to check the user
You would add another variable with
form = secondfield = flateAddForm(form, "second", 30, NULL);
(this is a linked list so you need to point flateAddForm() to "form" every
time you add a variable)
- pass a single string with all the variables:
s = strdup("variable,50:second,30");
form = flateSetForm(s);
Note that the s string will be modified by flateSetForm() so you cannot do
a simple char *s = "variable,50:second,30"; as the string declared this way
is read only.
Once you have set the variables you want to retrieve, call flateReadForm(form);
to populate the internal buffers with the HTML form values.
To access the variables values, if you have used flateAddForm() you can
directly access firstfield->value for the first variable or second->value for
the second: they will contain the variables passed with the GET or POST methods
(as a char * type) or NULL if the form does not contain these variable names.
If you have used flateSetForm() you can get the variable value with
char *val = flateGetForm(form, "variable");
4.5. Cookies manipulation
Cookies manipulation is really basic but I included these functions for people
like me who always forget about the format of HTTP cookies:
flateSetCookie(Flate *f, char *name, char *value, char *domain, time_t expires);
expires is in seconds or 0 for a session cookie or -1 to remove it
cookies are set in the HTTP headers so they will be set when flatePrint() is
flateGetCookie(char *value, int valuesz, char *cookie, check_function);
will retrieve the cookie named in "cookie" inside the "value" buffer if
characters matches the check_function() or NULL when no checking is wanted.
char cookie[50 + 1];
flateGetCookie(cookie, 50, "mycookie", isdigit);
Note that flateSetCookie() is bound to a Flate structure, so you have to call
flateSetFile() with a template file first. It might be a problem if you don't
want to print anything after you have set a cookie and instead need to do
a redirect, but I've not come accross a better API idea yet.
5. Suggestions and bug reports
You can reach me at the following address: nihilist dead-inside.org if
you have any question or want to report a bug.