cgi/template.h File Reference

Template handling functions. More...

#include <stdio.h>
#include <cgi/html_tree.h>
#include <cgi/html_utils.h>

Data Structures

struct s_section

Template/template section structure. More...

Typedefs

typedef struct s_section t_template

Template.

typedef struct s_section t_tpl_section

Template section.

typedef void(* t_command_processor )(t_tpl_section *section, TAG *node, char **text, char **tagstart, char **tagend, char *param)

Template command processor.

Functions

t_template * template_create (char *filename)

Create template from file.

t_tpl_section * template_find_section (t_template *tpl, char *name)

Find template section.

void template_free (t_tpl_section *section)

Delete template.

void template_insert (t_tpl_section *dest, char *where, t_tpl_section *src)

Insert template or template section.

void template_opt (t_tpl_section *section, char *name, long selection)

Set template/template section option.

void template_out (t_template *tpl, FILE *out)

Output template.

void template_section_out (t_tpl_section *tpl)

Output template section.

void template_set (t_tpl_section *section, char *name, char *fmt,...)

Set value for placeholder.

void free_template_command_processors (void)

Unregister all command processors.

void register_template_command_processor (char *cmd, t_command_processor processor)

Register command processor.

void unregister_template_command_processor (char *cmd)

Unregister command processor with given name.

Detailed Description

Template handling functions.

Author:: Vladimir Pavluk, 2006-2007

Templates are plain HTML files with additional tag support, including various placeholders/options for data or data processing commands.

