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

FreeBSD Manual Pages

  
 
  

home | help
CGI::FormBuilder::TempUser:Contributed PerlCGI::FormBuilder::Template::Text(3)

NAME
       CGI::FormBuilder::Template::Text	- FormBuilder interface	to
       Text::Template

SYNOPSIS
	   my $form = CGI::FormBuilder->new(
			   fields   => \@fields,
			   template => {
			       type => 'Text',
			       template	=> 'form.tmpl',
			       variable	=> 'form',
			   }
		      );

DESCRIPTION
       This engine adapts FormBuilder to use "Text::Template". Usage is	very
       similar to Template Toolkit:

	   my $form = CGI::FormBuilder->new(
			   fields => \@fields,
			   template => {
			       type => 'Text',		 # use Text::Template
			       template	=> 'form.tmpl',
			   }
		      );

       The default options passed into "Text::Template->new()" with this
       calling form are:

	   TYPE	  => 'FILE'
	   SOURCE => 'form.tmpl'
	   DELIMITERS => ['<%','%>']

       As these	params are passed for you, your	template will look very
       similar to ones used by Template	Toolkit	and "HTML::Mason" (the
       Text::Template default delimiters are "{" and "}", but using
       alternative delimiters speeds it	up by about 25%, and the "<%" and "%>"
       delimiters are good, familiar-looking alternatives).

       The following methods are provided (usually only	used internally):

   engine
       Returns a reference to the "Text::Template" object

   prepare
       Returns a hash of all the fields	ready to be rendered.

   render
       Uses the	prepared hash and expands the template,	returning a string of
       HTML.

TEMPLATES
	   <% $jshead %>  -  JavaScript	to stick in <head>
	   <% $title  %>  -  The <title> of the	HTML form
	   <% $start  %>  -  Opening <form> tag	and internal fields
	   <% $submit %>  -  The submit	button(s)
	   <% $reset  %>  -  The reset button
	   <% $end    %>  -  Closing </form> tag
	   <% $fields %>  -  List of fields
	   <% $field  %>  -  Hash of fields (for lookup	by name)

       Note that you refer to variables	with a preceding "$", just like	in
       Perl.  Like Template Toolkit, you can specify a variable	to place
       fields under:

	   my $form = CGI::FormBuilder->new(
	       fields => \@fields,
	       template	=> {
		    type => 'Text',
		    template =>	'form.tmpl',
		    variable =>	'form'
	       },
	   );

       Unlike Template Toolkit,	though,	these will not be placed in OO-style,
       dot-separated vars. Instead, a hash will	be created which you then
       reference:

	   <% $form{jshead} %>
	   <% $form{start}  %>
	   etc.

       And field data is in a hash-of-hashrefs format:

	   For a field named...	 The field data	is in...
	   --------------------	 -----------------------
	   job			 <% $form{field}{job}	%]
	   size			 <% $form{field}{size}	%]
	   email		 <% $form{field}{email}	%]

       Since "Text::Template" looks so much like Perl, you can access
       individual elements and create variables	like so:

	   <%
	       my $myfield = $form{field}{email};
	       $myfield->{label};      # text label
	       $myfield->{field};      # field input tag
	       $myfield->{value};      # first value
	       $myfield->{values};     # list of all values
	       $myfield->{options};    # list of all options
	       $myfield->{required};   # required flag
	       $myfield->{invalid};    # invalid flag
	       $myfield->{error};      # error string if invalid
	   %>

	   <%
	       for my $field (@{$form{fields}})	{
		   $OUT	.= "<tr>\n<td>"	. $field->{label} . "</td> <td>"
					. $field->{field} . "</td>\n<tr>";
	       }
	   %>

       In addition, when using the engine option, you supply an	existing
       Text::Template object or	a hash of parameters to	be passed to "new()".
       For example, you	can ask	for different delimiters yourself:

	   my $form = CGI::FormBuilder->new(
	       fields => \@fields,
	       template	=> {
		    type => 'Text',
		    template =>	'form.tmpl',
		    variable =>	'form',
		    engine   =>	{
		       DELIMITERS => [ '[@--', '--@]' ],
		    },
		    data => {
			 version => 1.23,
			 author	 => 'Fred Smith',
		    },
	       },
	   );

       If you pass a hash of parameters, you can override the "TYPE" and
       "SOURCE"	parameters, as well as any other "Text::Template" options. For
       example,	you can	pass in	a string template with "TYPE =>	STRING"
       instead of loading it from a file. You must specify both	"TYPE" and
       "SOURCE"	if doing so.  The good news is this is trivial:

	   my $form = CGI::FormBuilder->new(
	       fields => \@fields,
	       template	=> {
		    type => 'Text',
		    variable =>	'form',
		    engine   =>	{
			 TYPE => 'STRING',
			 SOURCE	=> $string,
			 DELIMITERS => [ '[@--', '--@]'	],
		    },
		    data => {
			 version => 1.23,
			 author	 => 'Fred Smith',
		    },
	       },
	   );

       If you get the crazy idea to let	users of your application pick the
       template	file (strongly discouraged) and	you're getting errors, look at
       the "Text::Template" documentation for the "UNTAINT" feature.

       Also, note that "Text::Template"'s "PREPEND => 'use strict;'" option is
       not recommended due to the dynamic nature for "FormBuilder".  If	you
       use it, then you'll have	to declare each	variable that "FormBuilder"
       puts into your template with "use vars qw($jshead' ... etc);"

       If you're really	stuck on this, though, a workaround is to say:

	   PREPEND => 'use strict; use vars qw(%form);'

       and then	set the	option "variable => 'form'". That way you can have
       strict Perl without too much hassle, except that	your code might	be
       exhausting to look at :-).  Things like
       $form{field}{your_field_name}{field} end	up being all over the place,
       instead of the nicer short forms.

       Finally,	when you use the "data"	template option, the keys you specify
       will be available to the	template as regular variables. In the above
       example,	these would be "<% $version %>"	and "<%	$author	%>". And
       complex datatypes are easy:

	   data	=> {
		   anArray => [	1, 2, 3	],
		   aHash => { orange =>	'tangy', chocolate => 'sweet' },
	   }

       This becomes the	following in your template:

	   <%
	       @anArray;    # you can use $myArray[1] etc.
	       %aHash;	    # you can use $myHash{chocolate} etc.
	   %>

       For more	information, please consult the	"Text::Template"
       documentation.

SEE ALSO
       CGI::FormBuilder, CGI::FormBuilder::Template, Text::Template

REVISION
       $Id: Text.pm 100	2007-03-02 18:13:13Z nwiger $

AUTHOR
       Copyright (c) Nate Wiger	<http://nateware.com>. All Rights Reserved.

       Text::Template support is due to	huge contributions by Jonathan
       Buhacoff.  Thanks man.

       This module is free software; you may copy this under the terms of the
       GNU General Public License, or the Artistic License, copies of which
       should have accompanied your Perl kit.

perl v5.32.1			  2016-08-1CGI::FormBuilder::Template::Text(3)

NAME | SYNOPSIS | DESCRIPTION | TEMPLATES | SEE ALSO | REVISION | AUTHOR

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

home | help