Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Template::Declare::TagUser Contributed Perl DocumentTemplate::Declare::Tags(3)

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.

perl v5.32.1			  2014-12-12	    Template::Declare::Tags(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS AND SUBROUTINES | VARIABLES | SEE ALSO | AUTHORS | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Template::Declare::Tags&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help