Short reference on templates (case doesn't matter):

Section:

 <SECTION name="...">...</SECTION>

Placeholder:

 {name}

Option:

 {name:value1|value2|...|valueN}

Command:

 {#name:parameter}

Nesting examples:

 {#htmlencode:{text}}

 {#strip_tags:{text}}

 {login_state:Hello, {username}!|Not logged in!}

 {#include:{login_state:unlogged_menu.html|logged_menu.html}}

Typedef Documentation

typedef void(* t_command_processor)(t_tpl_section *section, TAG *node, char **text, char **tagstart, char **tagend, char *param)

Template command processor.

Template command processor type.

Parameters:

	section	section where the command is found.
	node	DOM node where the command is found.
	text	pointer to pointer to the parsed text. When changed, the text is replaced.
	tagstart	pointer to pointer to the start of the command tag. Don't forget to change it appropriately if you change text.
	tagend	pointer to pointer to the end of command tag. Don't forget to change it appropriately if you change text. Also, parsing continues from this point after the command is processed so if you want to re-parse the command result, set it to be the same as tagstart.
	param	command parameter.

typedef struct s_section t_template

Template.

Template type.

typedef struct s_section t_tpl_section

Template section.

Template section type.

Function Documentation

void free_template_command_processors ( void )

Unregister all command processors.

Unregisters all command processors and frees command processors table.

void register_template_command_processor	(	char *	cmd,
		t_command_processor	processor
	)

Register command processor.

Registers custom command processor function.

Commands are found in {#name:param} tags, where name is the command name, and param will be passed as a parameter to command processor.

Default command set incudes following comands:

{#include:file} - includes specified file as sub-template. The path is relative to template file;
{#strip_tags:text} - strips HTML tags from text;
{#htmlencode:text} - replaces characters with their HTML entities.

Parameters:

	cmd	command name.
	processor	processing function.

t_template* template_create ( char * filename )

Create template from file.

Creates template from file with given name.

Parameters:

filename

file to parse. If filename is NULL, the standard input is parsed.

Returns:: parsed template on success, or NULL if failed.

t_tpl_section* template_find_section	(	t_template *	tpl,
		char *	name
	)

Find template section.

Searches for template section with given name.

Template sections are defined in HTML templates using <section name="..."> tag. You can use these sections for conditional output, for tables creation, etc.

The following example will create a table with multiple rows each containing two data entries - "name" and "value": Template:

 ...
 <TABLE border="1">
 <TR><TH>Name</TH><TH>Value</TH></TR>
 <SECTION name="row">
 <TR><TD>{name}</TD><TD>{value}</TD></TR>
 </SECTION>
 </TABLE>
 ...

C program:

 ...
 t_tpl_section *s;
 ...
 s = template_find_section(tpl, "row");
 ...
 for(i = 0; i < ...; i ++)
 {
    template_set(s, "name", ...);
    template_set(s, "value", ...);
    template_section_out(s);
 }
 ...

Parameters:

	tpl	template to search in.
	name	section name.

Returns:: found section upon succes, or NULL if section couldn't be found.

See also:

template_section_out(t_tpl_section *)

template_create(char *)

template_insert(t_tpl_section *, char *, t_tpl_section *)

void template_free ( t_tpl_section * tpl )

Delete template.

Deletes template and frees memory associated with it.

Attention:: WARNING: Don't delete sections found by template_find_section function. They are deleted automatically, when the whole template is freed.

Parameters:

tpl

template to delete.

See also:: template_create(char *)

void template_insert	(	t_tpl_section *	dest,
		char *	where,
		t_tpl_section *	src
	)

Insert template or template section.

Inserts template or template section into specified placeholder.

Template placeholders are defined using curly brackets like {name}.

Parameters:

	dest	template to insert to.
	where	placeholder name.
	src	template/section to insert.

See also:

template_section_out(t_tpl_section *)

template_find_section(t_template *, char *)

template_opt(t_tpl_section *, char *, long)

template_set(t_tpl_section *, char *, char *, ...)

template_create(char *)

void template_opt	(	t_tpl_section *	section,
		char *	name,
		long	option
	)

Set template/template section option.

Sets template or section option value.

Options are defined using following tag: {name:opt1|opt2|...|optN}. When you set template option number, the whole tag is replaced by the corresponding value. Option number is normalized to number of options using modulus operator.

Note, that nesting placeholders, commands, and even other options as option values is supported. But don't go mad on this, as multi-level nested options placeholders and commands are hard to read.

The following example will create a table with two interleaved rows colors. Note, that setting 'color' option you set background to one color and text to opposite at once. Template:

 ...
 <TABLE border="1">
 <TR><TH>Name</TH><TH>Value</TH></TR>
 <SECTION name="row">
 <TR style="background-color:{color:black|white}; color:{color:white|black}"><TD>Name should be here</TD><TD>Place value here</TD></TR>
 </SECTION>
 </TABLE>
 ...

C program:

 ...
 t_tpl_section *s;
 ...
 s = template_find_section(tpl, "row");
 ...
 for(i = 0; i < ...; i ++)
 {
    template_opt(s, "color", i);
    template_section_out(s);
 }
 ...

Parameters:

	section	template or template section.
	name	option name.
	option	option value.

See also:

template_section_out(t_tpl_section *)

template_set(t_tpl_section *, char *, char *, ...)

template_insert(t_tpl_section *, char *, t_tpl_section *)

template_create(char *)

void template_out	(	t_tpl_section *	tpl,
		FILE *	out
	)

Output template.

Outputs template to specified output stream.

If output stream is NULL, stdout is used.

Parameters:

	tpl	template to output.
	out	output stream.

See also:: template_section_out(t_tpl_section *)
template_create(char *)

void template_section_out ( t_tpl_section * tpl )

Output template section.

Inserts parsed template section into template.

The section is inserted into the place it is located in the template.

One template section can be inserted multiple times. This will result in multiple subsequent occurences of given section in resulting output.

Parameters:

tpl

template to output.

See also:

template_section_out(t_tpl_section *)

template_find_section(t_template *, char *)

template_create(char *)

void template_set	(	t_tpl_section *	section,
		char *	name,
		char *	fmt,
			...
	)

Set value for placeholder.

Sets template or template section placeholder value.

Template placeholders are defined using curly brackets like {name}. You can nest placeholder to another placeholder, command, or option. Don't go mad on this, as multi-level nested options placeholders and commands are hard to read.

Parameters:

	section	template or section.
	name	placeholder name.
	fmt	format. The format specs are the same as for *printf functions family.

See also:

template_section_out(t_tpl_section *)

template_find_section(t_template *, char *)

template_opt(t_tpl_section *, char *, long)

template_insert(t_tpl_section *, char *,t_tpl_section *)

template_create(char *)

void unregister_template_command_processor ( char * cmd )

Unregister command processor with given name.

Removes command processor with given name from command processors table.

Parameters:

cmd

command name.


Data Structures
struct	s_section
	Template/template section structure. More...
Typedefs
typedef struct s_section	t_template
	Template.
typedef struct s_section	t_tpl_section
	Template section.
typedef void(*	t_command_processor )(t_tpl_section section, TAG node, char text, char tagstart, char *tagend, char param)
	Template command processor.
Functions
t_template *	template_create (char *filename)
	Create template from file.
t_tpl_section *	template_find_section (t_template tpl, char name)
	Find template section.
void	template_free (t_tpl_section *section)
	Delete template.
void	template_insert (t_tpl_section dest, char where, t_tpl_section *src)
	Insert template or template section.
void	template_opt (t_tpl_section section, char name, long selection)
	Set template/template section option.
void	template_out (t_template tpl, FILE out)
	Output template.
void	template_section_out (t_tpl_section *tpl)
	Output template section.
void	template_set (t_tpl_section section, char name, char *fmt,...)
	Set value for placeholder.
void	free_template_command_processors (void)
	Unregister all command processors.
void	register_template_command_processor (char *cmd, t_command_processor processor)
	Register command processor.
void	unregister_template_command_processor (char *cmd)
	Unregister command processor with given name.