NAME

XML::XPathScript::Template - XML::XPathScript transformation template

SYNOPSIS

<%
    $t->set( 'important' => { 'pre' => '<blink>', 
                              'post' => '</blink>',
                              'prechild' => '<u>',
                              'postchild' => '</u>',
                              } );

    # urgent and annoying share the 'pre' and 'post'
    # of important
    $t->copy( 'important' => [ qw/ urgent annoying / ], 
                [ qw/ pre post / ],        );

    # redHot is a synonym of important
    $t->alias( 'important' => 'redHot' );

 %>
 <%= apply_templates() %>

DESCRIPTION

A stylesheet's template defines the transformations and actions that are performed on the tags of a document as they are processed.

The template of a stylesheet can be accessed via variables $t and $template.

METHODS

new

$template = new XML::XPathScript::Template;

Creates and returns a new, empty template.

set

$template->( $tag, \%attributes )
$template->set_template( \@tags , \%attributes )

Update the $tag or @tags in the template with the given %attributes.

Example:

$template->set( 'foo' => { pre => '<a>', post => '</a>' } );

copy

$template->copy( $original_tag, $copy_tag );
$template->copy( $original_tag, $copy_tag, \@attributes );
$template->copy( $original_tag, \@copy_tags );
$template->copy( $original_tag, \@copy_tags, \@attributes );

Copies all attributes (or a subset of them if @attributes is given) of $original_tag to $copy_tag.

Note that subsequent modifications of the original tag will not affect the copies. To bind several tags to the same behavior, see alias.

Example:

# copy the attributes 'pre' and 'post' of important 
# to 'urgent' and 'redHot'
$template->copy( 'important' => [ qw/ urgent redHot / ], 
                    [ qw/ pre post / ] );

alias

$template->alias( $original_tag => $alias_tag );
$template->alias( $original_tag => \@alias_tags );

Makes the target tags aliases to the original tag. Further modifications that will be done on any of these tags will be reflected on all others.

Example:

$template->alias( 'foo' => 'bar' );
$template->set( 'bar' => { pre => '<u>' } );  # also modify 'foo'

is_alias

@aliases = $template->is_alias( $tag )

Returns all tags that are aliases to $tag.

unalias

$template->unalias( $tag )

Unmerge $tag of its aliases, if it has any. Further modifications to $tag will not affect the erstwhile aliases, and vice versa.

Example:

$template->alias( 'foo' => [ qw/ bar baz / ] );
$template->set( 'foo' => { pre => '<a>' } );    # affects foo, bar and baz
$template->unalias( 'bar' );
$template->set( 'bar' => { pre => '<c>' } );    # affects only bar
$template->set( 'baz' => { pre => '<b>' } );    # affects foo and baz

clear

$template->clear()
$template->clear( \@tags )

Delete all tags, or those given by @tags, from the template.

Example:

$template->clear([ 'foo', 'bar' ]);

dump

$template->dump()
$template->dump( @tags )

Returns a pretty-printed dump of the templates. If @tags are specified, only return their templates.

Example:

<%= $template->dump( 'foo' ) %>

# will yield something like

# $template = {
#                'foo' => {
#                            'post' => '</bar>',
#                            'pre' => '<bar>'
#                        }
#             };

namespace

my $subtemplate = $template->namespace( $uri );

Returns the sub-template associated to the namespace defined by $uri.

Example:

$template->set( 'foo' => { 'pre' => 'within default namespace' } );
my $subtemplate = $template->namespace( 'http://www.www3c.org/blah/' );
$subtemplate->set( 'foo' => { 'pre' => "within 'blah' namespace" } );

resolve

$tag = $template->resolve( $namespace, $tagname );
$tag = $template->resolve( $tagname );

Returns the tag object within $template that matches $namespace and $tagname best. The returned match is the first one met in the following list:

• $namespace:$tagname

• $namespace:*

• $tagname

• *

• undef

Example:

$template->set( foo => { pre => 'a' } );
$template->set( '*' => { pre => 'b' } );
$template->namespace( 'http://blah' )->set( foo => { pre => 'c' } );
$template->namespace( 'http://blah' )->set( '*' => { pre => 'd' } );

$template->resolve( 'foo' )->get( 'pre' );  # returns 'a'
$template->resolve( 'baz' )->get( 'pre' );  # returns 'b'
$template->resolve( 'http://meeh', 'foo' )->get( 'pre' );  # returns 'a'
$template->resolve( 'http://blah', 'foo' )->get( 'pre' );  # returns 'c'
$template->resolve( 'http://blah', 'baz' )->get( 'pre' );  # returns 'd'

BACKWARD COMPATIBILITY

Prior to version 1.0 of XML::XPathScript, the template of a stylesheet was not an object but a simple hash reference. Modifications to the template were done by manipulating the hash directly.

<%
    # pre-1.0 way of manipulating the template
    $t->{important}{pre}  = '<blink>';
    $t->{important}{post} = '</blink>';

    for my $tag ( qw/ urgent redHot / ) {
        for my $attr ( qw/ pre post / ) {
            $t->{$tag}{$attr} = $t->{important}{$attr};
        }
    }

    $t->{ alert } = $t->{ important };
%>

Don't tell anyone, but as an XML::XPathScript::Template is a blessed hash reference this way of doing things will still work. However, direct manipulation of the template's hash is deprecated. Instead, it is recommended to use the object's access methods.

<%
    # correct way to manipulate the template
    $t->set( important => { pre => '<blink>', 
                            post => '</blink>',
                            showtag => 1
                            } );

    $t->copy( important => [ qw/ urgent redHot / ], [ qw/ pre post / ] );

    $t->alias( important => alert );
%>

BUGS AND LIMITATIONS

There are no known bugs in this module.

Please report problems to Yanick Champoux <yanick@cpan.org>

Patches are welcome.

AUTHOR

Yanick Champoux (yanick@cpan.org)