WebTemplate library

Summary: WebTemplate allows C programs to easily make web pages through the use of HTML templates.
Version: 1.15
Download:Current version: webtpl-1.15
The template system facilitates the separation of HTML from c; that is to say, the presentation of data from the generation of that data. It accomplishes this through the use of macros and dynamic blocks in the template file. The term parse as used here really has more the meaning of expand. The reason is historical.

A macro is identified by any sequence of the form {name}, where name consists entirely of alphanumeric characters or underscores, and is used to identify the macro within the program. A macro can acquire a value, a string, by one of three ways:

In the latter case the value of the macro becomes text of the template, with all internal macros and dynamic blocks expanded.

A dynamic block is identified by a sequence of the form,

<!-- BEGIN DYNAMIC BLOCK: name -->
HTML code
<!-- END DYNAMIC BLOCK: name -->

where name consists entirely of alphanumeric characters or underscores, and is used to identify the block within the program. The 'BEGIN' and 'END' tags must be on lines by themselves. They cannot be mixed with other text on the same line.

Each time a dynamic block is parsed, the resulting text, including all macros or nested dynamic blocks, are added to the value of the enclosing template.

WebTemplate allows an abbreviation of the block identifier. So the above pattern could look like this:

<!-- BDB: name -->
HTML code
<!-- EDB: name -->

The BDB and EDB still have to be by themselves on the line, however.

The library allows comments in template files. Comments are identified by caller-defined markers in the template text.

start_comment_marker ...
Comments
end_comment_marerk ...

or

single_comment_line_marker Comments

where all of the markers must appear at the start of a line.

The API WebTemplate_set_comments activates comments.

The common procedure for the template system is something like this:

  1. Load one or more templates that contain the HTML presentation of your application.

  2. For single replacement values: define the macro values for each dynamic variable.

  3. For multiple replacement values, tables, lists, and etc.:
    1. Define the macros used by the dynamic block, and
    2. parse the block into its parent.

  4. For each template that forms part of a page: Parse it into a macro definition for its parent.

  5. Parse the master template.

  6. Write the resultant macro value to the browser.

See the example.

  Contents
 

WebTemplate API

 WebTemplate_get_error_string

Description: Get the text message for an error
Syntax: char* WebTemplate_get_error_string(WebTemplate W)
Arguments:
Return: Text of the error.
Errors:
Notes:
  1. Any call that results in an error stores a text message in the template context. This function retrieves the message.
  2. The message is cleared on any successful action.
  3. Do NOT free the message.

 WebTemplate_new

Description: Initialize a template structure
Syntax: WebTemplate WebTemplate_new()
Arguments:
Return:
Errors:
Notes:
  1. This call must precede all others. Although you might make use of two template structures at once, I have never had the need to do so.

 WebTemplate_free

Description: Free a template structure
Syntax: void WebTemplate_free(WebTemplate W)
Arguments:
W: A WebTemplate
Return:
Errors:
Notes:
  1. frees the memory used by a WebTemplate

 WebTemplate_set_comments

Description: Set the comments delimiters
Syntax: void WebTemplate_set_comments(WebTemplate W, char* start, char* end)
Arguments:
W: A WebTemplate
start: string that signals start of a comment
end: string that signals end of a comment
Return:
Errors:
Notes:
  1. If the end is NULL then start identifies a single-line comment.
  2. In the template the start and end strings must appear at the beginning of a line.
  3. Comment delimiters must be setup before reading a template.

 WebTemplate_get_by_name

Description: Read a template from a named file
Syntax: int WebTemplate_get_by_name(WebTemplate W, char* name,  char* filename)
Arguments:
W: A WebTemplate
name: Name to be assigned to this template
filename: File containing the template
Return: 0 if OK; else the unix errno or -1.
Errors:
Notes:
  1. The template can be referenced by the string name
  2. Non-system errors are indicated by -1

 WebTemplate_get_by_fd

Description: Read a template from a file descriptor
Syntax: int WebTemplate_get_by_fd(WebTemplate W, char* name,  int fd)
Arguments:
W: A WebTemplate
name: Name to be assigned to this template
fd: Open file descriptor from which to read the template
Return: 0 if OK; else the unix errno or -1.
Errors:
Notes:
  1. The template can be referenced by the string name
  2. Non-system errors are indicated by -1

 WebTemplate_get_by_fp

