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

FreeBSD Manual Pages

  
 
  

home | help
Template::Magic::QuickUsertContributed Perl DocuTemplate::Magic::QuickStart(3)

NAME
       Template::Magic::QuickGuide - A quick start for Webmasters

Quick Start for	Webmasters
   Overview
       If you are a webmaster you don't	need to	know perl in order to
       completely customize the	output of any perl script that uses
       Template::Magic:	you have just to edit the templates that the perl
       script uses, and	you will have the full power on	the script output.
       Well... the full	power the perl programmer decided to give you ;-).

   Templates
       Templates are simple files used by the Template::Magic system in	order
       to produce the output. Depending	on the application, a template might
       be a text, html,	xml, or	any other type of file.	Usually	the template
       is composed by static text (i.e.	the text that will never be changed by
       the application), and a few delimited zones (labels or blocks), that
       will be substituted by the application with dynamic data	produced by
       the program. The	merging	of the static text and the program data	will
       produce the output of the program.

       This is a very simple template file:

	   City: {city}
	   Date	and Time: {date_and_time}

       where {city} and	{date_and_time}	are just zones (labels)	that the
       application recognizes and replaces with	some real runtime values. The
       remaining text is static	text which will	be included verbatim in	the
       output.

       The following may be an output:

	   City: NEW YORK
	   Date	and Time: Sat Nov 16 21:03:31 2002

   Zones: Labels and Blocks
       A 'zone'	is a special delimited place in	the template, that the
       Template::Magic system recognizes as a zone. Depending on the
       implementation decided by the programmer, the zones of each application
       may be delimited	by a different set of characters. Usually the default
       delimiters are "{ }" or "<!--{ }-->" (which are default delimiters
       included	in HTML	comments, very handy in	HTML WYSIWYG editors).

       A zone may have a content or not. A zone	with no	content	is also	a
       label, while a zone with	content	is also	a block:

	   a label: {identifier}
	   a block: {identifier} content of the	block {/identifier}

       Identifiers are case sensitive and are defined by the programmer. He
       should provide a	list of	recognized labels and block, along with	a
       description of each zone.

   Repeating blocks
       Oftenly an application is required to produce lists. It can do so by
       implementing a repeating	block. The content of the repeating block will
       be parsed and the included labels and blocks will be substituted	with
       the actual data as many time as necessary in order to produce the full
       list output:

	   {visit_list}
	     City: {city}
	     Date and Time: {date_and_time}
	   {/visit_list}

       The following may be an output:

	   City: NEW YORK
	   Date	and Time: Sat Nov 16 21:03:31 2002

	   City: WASHINGTON
	   Date	and Time: Sun Nov 17 18:21:40 2002

	   City: MIAMI
	   Date	and Time: Mon Nov 18 16:38:16 2002

   the NOT_* block
       For any label or	block you can use a NOT_* zone (where '*' stands for
       the zone	id) which  will	automatically be printed if the	zone is	not
       printed,	or wiped out if	the zone is printed.

	   {visit_list}
	     City: {city}
	     Date and Time: {date_and_time}{NOT_date_and_time}N/A{/NOT_date_and_time}
	   {/visit_list}
	   {NOT_visit_list}
	     No	visit to report
	   {/NOT_visit_list}

       The following may be an output:

	   City: DENVER
	   Date	and Time: N/A

	   City: WASHINGTON
	   Date	and Time: Sun Nov 17 18:21:40 2002

	   City: MIAMI
	   Date	and Time: Mon Nov 18 16:38:16 2002

       The following may be another output:

	   No visit to report

   INCLUDE_TEXT	and INCLUDE_TEMPLATE
       You can inlude a	template or a static text file by using	2 special
       lables: INCLUDE_TEXT and	INCLUDE_TEMPLATE. The include text will
       include verbatim	the text found into the	file, while INCLUDE_TEMPLATE
       will parse the file first, substituting labels and blocks with actual
       data.

	   {INCLUDE_TEMPLATE /templates/temp_file.html}
	   {INCLUDE_TEXT /templates/text_file.html}

       Paths are relative to the current template.

   Customizing a template
       You can customize all the static	text in	any template, you can also
       omit or move any	label or block inside any template. You	can split a
       template	into chunks and	include	each chunk with	an INCLUDE_TEXT	or an
       INCLUDE_TEMPLATE	label, or you can join different included templates
       chunk into a single template.

       In special cases, when the programmer implemented this possibility, you
       can also	pass some custom parameters to some custom labels in order to
       further customize the output. Anyway, the label and block definition
       along with the production of the	dynamic	content	is always controlled
       by the application.

