GitHub - ac000/libflate: A HTML template library for C by Fabien Menemenlis

ac000 / libflate Public

Notifications You must be signed in to change notification settings
Fork 3
Star 6

A HTML template library for C by Fabien Menemenlis

Notifications

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.gitattributes		.gitattributes
.gitignore		.gitignore
COPYING		COPYING
Makefile		Makefile
README		README
checktpl.c		checktpl.c
flate.c		flate.c
flate.h		flate.h

Repository files navigation

FLATE Library (Fast Template 2.0.1)
(c) Fabien MENEMENLIS (nihilist@dead-inside.org)

This program is released under the LGPL License. For copying information
see the file COPYING.


1. Description

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("<html>hello</html>"); is now history.


2. Installation

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


3. Changes

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. Documentation

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");
<!-- #BEGINZONE myzone --><html code goes here><!-- #ENDZONE myzone --> is a
zone that will be hidden until you call flateSetVar(f, "myzone", "");
<!-- #BEGINTABLE mytable --><html code><!-- #ENDTABLE mytable --> is a zone
that will be displayed as many times as you call the function
flateDumpTableLine(f, "mytable");


4.2 Sample HTML code

<html>
<h1>
  ##title##
</h1>
<body>
<p>

<!-- let's imagine you either want to show on your page a sun if it's daytime
     or a moon if it's nighttime -->
<!-- #BEGINZONE sunzone -->
  <img src="sun.png">
<!-- #ENDZONE sunzone -->
<!-- #BEGINZONE moonzone -->
  <img src="moon.png">
<!-- #ENDZONE moonzone -->

<!-- the following will display a table with 2 columns and will be fed by
     the CGI -->
<p>
The following events are recorded in your database:
<table>
<!-- #BEGINTABLE dbline -->
<tr>
  <td>
    ##number##
  </td>
  <td>
    ##value##
  </td>
</tr>
<!-- #ENDTABLE dbline -->
</table>
</body>
</html>


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
<!-- #INCLUDEFILE /path/to/otherfile.html -->
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
to declare:
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.

flateSetFile(&f, "template.html");
  will load the file into memory and initialize the f template.

flateSetVar(f, "variable", "value", fmt_func);
  will set ##variable## in the HTML template to "value". If fmt_func is
  not NULL, value will be passed to fmt_func and the value returned from
  fmt_func will be used. This can be used to render XSS attacks void.

flateSetVar(f, "myzone", "", NULL);
  will display the block between
    <!-- #BEGINZONE myzone --> <!-- #ENDZONE myzone -->

flateDumpTableLine(f, "dbline");
  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
  flateDumpTableLine(f, "dbline");

Once you're done, you can use:
flatePrint(f, "text/html");
  this will output the whole page (the result) to stdout with the given content
type.
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.

flateFreeMem(f);
  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
  input.
  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:
  char *s;
  s = strdup("variable,50:second,30");
  form = flateSetForm(s);
  free(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
called.

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.
Example:
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 <at> dead-inside.org if
you have any question or want to report a bug.

Fabien MENEMENLIS