Description: Read a template from a file pointer
Syntax: int WebTemplate_get_by_fp(WebTemplate W, char* name,  FILE* fp)
Arguments:
W: A WebTemplate
name: Name to be assigned to this template
fp: Open file from which to read the template
Return: 0 if OK; else the unix errno or -1.
Errors:
Notes:
  1. The template can be referenced by the string name
  2. Non-system errors are indicated by -1

 WebTemplate_assign

Description: Assign a value to a macro
Syntax: void WebTemplate_assign(WebTemplate W, char* name, char* value)
Arguments:
W: A WebTemplate
name: Name of the macro
value: Value of the macro
Return:
Errors:
Notes:
  1. This is the direct way to give a macro a value.

 WebTemplate_assign_int

Description: Assign an intever value to a macro
Syntax: void WebTemplate_assign_int(WebTemplate W, char* name, int value)
Arguments:
W: A WebTemplate
name: Name of the macro
value: Integer value of the macro
Return:
Errors:
Notes:
  1. The macro value will be the decimal representation of the integer.

 WebTemplate_parse_dynamic

Description: Parse a dynamic block
Syntax: int WebTemplate_parse_dynamic(WebTemplate W, char* block_name)
Arguments:
W: A WebTemplate
block_name: Identifier of the block to be parsed
Return: 0 if OK; 1 if template not found.
Errors:
Notes:
  1. Evaluates all macros and nested blocks and adds the resultant text to this block's parent template.
  2. The block's identifier is a dotted concatenation of the template's name, the names of any enclosing blocks, and this block's name. For example, the identifier of a block named "item", within a block named "list", in the template "page", would be "page.list.item".

 WebTemplate_parse

Description: Parse a template
Syntax: int WebTemplate_parse(WebTemplate W, char* macro_name, char* template_name)
Arguments:
W: A WebTemplate
macro_name: Name of the macro to be assigned the template's value
template_name: Name of the template to be parsed
Return: 0 if OK; 1 if template not found.
Errors:
Notes:
  1. Evaluates all macros and nested blocks and assigns the resultant text to the macro's value.

 WebTemplate_set_output

Description: Set output file descriptor
Syntax: void WebTemplate_set_output(WebTemplate W, int fd)
Arguments:
W: A WebTemplate
fd: file descriptor to use for writing
Return:
Errors:
Notes:
  1. All output will go to the designated file descriptor. Default is to standard output.

 WebTemplate_add_header

Description: Add a header name and value
Syntax: void WebTemplate_add_header(WebTemplate W, char* name, char* value)
Arguments:
W: A WebTemplate
name: Name of the header item
value: Value of the header
Return:
Errors:
Notes:
  1. Adds the name/value pair to the header list

 WebTemplate_macro_value

Description: Retrieve a macro value
Syntax: char* WebTemplate_macro_value(WebTemplate W, char* name)
Arguments:
W: A WebTemplate
name: Name of the macro
Return: A string containing the macros's value, NULL if not found
Errors:
Notes:
  1. You are responsible for freeing the returned string

 WebTemplate_write

Description: Output a macro value
Syntax: int WebTemplate_write(WebTemplate W, char* name)
Arguments:
W: A WebTemplate
name: Name of the macro to be written
Return: 0 if OK; else the unix errno or -1.
Errors:
Notes:
  1. Writes the macro's value to standard output or to the file descriptor specified by a previous call to WebTemplate_set_output.
  2. Unless you have previously called WebTemplate_set_noheader, an HTML header will automatically be written prior to the first macro output.
  3. The macro is usually the final result of one or more template evaluations and constitutes the complete web page.
  4. Returns -1 if macro not found

 WebTemplate_header

Description: Output headers
Syntax: int WebTemplate_header(WebTemplate W)
Arguments:
W: A WebTemplate
Return: 0 if OK; else the unix errno.
Errors:
Notes:
  1. This writes the html headers, plus any cookies. Writing the headers explicitly allows you to print diagnostics to the web page.
  2. If this procedure is not called, the headers will be sent when the rest of the page is written.

 WebTemplate_set_noheader

