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

FreeBSD Manual Pages

  
 
  

home | help
Template::Magic::Zone(User Contributed Perl DocumentatTemplate::Magic::Zone(3)

NAME
       Template::Magic::Zone - The Zone	object

VERSION	1.39
       Included	in Template-Magic 1.39 distribution.

       The latest versions changes are reported	in the Changes file in this
       distribution.

DESCRIPTION
       Template::Magic uses the	Template::Magic::Zone objects to internally
       represent zones.	A reference to the Zone	object is passed as a
       parameter to each handler and is	passed to your subroutines whenever an
       identifier trigger their	execution.

       Note: Unless you	plan to	write an extension or some custom solution,
       you will	find useful just the "attributes", "content" and "param"
       properties that you can use to retrieve parameters from your
       subroutines (see	"Pass parameters to a subroutine" in Template::Magic),
       and the "include_template()" method that	you can	use to include
       templates from inside your code (see "Conditionally include and process
       a template file"	in Template::Magic).

ZONE OBJECT METHODS
       Note: If	you plan to write your own extension, please, feel free	to ask
       for more	support: the documentation in this distribution	is not yet
       complete	for that purpose.

       With Template::Magic the	output generation is so	flexible and
       customizable, because it	can be changed DURING THE PROCESS by several
       factors coming both from	the code (e.g. the type	of value found by the
       "lookup()"), or from the	template (e.g. the literal id of a zone), or
       whatever	combination of factors you prefer.

       It's important to understand that - for this reason - the output
       generation is done recursively by several processes (all	customizable
       by the user) that are executed zone-by-zone, step-by-step, deciding the
       next step by evaluating the handlers conditions.

       This is a sloppy	code to	better understand the whole process:

	   ZONE: while ($zone =	find_and_create_the_zone)
		 {
		   foreach $process (@all_the_process)
		   {
		     HANDLER: foreach $handler (@$process)
			      {
				$handler->($zone)
			      }
		   }
		 }

       As you can see, the HANDLER loop	is nested inside the ZONE loop,	not
       vice versa. This	avoids unneeded	recursions in zones that could be
       wiped out by some handler, thus allowing	a faster execution. (for
       example when the	"value"	property of a zone is undefined	the zone is
       deleted).

       These are the processes that are	executed for any single	zone:

	 content process
	   nested zones	creation
	     zone process
	     lookup process
	     value process
	     text & output processes
	   post	process

       As a general rule, a *_process is a method that executes	in sequence
       the handlers contained in *_handlers constructor	array. In details,
       these process executes the handlers contained in	these constructor
       arrays:

	   zone_process()    zone_handlers
	   value_process()   value_handlers
	   text_process()    text_handlers
	   output_process()  output_handlers
	   post_process()    post_handlers

       Note: the "lookup_process" and the "content_process" are	exceptions to
       this rule.

   content_process()
       This method starts (and manage) the output generation for the zone: it
       process the zone	content, creates each new zone object and apply	the
       appropriate process on the new zones.

       Note: You can change the	way of parsing by customizing the markers
       constructor array. You can change the resulting output by customizing
       the other constructor arrays.

   zone_process()
       The scope of this method	is organizing the Zone object.

       Since it	is called first, and just after	the creation of	each new zone
       object, this is a very powerful method that allows you to manage	the
       output generation before	any other process. With	this method you	can
       even bypass or change the way of	calling	the other processes.

       As other	process	methods, this process simply calls in turn all the
       handlers	in the "zone_handlers" constructor array until some handler
       returns a true value: change the	"zone_handlers"	to change this process
       (see "zone_handlers" in Template::Magic).

   lookup([identifier])
       This method tries to match a zone id with a code	identifier: if it find
       a match it returns the value of the found code identifier, if it	does
       not find	any match it returns the " undef" value.

       If identifier is	omitted, it will use the zone id. Pass an identifier
       to lookup values	from other zones.

       This method looks up first in the containers found values, then in the
       lookups locations. You can customize the	lookup by changing the items
       in the "lookups"	constructor array.

   lookup_process()
       The scope of this method	is setting the zone value with a value from
       the code. It executes the "lookup()" method with	the zone id

       Note: it	works only IF the zone value property is undefined.

   value_process()
       The scope of this method	is finding out a scalar	value from the code to
       pass to the "output_process()".

       As other	process	methods, this process simply calls in turn all the
       handlers	in the "value_handlers"	constructor array until	some handler
       returns a true value: change the	"value_handlers" to change this
       process (see "value_handlers" in	Template::Magic).

       Note: it	works only IF the zone value property is defined.

   text_process()
       The scope of this method	is processing only the text that comes from
       the template and	that goes into the output (in other words the template
       content between labels).

       As other	process	methods, this process simply calls in turn all the
       handlers	in the "text_handlers" constructor array until some handler
       returns a true value: change the	"zone_handlers"	to change this process
       (see "text_handlers" in Template::Magic).

       Note: If	the "text_handlers" constructor	array is undefined (as it is
       by default) the text will be processed by the "output_process()"
       instead.	Use this method	only if	you need to process the	text coming
       from the	template in some special way, different	by the text coming
       from the	code.

   output_process()
       The scope of this method	is processing the text that comes from the
       code. It	is usually used	to process the text coming from	the template
       as well if the "text_process()" method is not used (i.e.	no defined
       "text_handlers").

       As other	process	methods, this process simply calls in turn all the
       handlers	in the "output_handlers" constructor array until some handler
       returns a true value: change the	"zone_handlers"	to change this process
       (see "output_handlers" in Template::Magic).

   post_process()
       This method is called at	the end	of the process,	after the production
       of the output. It is not	used by	default. Use it	to clean up or log
       processes as you	need.

       As other	process	methods, this process simply calls in turn all the
       handlers	in the "post_handlers" constructor array until some handler
       returns a true value: change the	"zone_handlers"	to change this process
       (see "post_handlers" in Template::Magic).

   include_template( template )
       This method loads and process a template. It is useful specially	if you
       want to conditionally load and process a	template from inside your
       code. (see "Conditionally include and process a template	file" in
       Template::Magic)

   AUTOLOAD()
       The Zone	package	has a convenient "AUTOLOAD" method that	allows you to
       retrive or set a	propery	of the zone object.

       All the properties are "lvalue" methods,	that means that	you can	use
       the property as a left value :

	   # to	set classical way (it works anyway)
	   $z->value('whatever')   ;

	   # to	set new	way (lvalue type)
	   $z->value  =	'whatever' ;

	   $the_value =	$z->value  ; # to retrive

       If you plan to customize	the behaviours of Template::Magic, you will
       find useful the "AUTOLOAD" method. You can automatically	set and
       retrieve	your own properties by just using them.	The following example
       shows how you can add a custom 'my_attributes' property to the zone
       object

       In the template zone 'my_zone':

	   text	{my_zone attr1 attr2 attr3} content {/my_zone} text

       These are the properties	right after the	parsing:

	   $zone->id is	set to the string 'my_zone'
	   $zone->attributes is	set to the string ' attr1 attr2	attr3'
	   $zone->content is set to the	string ' content '

       If you want to have your	own 'my_attributes' property, structured as
       you want, you could do this:

	   # creates a 'my_attributes' property
	   # and set it	to an array ref	containing one word per	element
	   $zone->my_attributes	= [ split /\s+/,  substr( $zone->attributes, 1)	]

       From now	on you can retrieve the	attributes your	way:

	   # retrieves the second attribute
	   print $zone->my_attributes->[1]

	   # would print
	   attr2

PROPERTIES
       The following are the properties	that Template::Magic uses to do	its
       job: they all are left value properties (lvalue means that you can
       create a	reference to it, assign	to it and apply	a regex	to it; see
       also "KNOWN ISSUE").

   tm
       The "tm"	property allows	you to access the Template::Magic object.

       Note: this is a read only property.

   mt
       Obsolete	and deprecated property: use "tm" instead.

   id
       The "id"	property allows	you to access the zone identifier. It is
       undefined only if the zone is the main template zone

       Note: this is a read only property.

   attributes
       The "attributes"	property allows	you to access the attributes string.
       This string contains everything between the end of the label IDENTIFIER
       and the END_LABEL marker. It returns the	empty string when there	are no
       attributes.

       Note: this is a read only property.

   content
       The "content" property allows you to retrieve the zone content. The
       zone content is defined only for	blocks (i.e. only with zones that have
       a start and an end label). If the zone is a single label	zone, the
       content property	will return the	"undef"	value.

       Note: this is a read only property.

   param
       This property is	added by the "_EVAL_ATTRIBUTES_" zone handler (if you
       explicitly use it), and - in that case -	holds the evalued attributes
       structure. You can use this property to hold your favorite structure:
       just create it with a simple zone handler as "_EVAL_ATTRIBUTES_".

   container
       This property holds the reference to the	container zone.	It is
       undefined only if the zone is the main template zone and	if the file is
       not included. If	the file is included the container is the zone where
       the INCLUDE_TEMPLATE label was found.

       Note: this is a read only property.

   level
       This property holds the number of nesting level of the zone. -1 for the
       main template zone, 0 for the zones at the template level, 1 for	the
       zone nested in a	zone at	the template level and so on. In other words
       ($z->level < 0) for the main template zone and ($z->level > 0) if the
       zone is nested. The level number	of a zone in an	included file is
       relative	to the main template file, not to the file itself.

   location
       This property holds the package name, the blessed object	or the hash
       reference from which comes the matching identifier at that particular
       moment of the process.

       Usually you don't need to set this property, but	you could find it very
       useful, for example, to access the object methods of a lookup element
       from inside an extension. (more documentation to	come)

   value
       This propery holds the value of the matching identifier at that
       particular moment of the	output generation.

       It's important to understand that the "value_process()" implies a
       recursive assignation to	this property (not to mention that other
       processes could set the property	as well). That means that the "value"
       property	will return different values in	different part of that
       process.	For example: if	you have this simple template:

	   text	{my_id_label} text

       and this	simple code where Template::Magic is looking up:

	   $scalar = 'I	am a simple string';
	   $reference =	\$scalar;
	   $my_id_label	= $reference;

       At the beginning	of the process,	the "value" property will return a
       reference, then (after passing through the other	value handlers)	it
       will be dereferenced and	so the "value" property, at that point,	will
       return 'I am a simple string'.

       Note: In	order to make it work, if the found value is a SCALAR or a
       REFERENCE it must be set	the "value" property 'as is'; if it is
       anything	else, it must be set as	a reference. For example:

	   found values		 value of $zone->value
	   ------------------------------------
	   'SCALAR'		 'SCALAR'
	   (1..5)		 [1..5]
	   [1..5]		 [1..5]
	   (key=>'value')	 {key=>'value'}
	   {key=>'value'}	 {key=>'value'}
	   ------------------------------------

   output
       This property holds the output string coming from the code.

   is_main
       Boolean property: it returns true if the	zone is	a main template	zone.

       Note: this is a read only property.

   _t
       This property holds the reference to the	template structure.

   _s
       This property holds the offset of the template chunk where the content
       starts. Use it to re-locate the content of a zone and only if you know
       what you	are doing.

   _e
       This property holds the offset of the template chunk where the content
       ends. Use it to re-locate the content of	a zone and only	if you know
       what you	are doing.

SEE ALSO
       o   Template::Magic

       o   Template::Magic::HTML

KNOWN ISSUE
       Due to the perl bug #17663 (Perl	5 Debugger doesn't handle properly
       lvalue sub assignment), you must	know that under	the -d switch the
       lvalue sub assignment will not work, so your program will not run as
       you expect.

       In order	to avoid the perl-bug you have 3 alternatives:

       1.  patch perl itself as	suggested in this post:
	   http://www.talkaboutprogramming.com/group/comp.lang.perl.moderated/messages/13142.html
	   (See	also the cgi-builder-users mailinglist about that topic)

       2.  use the lvalue sub assignment (e.g. "$s->any_property =
	   'something'") only if you will never	need -d

       3.  if you plan to use -d, use only standard assignments	(e.g.
	   "$s->any_property('something')")

       Maybe a next version of perl will fix the bug, or maybe lvalue subs
       will be banned forever, meanwhile be careful with lvalue	sub
       assignment.

SUPPORT
       Support for all the modules of the Template Magic System	is via the
       mailing list. The list is used for general support on the use of	the
       Template::Magic,	announcements, bug reports, patches, suggestions for
       improvements or new features. The API to	the Magic Template System is
       stable, but if you use it in a production environment, it's probably a
       good idea to keep a watch on the	list.

       You can join the	Template Magic System mailing list at this url:

       <http://lists.sourceforge.net/lists/listinfo/template-magic-users>

AUTHOR and COPYRIGHT
       A(C) 2004-2005 by Domizio Demichelis (<http://perl.4pro.net>)

       All Rights Reserved. This module	is free	software. It may be used,
       redistributed and/or modified under the same terms as perl itself.

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 512:
	   Non-ASCII character seen before =encoding in	'A(C)'.	Assuming
	   CP1252

perl v5.32.1			  2006-09-15	      Template::Magic::Zone(3)

NAME | VERSION 1.39 | DESCRIPTION | ZONE OBJECT METHODS | PROPERTIES | SEE ALSO | KNOWN ISSUE | SUPPORT | AUTHOR and COPYRIGHT | POD ERRORS

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

home | help