SYNTAX GLOSSARY
       attributes string
	   The attributes string contains every	character between the end of
	   the label identifier	and the	end label marker.

	   Note: The attributes	are a special implementation decided by	the
	   programmer for special resons.

       block
	   A block is a	template zone delimited	by (and	including) a label and
	   an end label:

	       +-------+-------------------+------------+
	       | LABEL |      CONTENT	   | END_LABEL	|
	       +-------+-------------------+------------+

	   Example: {my_identifier} content of the block {/my_identifier}

	   where '{my_identifier}' is the LABEL, ' content of the block	' is
	   the CONTENT and '{/my_identifier}' is the END_LABEL.

       end label
	   An end label	is a string in the form	of:

	       +--------------+---------------+------------+------------+
	       | START_MARKER |	END_MARKER_ID |	IDENTIFIER | END_MARKER	|
	       +--------------+---------------+------------+------------+

	   Example of end label	: {/my_identifier}

	   where '{' is	the START_MARKER, '/' is the END_MARKER_ID,
	   'my_identifier' is the IDENTIFIER, and '}' is the END_MARKER.

       identifier
	   A label identifier is a alpha-numeric case-sensitive	name that must
	   be implemented by the application.

       illegal blocks
	   Each	block in the template can contain arbitrary quantities of
	   nested labels and/or	blocks,	but it cannot contain itself (a	block
	   with	its same identifier), or cannot	be cross-nested.

	   Legal  block: {block1}...{block2}...{/block2}...{/block1}

	   Illegal auto-nested block:
	   {block1}...{block1}...{/block1}...{/block1}

	   Illegal cross-nested	block:
	   {block1}...{block2}...{/block1}...{/block2}

	   If the template contains any	illegal	block, unpredictable
	   behaviours may occur.

       include label
	   An include label is a label used to include a template or static
	   text	file. The identifier must be 'INCLUDE_TEMPLATE'	of
	   'INCLUDE_TEXT' and the attributes string should be a	valid path.
	   Paths are relative to the current template.

	   Example: {INCLUDE_TEMPLATE /templates/temp_file.html} Example:
	   {INCLUDE_TEXT /templates/text_file.html}

       label
	   A label is a	string in the form of:

	       +--------------+------------+------------+------------+
	       | START_MARKER |	IDENTIFIER | ATTRIBUTES	| END_MARKER |
	       +--------------+------------+------------+------------+

	   Example: {my_identifier attribute1 attribute2}

	   where '{' is	the START_MARKER, 'my_identifier' is the IDENTIFIER,
	   'attribute1 attribute2' are the ATTRIBUTES and '}' is the
	   END_MARKER.

	   Note: The attributes	are a special implementation decided by	the
	   programmer for special resons.

       markers
	   The markers that defines a labels and blocks. These are the default
	   values of the markers that define the label:

	       START_MARKER:   {
	       END_MARKER_ID:  /
	       END_MARKER:     }

	   The default marker used in HTML environment (e.g.
	   <!--{identifier}-->):

	       START_MARKER:   <!--{
	       END_MARKER_ID:  /
	       END_MARKER:     }-->

	   Each	application may	define a different set of markers.

       nested block
	   A nested block is a block contained in another block:

	       +----------------------+
	       |   CONTAINER_BLOCK    |
	       |  +----------------+  |
	       |  |  NESTED_BLOCK  |  |
	       |  +----------------+  |
	       +----------------------+

	   Example:
	       {my_container_identifier}
	       {my_nested_identifier} content of the block
	   {/my_nested_identifier}
	       {/my_container_identifier}

	   where all the above is the CONTAINER_BLOCK and
	   '{my_nested_identifier} content of the block
	   {/my_nested_identifier}' is the NESTED_BLOCK.

       output
	   The output is the result of the merger of runtimes values with a
	   template

       template
	   A template is a text	content	or a text file (i.e. plain, HTML, XML,
	   etc.) containing some label or block.

       zone
	   A zone is an	area in	the template that must have an identifier, may
	   have	an attributes string and may have a content. A zone without
	   any content is also called label, while a zone with content is also
	   called block.

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 229:
	   Non-ASCII character seen before =encoding in	'A(C)'.	Assuming
	   CP1252

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

NAME | Quick Start for Webmasters | SYNTAX GLOSSARY | 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::QuickStart&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help