Great Templates

FEATURED WEB TEMPLATES

Amazon Books

Learn PHP

PHP Training
Zend Cert Training Zend Certified Engineer Zend PHP Pro

Smarty: Custom Functions

Chapter 8. Custom Functions


Smarty comes with several custom functions that you can use in the templates.

assign

Attribute Name Type Required Default Description
var string Yes n/a The name of the variable being assigned
value string Yes n/a The value being assigned

assign is used for assigning template variables during the execution of the template.

Example 8-1. assign
{assign var="name" value="Bob"}

The value of $name is {$name}.

OUTPUT:

The value of $name is Bob.

counter

Attribute Name Type Required Default Description
name string No default The name of the counter
start number No 1 The initial number to start counting from
skip number No 1 The interval to count by
direction string No up the direction to count (up/down)
print boolean No true Whether or not to print the value
assign string No n/a the template variable the output will be assigned to

counter is used to print out a count. counter will remember the count on each iteration. You can adjust the number, the interval and the direction of the count, as well as determine whether or not to print the value. You can run multiple counters concurrently by supplying a unique name for each one. If you do not supply a name, the name \'default\' will be used.

If you supply the special "assign" attribute, the output of the counter function will be assigned to this template variable instead of being output to the template.

Example 8-2. counter
{* initialize the count *}
{counter start=0 skip=2}

{counter}

{counter}

{counter}

this will output: 

0

2

4

6

cycle

Attribute Name Type Required Default Description
name string No default The name of the cycle
values mixed Yes N/A The values to cycle through, either a comma delimited list (see delimiter attribute), or an array of values.
print boolean No true Whether to print the value or not
advance boolean No true Whether or not to advance to the next value
delimiter string No , The delimiter to use in the values attribute.
assign string No n/a the template variable the output will be assigned to

Cycle is used to cycle though a set of values. This makes it easy to alternate between two or more colors in a table, or cycle through an array of values.

You can cycle through more than one set of values in your template by supplying a name attribute. Give each set of values a unique name.

You can force the current value not to print with the print attribute set to false. This would be useful for silently skipping a value.

The advance attribute is used to repeat a value. When set to false, the next call to cycle will print the same value.

If you supply the special "assign" attribute, the output of the cycle function will be assigned to this template variable instead of being output to the template.

Example 8-3. cycle


{/section} 
{section name=rows loop=$data}
{$data[rows]}











   1
   2
   3

					
				
			

		

				
	








	
debug

	

		
					Attribute 
					Name
					Type
					Required
					Default
					Description
				

			
				

			
			

				output
				string
				No
				
				html
				output type, html 
				or javascript
			

		

	

	
{debug} dumps the debug console to the page. This works 
	regardless of the debug settings in Smarty. Since this gets executed at 
	runtime, this is only able to show the assigned variables, not the templates 
	that are in use. But, you see all the currently available variables within 
	the scope of this template. 




	
eval

	

		
					Attribute 
					Name
					Type
					Required
					Default
					Description
				

			
				

			
			

				var
				mixed
				Yes
				
				n/a
				variable (or 
				string) to evaluate
			

			

				assign
				string
				No
				
				n/a
				the template 
				variable the output will be assigned to
			

		

	

	
eval is used to evaluate a variable as a template. This 
	can be used for things like embedding template tags/variables into variables 
	or tags/variables into config file variables. 

	
If you supply the special "assign" attribute, the output 
	of the eval function will be assigned to this template variable instead of 
	being output to the template. 

	

		

			
Technical Note: Evaluated variables are 
			treated the same as templates. They follow the same escapement and 
			security features just as if they were templates. 

		

	

	

		

			
Technical Note: Evaluated variables are 
			compiled on every invocation, the compiled versions are not saved! 
			However if you have caching enabled, the output will be cached with 
			the rest of the template. 

		

	

	

		

			
			

				Example 8-4. eval

					

						
						
setup.conf
----------

