Declaring templates

    template select_list => sub {
        my $self = shift;
        select {
            option { $_ } for @_;
        }
    };

Declares a template in the current package. The first argument to the template subroutine will always be a "Template::Declare" object. Subsequent arguments will be all those passed to "show()". For example, to use the above example to output a select list of colors, you'd call it like so:

    Template::Declare->show('select_list', qw(red yellow green purple));

You can use any URL-legal characters in the template name; "Template::Declare" will encode the template as a Perl subroutine and stash it where "show()" can find it.

(Did you know that you can have characters like ":" and "/" in your Perl subroutine names? The easy way to get at them is with "can").

private template TEMPLATENAME => sub { 'Implementation' };

    private template select_list => sub {
        my $self = shift;
        select {
            option { $_ } for @_;
        }
    };

Declares that a template isn't available to be called directly from client code. The resulting template can instead only be called from the package in which it's created.

Showing templates

    show( main => { user => 'Bob' } );

Displays templates. The first argument is the name of the template to be displayed. Any additional arguments will be passed directly to the template.

"show" can either be called with a template name or a package/object and a template. (It's both functional and OO.)

If called from within a Template::Declare subclass, then private templates are accessible and visible. If called from something that isn't a Template::Declare, only public templates will be visible.

From the outside world, users can either call "Template::Declare->show()", "show()" exported from Template::Declare::Tags or "Template::Declare::Tags::show()" directly to render a publicly visible template.

Private templates may only be called from within the "Template::Declare" package.

show_page

    show_page( main => { user => 'Bob' } );

Like "show()", but does not dispatch to private templates. It's used internally by "show()" when when that method is called from outside a template class.

Attributes

    attr { src => 'logo.png' };

Specifies attributes for the element tag in which it appears. For example, to add a class and ID to an HTML paragraph:

    p {
       attr {
           class => 'greeting text',
           id    => 'welcome',
       };
       'This is a welcoming paragraph';
    }

ATTR is VALUE

Attributes can also be specified by using "is", as in

    p {
       class is 'greeting text';
       id    is 'welcome';
       'This is a welcoming paragraph';
    }

A few tricks work for 'is':

    http_equiv is 'foo'; # => http-equiv="foo"
    xml__lang is 'foo';  # => xml:lang="foo"

So double underscore replaced with colon and single underscore with dash.

with

    with ( id => 'greeting', class => 'foo' ),
        p { 'Hello, World wide web' };

An alternative way to specify attributes for a tag, just for variation. The standard way to do the same as this example using "attr" is:

    p { attr { id => 'greeting', class => 'foo' }
        'Hello, World wide web' };

Displaying text and raw data

    p { outs 'Grettings & welcome pyoonie hyoomon.' }

HTML-encodes its arguments and appends them to "Template::Declare"'s output buffer. This is similar to simply returning a string from a tag function call, but is occasionally useful when you need to output a mix of things, as in:

    p { outs 'hello'; em { 'world' } }

outs_raw STUFF

   p { outs_raw "That's what <em>I'm</em> talking about!' }

Appends its arguments to "Template::Declare"'s output buffer without HTML escaping.

Installing tags and wrapping stuff

    install_tag video => 'Template::Declare::TagSet::HTML';

Sets up TAGNAME as a tag that can be used in user templates. TAGSET is an instance of a subclass for Template::Declare::TagSet.

smart_tag_wrapper

    # create a tag that has access to the arguments set with L</with>.
    sub sample_smart_tag (&) {
        my $code = shift;

        smart_tag_wrapper {
            my %args = @_; # set using 'with'
            outs( 'keys: ' . join( ', ', sort keys %args) . "\n" );
            $code->();
        };
    }

    # use it
    with ( foo => 'bar', baz => 'bundy' ), sample_smart_tag {
        outs( "Hello, World!\n" );
    };

The output would be

    keys: baz, foo
    Hello, World!

The smart tag wrapper allows you to create code that has access to the attribute arguments specified via "with". It passes those arguments in to the wrapped code in @_. It also takes care of putting the output in the right place and tidying up after itself. This might be useful to change the behavior of a template based on attributes passed to "with".

create_wrapper WRAPPERNAME => sub { 'Implementation' };

    create_wrapper basics => sub {
        my $code = shift;
        html {
            head { title { 'Welcome' } };
            body { $code->() }
        }
    };

"create_wrapper" declares a wrapper subroutine that can be called like a tag sub, but can optionally take arguments to be passed to the wrapper sub. For example, if you wanted to wrap all of the output of a template in the usual HTML headers and footers, you can do something like this:

    package MyApp::Templates;
    use Template::Declare::Tags;
    use base 'Template::Declare';

    BEGIN {
        create_wrapper wrap => sub {
            my $code = shift;
            my %params = @_;
            html {
                head { title { outs "Hello, $params{user}!"} };
                body {
                    $code->();
                    div { outs 'This is the end, my friend' };
                };
            }
        };
    }

    template inner => sub {
        wrap {
            h1 { outs "Hello, Jesse, s'up?" };
        } user => 'Jesse';
    };

Note how the "wrap" wrapper function is available for calling after it has been declared in a "BEGIN" block. Also note how you can pass arguments to the function after the closing brace (you don't need a comma there!).

The output from the "inner" template will look something like this:

 <html>
  <head>
   <title>Hello, Jesse!</title>
  </head>
  <body>
   <h1>Hello, Jesse, s&#39;up?</h1>
   <div>This is the end, my friend</div>
  </body>
 </html>

Helpers

    xml_decl { 'xml', version => '1.0' };

Emits an XML declaration. For example:

    xml_decl { 'xml', version => '1.0' };
    xml_decl { 'xml-stylesheet',  href => "chrome://global/skin/", type => "text/css" };

Produces:

 <?xml version="1.0"?>
 <?xml-stylesheet href="chrome://global/skin/" type="text/css"?>

current_template

    my $path = current_template();

Returns the absolute path of the current template

current_base_path

    my $path = current_base_path();

Returns the absolute base path of the current template

under

"under" is a helper function providing semantic sugar for the "mix" method of Template::Declare.

setting

"setting" is a helper function providing semantic sugar for the "mix" method of Template::Declare.