NAME
Cindy - use unmodified XML or HTML documents as templates.
SYNOPSIS
use Cindy;
my $doc = get_html_doc('cindy.html');
my $data = get_xml_doc('cindy.xml');
my $descriptions = parse_cis('cindy.cjs');
my $out = inject($data, $doc, $descriptions);
print $out->toStringHTML();DESCRIPTION
Cindy does Content INjection into XML and HTML documents. The positions for the modifications as well as for the data are identified by xpath expressions. These are kept in a seperate file called a Content inJection Sheet. The syntax of this CJS file (the ending .cis implies a japanese charset in the apache defaults) remotely resembles CSS. The actions for content modification are those implemented by TAL.
CJS SYNTAX
The syntax for content injection sheets is pretty simple. In most cases it is
<source path> <action> <target path> ;The source and target path are xpath expressions. The action describes how to move the data. The whitespace before the terminating ; is required, since xpath expressions may end with a colon. The xpath expressions must not contain whitespaces. If the syntax for an action is different this is documented with the action.
Everything from a ; to the end of the line is ignored and can be used for comments.
CJS ACTIONS
Actions locate data and document nodes and perform an operation that creates a modified document.
All source paths for actions other than repeat should locate one node. Otherwise the action is executed for all source nodes on the same target. The action is executed for all target nodes.
Actions are executed in the order they appear in the sheet. Subsheets are executed after the enclosing sheet.
The following example illustrates the effect of exectuion order. If a target node is omitted, an action that changes its content will not have any effect.
true() omit-tag <target> ;
<source> content <target> ;So the above is not equvalent to the replace action.
Execution matches document nodes and then data nodes. Thereafter the actions are executed. Since execution of a repeat action copies the document node for each repetition, changes to this node done after the repeat are lost. At last this is recursively done for all subsheets.
As an unfortunate consequence matches on subsheet doc nodes do see the changes done by actions from enclosing sheets. This behaviour will hopefully change in future releases.
content
All child nodes of the target node are replaced by child nodes of the source node. This means that the text of the source tag with all tags it contains replaces the content of the target tag. If data is not a node, it is treated as text.
replace
The child nodes of the source node replace the target node and all its content. THis means that the target tag including any content is replaced by the content of the subtag. This is equivalent to
<source> content <target> ;
true() omit-tag <target> ;omit-tag
The source node is used as a condition. If it exists and if its text content evaluates to true the target node is replaced by its children. This means that if the source tag exists and its content is not '' or 0 the target tag is removed while its content remains.
comment
The source nodes comntent is move into a comment node. This comment node is appended to the children of the target node. This can be useful for debugging and enables injection of SSI directives.
attribute
The syntax has an additional field atname
<source> attribute <target> <atname> ;that holds the name of the attribute. If the source node exists, its content replaces or sets the value of the atname attribute of the target node. If the source node does not exist the attribute atname is removed from the target node.
condition
The source node is used as a condition. If it exists and if its text content evaluates to true nothing is done. Otherwise the target node and its children are removed. This means that the target tag is removed if the source tage does not exist or contains '', 0 or 0.0 whileit is left untouched otherwise.
repeat
The repeat action is the CJS equivalent of a template engines loop. For each match of the source path the source node and the target node are used as root nodes for a sequence of actions. The syntax is
<source> repeat <target> [condition] {
<actions>
} ;The optional condition is an xpath expression that is run in the context of the root node of a temporary document fragment. The fragment has two children, DOC and DATA which hold a subtree from a repeat doc respective data match. Only those combinations where the condition evaluates to true are used, all others are discarded.
Note that the repeat condition is an EXPERIMENTAL feature, it may well change.
AUTHOR
Joachim Zobel <jz-2008@heute-morgen.de>
SEE ALSO
See Cindy/Sheet.pm for the RecDescent grammar for content injection sheets. The usage of Cindy through apache is implemented in Cindy::Apache2. This is distributed seperately (see http://search.cpan.org/%7ejzobel/Cindy-Apache2/) since it introduces additional dependencies.