emphstart = 
emphend = 
title = Welcome to {$company}\'s home page!
ErrorCity = You must supply a {#emphstart#}city{#emphend#}.
ErrorState = You must supply a {#emphstart#}state{#emphend#}.


index.tpl
---------

{config_load file="setup.conf"}

{eval var=$foo}
{eval var=#title#}
{eval var=#ErrorCity#}
{eval var=#ErrorState# assign="state_error"}
{$state_error}

OUTPUT:

This is the contents of foo.
Welcome to Foobar Pub & Grill\'s home page!
You must supply a city.
You must supply a state.

								
					

				

			

					
		

	

	
fetch

	

		
					Attribute 
					Name
					Type
					Required
					Default
					Description
				

			
				

			
			

				file
				string
				Yes
				
				n/a
				the file, http or 
				ftp site to fetch
			

			

				assign
				string
				No
				
				n/a
				the template 
				variable the output will be assigned to
			

		

	

	
fetch is used to fetch files from the local file system, 
	http, or ftp and display the contents. If the file name begins with 
	"http://", the web site page will be fetched and displayed. If the file name 
	begins with "ftp://", the file will be fetched from the ftp server and 
	displayed. For local files, the full system file path must be given, or a 
	path relative to the executed php script. 

	
If you supply the special "assign" attribute, the output 
	of the fetch function will be assigned to this template variable instead of 
	being output to the template. (new in Smarty 1.5.0) 

	

		

			
Technical Note: This will not support http redirects, be 
			sure to include a trailing slash on your web page fetches where 
			necessary. 

		

	

	

		

			
Technical Note: If template security is 
			turned on and you are fetching a file from the local file system, 
			this will only allow files from within one of the defined secure 
			directories. ($secure_dir) 

		

	

	

		

			
			

				Example 8-5. fetch

					

						
						
{* include some javascript in your template *}
{fetch file="/export/httpd/www.example.com/docs/navbar.js"}

{* embed some weather text in your template from another web site *}
{fetch file="http://www.myweather.com/68502/"}

{* fetch a news headline file via ftp *}
{fetch file="ftp://user:password@ftp.example.com/path/to/currentheadlines.txt"}

{* assign the fetched contents to a template variable *}
{fetch file="http://www.myweather.com/68502/" assign="weather"}
{if $weather ne ""}
	{$weather}
{/if}

								
					

				

			

					
		

	






html_checkboxes




	
				Attribute Name
				Type
				Required
				Default
				Description
			

		
			

		
		

			name
			string
			No
			
			checkbox
			name of checkbox list
		

		

			values
			array
			Yes, unless using 
			options attribute
			
			n/a
			an array of values for 
			checkbox buttons
		

		

			output
			array
			Yes, unless using 
			options attribute
			
			n/a
			an array of output for 
			checkbox buttons
		

		

			selected
			string/array
			No
			
			empty
			the selected checkbox 
			element(s)
		

		

			options
			associative array
			Yes, unless using 
			values and output
			
			n/a
			an associative array of 
			values and output
		

		

			separator
			string
			No
			
			empty
			string of text to 
			separate each checkbox item
		

		

			labels
			boolean
			No
			
			true
			add -tags to the 
			output
		

	





html_checkboxes is a custom function that creates an html 
checkbox group with provided data. It takes care of which item(s) are selected 
by default as well. Required attributes are values and output, unless you use 
options instead. All output is XHTML compatible. 



All parameters that are not in the list above are printed as name/value-pairs 
inside each of the created -tags. 





	

		
		

			Example 8-6. html_checkboxes

				

					
					
					

					require(\'Smarty.class.php\');

					$smarty 
					= new 
					Smarty;

					$smarty->assign(\'cust_ids\', 
					array(1000,1001,1002,1003));

					$smarty->assign(\'cust_names\', 
					array(\'Joe 
					Schmoe\',\'Jack 
					Smith\',\'Jane 
					Johnson\',\'Charlie 
					Brown\'));

					$smarty->assign(\'customer_id\',
					1001);

					$smarty->display(\'index.tpl\');

					

					?> 
							
				

			

			
where index.tpl is: 

			

				

					
					
{html_checkboxes name="id" values=$cust_ids selected=$customer_id output=$cust_names separator="
"}

							
				

			

			

				

					
					
					

					require(\'Smarty.class.php\');

					$smarty 
					= new 
					Smarty;

					$smarty->assign(\'cust_checkboxes\', 
					array(

					            1000
					=> 
					\'Joe Schmoe\',

					            1001
					=> 
					\'Jack Smith\',

					            1002
					=> 
					\'Jane Johnson\',

					            1003
					=> 
					\'Charlie Brown\'));

					$smarty->assign(\'customer_id\',
					1001);

					$smarty->display(\'index.tpl\');

					?> 
							
				

			

			
where index.tpl is: 

			

				

					
					
{html_checkboxes name="id" options=$cust_checkboxes selected=$customer_id separator="
"}

							
				

			

			
both examples will output: 

			

				

					
					
Joe Schmoe

Jack Smith

Jane Johnson

Charlie Brown

							
				

			

		

				
	







html_image




	
				Attribute Name
				Type
				Required
				Default
				Description
			

		
			

		
		

			file
			string
			Yes
			
			n/a
			name/path to image
		

		

			height
			string
			No
			
			actual image height
			height to display image
		

		

			width
			string
			No
			
			actual image width
			width to display image
		

		

			basedir
			string
			no
			
			web server doc root
			directory to base 
			relative paths from
		

		

			alt
			string
			no
			
			""
			alternative description 
			of the image
		

		

			href
			string
			no
			
			n/a
			href value to link the 
			image to
		

	





html_image is a custom function that generates an HTML tag 
for an image. The height and width are automatically calculated from the image 
file if none are supplied. 



basedir is the base directory that relative image paths are 
based from. If not given, the web server document root (env variable 
DOCUMENT_ROOT) is used as the base. If security is enabled, the path to the 
image must be within a secure directory. 



href is the href value to 
link the image to. If link is supplied, an  
tag is put around the image tag. 



All parameters that are not in the list above are printed as name/value-pairs 
inside the created -tag. 




	

		
Technical Note: html_image requires a hit to 
		the disk to read the image and calculate the height and width. If you 
		don\'t use template caching, it is generally better to avoid html_image 
		and leave image tags static for optimal performance. 

	







	

		
		

			Example 8-7. html_image example

				

					
					
					

					require(\'Smarty.class.php\');

					$smarty 
					= new 
					Smarty;

					$smarty->display(\'index.tpl\');

					

					?> 
							
				

			

			
where index.tpl is: 

			

				

					
					
{html_image file="pumpkin.jpg"}
{html_image file="/path/from/docroot/pumpkin.jpg"}
{html_image file="../path/relative/to/currdir/pumpkin.jpg"}

							
				

			

			
a possible output would be: 

			

				

					
					



							
				

			

		

				
	







html_options




	
				Attribute Name
				Type
				Required
				Default
				Description
			

		
			

		
		

			values
			array
			Yes, unless using 
			options attribute
			
			n/a
			an array of values for 
			dropdown
		

		

			output
			array
			Yes, unless using 
			options attribute
			
			n/a
			an array of output for 
			dropdown
		

		

			selected
			string/array
			No
			
			empty
			the selected option 
			element(s)
		

		

			options
			associative array
			Yes, unless using 
			values and output
			
			n/a
			an associative array of 
			values and output
		

		

			name
			string
			No
			
			empty
			name of select group
		

	





html_options is a custom function that creates html option 
group with provided data. It takes care of which item(s) are selected by default 
as well. Required attributes are values and output, unless you use options 
instead. 



If a given value is an array, it will treat it as an html 
OPTGROUP, and display the groups. Recursion is supported with OPTGROUP. All 
output is XHTML compatible. 



If the optional 
name attribute is given, the  tags 
will enclose the option list. Otherwise only the option list is generated. 



All parameters that are not in the list above are printed as 
name/value-pairs inside the 

EXAMPLE 2
---------

index.php:

require(\'Smarty.class.php\');
$smarty = new Smarty;
$smarty->assign(\'cust_options\', array(
			1001 => \'Joe Schmoe\',
			1002 => \'Jack Smith\',
			1003 => \'Jane Johnson\',
			1004 => \'Charlie Brown\'));
$smarty->assign(\'customer_id\', 1001);
$smarty->display(\'index.tpl\');

index.tpl:




OUTPUT: (both examples)
-----------------------

Joe SchmoeJack SmithJane JohnsonCharlie Brown
					
				
			
		
		
	





html_radios




	
				Attribute Name
				Type
				Required
				Default
				Description
			

		
			

		
		

			name
			string
			No
			
			radio
			name of radio list
		

		

			values
			array
			Yes, unless using 
			options attribute
			
			n/a
			an array of values for 
			radio buttons
		

		

			output
			array
			Yes, unless using 
			options attribute
			
			n/a
			an array of output for 
			radio buttons
		

		

			selected
			string
			No
			
			empty
			the selected radio 
			element
		

		

			options
			associative array
			Yes, unless using 
			values and output
			
			n/a
			an associative array of 
			values and output
		

		

			separator
			string
			No
			
			empty
			string of text to 
			separate each radio item
		

	





html_radios is a custom function that creates html radio 
button group with provided data. It takes care of which item is selected by 
default as well. Required attributes are values and output, unless you use 
options instead. All output is XHTML compatible. 



All parameters that are not in the list above are printed as name/value-pairs 
inside each of the created -tags. 





	

		
		

			Example 8-9. html_radios

				

					
					
index.php:

require(\'Smarty.class.php\');
$smarty = new Smarty;
$smarty->assign(\'cust_ids\', array(1000,1001,1002,1003));
$smarty->assign(\'cust_names\', array(\'Joe Schmoe\',\'Jack Smith\',\'Jane
Johnson\',\'Charlie Brown\'));
$smarty->assign(\'customer_id\', 1001);
$smarty->display(\'index.tpl\');


index.tpl:

{html_radios name="id" values=$cust_ids selected=$customer_id output=$cust_names separator="
"}


index.php:

require(\'Smarty.class.php\');
$smarty = new Smarty;
$smarty->assign(\'cust_radios\', array(
			1000 => \'Joe Schmoe\',
			1001 => \'Jack Smith\',
			1002 => \'Jane Johnson\',
			1003 => \'Charlie Brown\'));
$smarty->assign(\'customer_id\', 1001);
$smarty->display(\'index.tpl\');


index.tpl:

{html_radios name="id" options=$cust_radios selected=$customer_id separator="
"}


OUTPUT: (both examples)

Joe Schmoe

Jack Smith

Jane Johnson

Charlie Brown

							
				

			

		

				
	







 


			
			

 		
		

	
















	

		
		

	

	

		
		

		Learn PHP |
		Zend Certified Engineer |
		Zend PHP Pro |		
		PHP Web Apps |		
		Web Hosting Service | 
		Low Cost Domain Names | 
		Great Templates |
		Great Books |		
		Testimonials |
		Tech.Articles | 
		TOS | 
		AUS | 
		Home | 
		Linux Apache MySQL PHP