NAME

XML::XSS::Template - XML::XSS templates

VERSION

version 0.1.3

SYNOPSIS

    use XML::XSS;

    my $xss = XML::XSS->new;

    $xss.'chapter'.'content' *= xsst q{
        <%~ title %>
        <%~ para %>
        <%~ note %>
    };

DESCRIPTION

XML::XSS::Template provides a templating markup language to ease the writing of rules for XML::XSS stylesheet rules. So that the style

    $xss.'chapter'.'content' *= sub {
        my ( $r, $node, $args ) = @_;
        my $output;

        $output .= $r->render( $node->findnodes( 'title' ) );

        $output .= $r->render( $node->findnodes( 'para' ) );

        if ( my @notes = $node->findnodes('note') ) {
            $output .= '<div class="notes">'
                    .  $r->render( @notes )
                    .  '</div>';
        }

        return $output;
    };

can be written

    $xss.'chapter'.'content' *= xsst q{
        <%~ title %>
        <%~ para %>

        <% if ( my  @notes = $node->findnodes('note') ) { %>
            <div class="notes">
                <%= $r->render( @notes ) %>
            </div>
        <% } %>
    };

TEMPLATE SYNTAX

The template directives are surrounded by '<%', '%>' delimiters. An optional dash can be squeezed in ('<-%', '%->'), which will cause all preceding or following whitespaces (including carriage returns) to be squished from the rendered document. This is useful to keep a stylesheet readable without generating transformed document with many whitespace gaps. The dash can be added independently to the right and left delimiter.

For example

    <h1>
        <-%@ /doc/title %->
    </h1>

will be rendered as

    <h1>A Tale of Two Cities</h1>

As an empty directive is an no-op, one can take advantage of it and use '<-%%->' as a magic template compacter.

Template Directives

<% %>

Evaluates the code enclosed without printing anything.

Example:

    <% my $now = localtime %>

To make the directive output something, simply print it.

    <% print "oooh, shiny" if $thingy->albedo_index > 50  %>

To create a loop in your template, use two directives to wrap the opening and closing pieces of code:

    <% for my $item ( @shopping_list ) { %>
        <p>I need a <%= $item %>.</p>
    <% } %>

<%= %>

Evaluates the enclosed code and prints its result.

    Author: <%= 'Hi ' + $name %>

<%# %>

Comments out the enclosed text, which will neither be executed or show in the rendered document.

<%~ $xpath %>

Takes the XPath expression, applies it on the current node and renders the resulting nodes. Equivalent of doing

    <%= $r->render( $node->findnodes( $xpath ), $args ) %>

Example:

    $xss->set( chapter => { content => <<'END_CONTENT' } );
        <%~ title %>   <%# process the title node %>
        <%~ para %>    <%# ... and then the paragraphs %>
        <%~ note %>    <%# ... and the notes %>
    END_CONTENT

<%@ $xpath %>

Takes the XPath expression and prints its value. Equivalent of doing

    <%= $node->findvalue( $xpath ) %>

EXPORTED FUNCTIONS

xsst( $template )

Takes the template given as a string and convert it as a XML::XSS::Template object ready to be used by a style attribute of the stylesheet.

    my $template = xsst q{
        <div>
            <h2>List of stuff</h2>
            <%~ item %>
        </div>
    };

    $xss->set( list => { content => $template } );

From the point of view of the stylesheet, the template object created by xsst is just another coderef, and will be passed the usual rendering node, xml node and option hashref arguments. For convenience, those are already made available as $r, $node and $args.

    my $template = xstt q{
        <h2><%= $r->stylesheet->stash->{section_nbr}++ %>. <%~ title %></h2>
        <% for my $child ( $node->childNodes ) { %>
            do something...
        <% } %>
    };

ATTRIBUTES

template

The original template string.

code

The code generated out of the original template, as a string.

    my $template = xsst q{ Hello <%= $r->stylesheet->stash->{name} %> };
    print $template->code;

AUTHOR

  Yanick Champoux <yanick@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Yanick Champoux.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm XML::XSS

perl -MCPAN -e shell
install XML::XSS