Description: Set no header option
Syntax: void WebTemplate_set_noheader(WebTemplate W)
Arguments:
W: A WebTemplate
Return:
Errors:
Notes:
  1. Normally WebTemplate will automatically write an HTML header prior to writing anything else. This call inhibits that behavior.

 WebTemplate_reset_output

Description: Reset output flags and values
Syntax: int WebTemplate_reset_output(WebTemplate W)
Arguments:
W: A WebTemplate
Return:
Errors:
Notes:
  1. This clears any output cookies and header flags.
  2. It allows persistant cgi programs to setup for a new page.

Form and cookie API

The template package includes some convenience routines for managing cookies and parsing form data.

Parameters, whether from a form or the QUERY_STRING, consist of name and value pairs. Both the names and values are strings. A name may appear without a value. A name may appear more than once and thus acquire multiple values. No distinction is made between parameters acquired from forms or from QUERY_STRING arguments, except that the form values are processed first.

Cookies, received and sent with headers, are also name and value pairs.

In addition, the template system stores the REMOTE_USER environment variable, set by the web server on authenticated requests, in the global variable remote_user.

 WebTemplate_get_args

Description: Load the form and request arguments (parameters)
Syntax: void WebTemplate_get_args(WebTemplate W)
Arguments:
W: A WebTemplate
Return:
Errors:
Notes:
  1. Processes arguments from:
    1. form post data;
    2. QUERY_STRING parameters.
  2. You normally call this just once at the start of the cgi program. Persistent cgi programs would need to get new parameters for each request.

 WebTemplate_get_arg

Description: Get a parameter by name
Syntax: char* WebTemplate_get_arg(WebTemplate W, char* name)
Arguments:
W: A WebTemplate
name: Name of the parameter
Return: A string containing the parameter's value.
Errors:
Notes:
  1. Returns an empty string, if the parameter was specified without a value.
  2. Returns NULL if the parameter was not specified
  3. If the parameter has multiple values, the first encountered will be returned.
  4. You are responsible for freeing the returned string

 WebTemplate_get_arg_list

Description: Get a multivalued parameter by name
Syntax: char** WebTemplate_get_arg_list(WebTemplate W, char* name)
Arguments:
W: A WebTemplate
name: Name of the parameter
Return: A null-terminated list of strings containing the parameter's values.
Errors:
Notes:
  1. Returns NULL if the parameter was not specified
  2. Returns an empty string (or strings), if the parameter was specified without a value.
  3. You are responsible for freeing the list and each string.
  4. You may use the provided function WebTemplate_free_arg_list to do that.

 WebTemplate_free_arg_list

Description: Free a parameter list
Syntax: void WebTemplate_free_arg_list(char** list)
Arguments:
list: List returned by WebTemplate_get_arg_list
Return:
Errors:
Notes:
  1. This frees the list and all the strings

 WebTemplate_get_next_arg

Description: Get a parameter's name and value by number
Syntax: char* WebTemplate_get_next_arg(WebTemplate W, int* n, char** value)
Arguments:
W: A WebTemplate
n: Pointer to a parameter index
value: Receives the parameter's value
Return: A string containing the n'th parameter's name
Errors:
Notes:
  1. Returns NULL if the index is out of range
  2. This function allows the caller to step through all parameters.
  3. The index, n, must be initialized by the caller. It will be incremented by one on each call.
  4. The first parameter is zero
  5. value will receive the n'th parameter's value, or NULL if the parameter had no value.
  6. You are responsible for freeing the returned strings

 WebTemplate_get_octet_arg

