---
name: "Template::Declare::Tags"
section: "3pm"
platform: "linux"
package: "libtemplate-declare-perl"
version: "0.47-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Template::Declare::Tags"
---

# Template::Declare::Tags(3pm)

Build and install XML Tag subroutines for Template::Declare

## NAME

Template::Declare::Tags - Build and install XML Tag subroutines for Template::Declare

## SYNOPSIS

```
    package MyApp::Templates;
    use base 'Template::Declare';
    use Template::Declare::Tags 'HTML';
    template main => sub {
        link {}
        table {
            row {
                cell { "Hello, world!" }
            }
        }
        img { attr { src => 'cat.gif' } }
        img { src is 'dog.gif' }
    };
```

Produces:

```
 <link />
 <table>
  <tr>
   <td>Hello, world!</td>
  </tr>
 </table>
 <img src="cat.gif" />
 <img src="dog.gif" />
```

Using XUL templates with a namespace:

```
    package MyApp::Templates;
    use base 'Template::Declare';
    use Template::Declare::Tags
        'XUL', HTML => { namespace => 'html' };
    template main => sub {
        groupbox {
            caption { attr { label => 'Colors' } }
            html::div { html::p { 'howdy!' } }
            html::br {}
        }
    };
```

Produces:

```
 <groupbox>
  <caption label="Colors" />
  <html:div>
   <html:p>howdy!</html:p>
  </html:div>
  <html:br></html:br>
 </groupbox>
```

## DESCRIPTION

`"Template::Declare::Tags"` is used to generate templates and install subroutines for tag sets into the calling namespace.

You can specify the tag sets to install by providing a list of tag modules in the `"use"` statement:

```
    use Template::Declare::Tags qw/ HTML XUL /;
```

By default, Template::Declare::Tags uses the tag set provided by Template::Declare::TagSet::HTML. So

```
    use Template::Declare::Tags;
```

is equivalent to

```
    use Template::Declare::Tags 'HTML';
```

Currently Template::Declare bundles the following tag sets: Template::Declare::TagSet::HTML, Template::Declare::TagSet::XUL, Template::Declare::TagSet::RDF, and Template::Declare::TagSet::RDF::EM.

You can specify your own tag set classes, as long as they subclass Template::Declare::TagSet and implement the corresponding methods (e.g. `"get_tag_list"`).

If you implement a custom tag set module named `"Template::Declare::TagSet::Foo"`, you can load it into a template module like so:

```
    use Template::Declare::Tags 'Foo';
```

If your tag set module is not under the Template::Declare::TagSet namespace, use the `"from"` option to load it. Fore example, if you created a tag set named `"MyTag::Foo"`, then you could load it like so:

```
    use Template::Declare::Tags Foo => { from => 'MyTag::Foo' };
```

XML namespaces are emulated by Perl packages. For example, to embed HTML tags within XUL using the `"html"` namespace:

```
    package MyApp::Templates;
    use base 'Template::Declare';
    use Template::Declare::Tags 'XUL', HTML => { namespace => 'html' };
    template main => sub {
        groupbox {
            caption { attr { label => 'Colors' } }
            html::div { html::p { 'howdy!' } }
            html::br {}
        }
    };
```

This will output:

```
 <groupbox>
  <caption label="Colors" />
  <html:div>
   <html:p>howdy!</html:p>
  </html:div>
  <html:br></html:br>
 </groupbox>
```

Behind the scenes, `"Template::Declare::Tags"` generates a Perl package named `"html"` and installs the HTML tag subroutines into that package. On the other hand, XUL tag subroutines are installed into the current package, namely, `"MyApp::Templates"` in the previous example.

There may be cases when you want to specify a different Perl package for a particular XML namespace. For instance, if the `"html"` Perl package has already been used for other purposes in your application and you don't want to install subs there and mess things up, use the `"package"` option to install them elsewhere:

```
    package MyApp::Templates;
    use base 'Template::Declare';
    use Template::Declare::Tags 'XUL', HTML => {
        namespace => 'htm',
        package   => 'MyHtml'
    };
    template main => sub {
        groupbox {
            caption { attr { label => 'Colors' } }
            MyHtml::div { MyHtml::p { 'howdy!' } }
            MyHtml::br {}
        }
    };
```

This code will generate something like the following:

```
 <groupbox>
  <caption label="Colors" />
  <htm:div>
   <htm:p>howdy!</htm:p>
  </htm:div>
  <htm:br></htm:br>
 </groupbox>
```

## METHODS AND SUBROUTINES

### Declaring templates

*template TEMPLATENAME =\> sub { 'Implementation' };*

```
    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 \[$template\_name or $template\_coderef\], args*

```
    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 HASH*

```
    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

*outs STUFF*

```
    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 TAGNAME, TAGSET*

```
    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 HASH*

```
    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.

## VARIABLES

- @Template::Declare::Tags::EXPORT

  Holds the names of the static subroutines exported by this class. Tag subroutines generated by tag sets, however, are not included here.

- @Template::Declare::Tags::TAG\_SUB\_LIST

  Contains the names of the tag subroutines generated from a tag set.

  Note that this array won't get cleared automatically before another `"use Template::Decalre::Tags"` statement.

  `@Template::Declare::Tags::TagSubs` is aliased to this variable for backward-compatibility.

- $Template::Declare::Tags::TAG\_NEST\_DEPTH

  Controls the indentation of the XML tags in the final outputs. For example, you can temporarily disable a tag's indentation by the following lines of code:

  ```
      body {
          pre {
            local $Template::Declare::Tags::TAG_NEST_DEPTH = 0;
            script { attr { src => 'foo.js' } }
          }
      }
  ```

  It generates

  ```
   <body>
    <pre>
   <script src="foo.js"></script>
    </pre>
   </body>
  ```

  Note that now the `"script"` tag has *no* indentation and we've got what we want. ;)

- $Template::Declare::Tags::SKIP\_XML\_ESCAPING

  Disables XML escape postprocessing entirely. Use at your own risk.

## SEE ALSO

Template::Declare::TagSet::HTML, Template::Declare::TagSet::XUL, Template::Declare.

## AUTHORS

Jesse Vincent \<jesse@bestpractical.com\>

Agent Zhang \<agentzh@yahoo.cn\>

## COPYRIGHT

Copyright 2006-2009 Best Practical Solutions, LLC.