/ 
XML-XPathScript-2.00
River stage one • 1 direct dependent • 1 total dependent
/ XML::XPathScript::Template

NAME

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

VERSION

version 2.00

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, $template and $XML::XPathScript::trans.

METHODS

new

$template = XML::XPathScript::Template->new

Creates and returns a new, empty template.

set

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

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

Thank to the magic of overloading, using the $template as a code reference acts as a shortcut to set.

Example:

$template->set( 'foo' => { pre => '<a>', post => '</a>' } );
# or, if you prefer,
$template->( '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 / ] );

import_template

$template->import_template( $other_template )

Imports another template into the current one.

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' );
                        
# also modifies 'foo'
$template->set( 'bar' => { pre => '<u>' } );

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 );
%>

AUTHORS

  • Yanick Champoux <yanick@cpan.org>

  • Dominique Quatravaux <domq@cpan.org>

  • Matt Sergeant <matt@sergeant.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019, 2018, 2008, 2007 by Matt Sergeant.

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