Description: Get a multi-part form value
Syntax: int WebTemplate_get_octet_arg(WebTemplate W, char* name, void** value, size_t* len, char** type, char** Vfilename')
Arguments:
W: A WebTemplate
name: Name of the parameter
value: Receives a pointer to the parameter's value
len: Receives the length of the value
type: Receives the Content-type of the parameter
filename: Receives the filename of the parameter
Return: non-zero if the parameter exists; zero if not
Errors:
Notes:
  1. This function is used to retrieve data from a multi-part form submission.
  2. Expecting that thses data may be very large, the returned value is a reference to internal data. It is not copied. You must not free the value.
  3. If the type and filename are not null they will recieve copies the the form's type and filename fields.
  4. You are responsible for freeing the type and filename

 WebTemplate_html2text

Description: Convert html to text
Syntax: char* WebTemplate_html2text(char* string)
Arguments:
string: A html-encoded string
Return: A string containing the decoded input
Errors:
Notes:
  1. This function will convert standard html encoded strings to plain text.
  2. You are responsible for freeing the returned string

 WebTemplate_text2html

Description: Convert text to html
Syntax: char* WebTemplate_text2html(char* string)
Arguments:
string: A string to convert
Return: The encoded string
Errors:
Notes:
  1. The encoded string will have these substitutions:

    inout
    "&quot;
    <&lt;
    >&gt;
    &&amp;

  2. This function removes html commands from a string
  3. You are responsible for freeing the returned string

 WebTemplate_get_cookie

Description: Get a cookie's value
Syntax: char* WebTemplate_get_cookie(WebTemplate W, char* name)
Arguments:
W: A WebTemplate
name: Name of the cookie
Return: A string containing the parameter's value.
Errors:
Notes:
  1. Returns NULL if the cookie was not sent with the request.
  2. You are responsible for freeing the returned string

 WebTemplate_set_cookie

Description: Set a cookie's value
Syntax: void WebTemplate_set_cookie(WebTemplate W, char* name, char* value, time_t V'expires, char* domain, char* path, int secure)
Arguments:
W: A WebTemplate
name: Name of the cookie
value: Value of the cookie
expires: Expiration time of the cookie, may be zero
path: Path attribute of the cookie, may be null
domain: Domain attribute of the cookie, may be null
secure: Non-zero to set the cookie's secure flag
Return:
Errors:
Notes:
  1. Adds a cookie to the output page. The cookies are written when the header is written.

 Factorials

Assume two template files:

page.tpl 

 NOTE
   Comments in this file are delimited by 'NOTE' and 'ENDNOTE'
 ENDNOTE
 <html>
 <head>
 <title>{TITLE}</title>
 </head>
 <body>
 {BODY}
 </body>
 </html>

list.tpl 

 # comments in this file are identified by leading '#'

 <h1>{TITLE}</h1>
 <p>
 <table colsep=3>
 <tr><td align=right>n</td><td align=right>n!</td></tr>
  <!-- BEGIN DYNAMIC BLOCK: num -->
    <tr><td align=right>{N}</td><td align=right>{NFACT}</td></tr>
  <!-- END DYNAMIC BLOCK: num -->
 </table>

This program 

/* Show factorials */


main()
{
   WebTemplate W;
   int n;
   int f = 1;
   char txt[12];

   /* Initialize */
   W = newWebTemplate();

   /* Write the headers */
   WebTemplate_header(W);

   /* Load the two templates */
   WebTemplate_set_comments(W, "NOTE", "ENDNOTE");
   WebTemplate_get_by_name(W, "page", "page.tpl");
   WebTemplate_set_comments(W, "#", NULL);
   WebTemplate_get_by_name(W, "list", "list.tpl");

   /* Set the title */
   WebTemplate_assign(W, "TITLE", "10 factorials");

   /* Make a line for each number */
   for (n=1;n<11;n++) {
     f = n * f;
     sprintf(txt,"%d",n);
     WebTemplate_assign(W, "N", txt);
     sprintf(txt,"%d",f);
     WebTemplate_assign(W, "NFACT", txt);
     WebTemplate_parse_dynamic(W, "list.num");
   }

   /* Make the body of the page */
   WebTemplate_parse(W, "BODY", "list");

   /* Make the page */
   WebTemplate_parse(W, "PAGE", "page");
 
   /* Write the page */
   WebTemplate_write(W, "PAGE");
   
   exit (0);
}

produces this page:

10 factorials

nn!
11
22
36
424
5120
6720
75040
840320
9362880
103628800

Procedures

Examples