11.5 Smarty模板函数
Smarty的使用过程主要通过调用其成员方法来实现。在模板设计过程中主要应用的是Smarty的模板函数。本节主要阐述Smarty模板函数的使用。
11.5.1 内建函数
Smarty自带一些内建函数。内建函数是模板语言的一部分，用户不能创建名称和内建函数一样的自定义函数，也不能修改内建函数。
1．capture函数
capture函数的作用是捕获模板输出的数据并将其存储到一个变量里，而不是把它们输出到页面。任何在{capture name="foo"}和{/capture}之间的数据将被存储到变量$foo中，该变量由name属性指定。在模板中通过$smarty.capture.foo访问该变量。如果没有指定name属性，函数默认将使用“default”作为参数，{capture}必须成对出现，即以{/capture}作为结尾，且该函数不能嵌套使用。
例11-1 捕获模板内容。
{* 该例在捕获到内容后输出一行包含数据的表格，如果没有捕获到就什么也不输出 *}
{capture name=banner}
{include file=”get_banner.tpl”}
{/capture}
{if $smarty.capture.banner ne “”}
<tr>
<td>
{$smarty.capture.banner}
</td>
</tr>
{/if}
2．config_load函数
该函数用于从配置文件中加载变量。
配置文件有利于设计者管理文件中的模板全局变量。最简单的例子就是模板色彩变量。一般情况下如果想改变一个程序的外观色彩，就必须去更改每一个文件的颜色变量。如果有这个配置文件，色彩变量就可以保存在一个地方，只要改变这个配置文件就可以实现色彩的更新。
例11-2 配置文件语法。
# global variables pageTitle = "Main Menu" bodyBgColor = #000000 tableBgColor = #000000 rowBgColor = #00ff00 [Customer] pageTitle = "Customer Info" [Login] pageTitle = "Login" focus = "username" Intro = """This is a value that spans more than one line. you must enclose it in triple quotes.""" # hidden section [.Database] host=my.domain.com db=ADDRESSBOOK user=php-user pass=foobar
配置文件变量值能够在引号中使用，但是没有必要。可以用单引号或者双引号。如果有一个不只在一个区域内使用的变量值，可以使用三引号(""")将它完整地封装起来，可以把它们放进配置文件，只要没有语法错误。建议在程序行前使用“#”加一些注释信息来标识。
上面关于配置文件的例子共有两个部分。每部分的名称都是用一个“[]”给括起来。每部分的名称命名规则就是任意的字符串，只要不包括符号“[”或者“]”。例子开头的4个变量都是全局变量，也就是说不仅可以在一个区域内使用。这些变量总是从配置文件中载入。如果某个特定的局部变量已经载入，这样全局变量和局部变量都还可以载入。如果当某个变量名既是全局变量又是局部变量时，局部变量将被优先赋予值来使用。如果在一个局部中两个变量名相同，最后一个将被赋值使用。
配置文件是通过内建函数载入到模板{ config load } ，可以在某段时期通过预先想好的变量名或者局部名隐藏变量或者完整的一个节。当应用程序读取配置文件和取得有用数据而不用读取模板时这个非常有用，如果有第三方来做模板编辑的话，可以肯定地说它们不能通过载入配置文件到模板而读取到任何有用的数据。
例11-3 config_load函数。
{config_load file="colors.conf"}
<html>
<title>{#pageTitle#}</title>
<body bgcolor="{#bodyBgColor#}">
<table border="{#tableBorderSize#}" bgcolor="{#tableBgColor#}">
<tr bgcolor="{#rowBgColor#}">
<td>First</td>
<td>Last</td>
<td>Address</td>
</tr>
</table>
</body>
</html>
配置文件有可能包含多个部分，此时可以使用附加属性section指定从哪一部分中取得变量。注意：配置文件中的section和模板内建函数section只是命名相同，毫不相干。
例11-4 带section属性的config_load函数演示。
{config_load file="colors.conf" section="Customer"}
<html>
<title>{#pageTitle#}</title>
<body bgcolor="{#bodyBgColor#}">
<table border="{#tableBorderSize#}" bgcolor="{#tableBgColor#}">
<tr bgcolor="{#rowBgColor#}">
<td>First</td>
<td>Last</td>
<td>Address</td>
</tr>
</table>
</body>
</html>
3．include
Include标签用于在当前模板中包含其他模板。当前模板中的变量在被包含的模板中可用。必须指定file属性，该属性指明模板资源的位置。
如果设置了assign属性，该属性对应的变量名用于保存待包含模板的输出，这样待包含模板的输出就不会直接显示了。
例11-5 include函数演示。
{include file="header.tpl"}
{* body of template goes here *}
{include file="footer.tpl"}
可以在属性中传递参数给待包含模板。传递给待包含模板的参数只在待包含模板中可见。如果传递的参数在待包含模板中有同名变量，那么该变量被传递的参数替代。
例11-6 带传递参数的include函数演示。
{include file="header.tpl" title="Main Menu" table_bgcolor="#c0c0c0"}
{* body of template goes here *}
{include file="footer.tpl" logo="http://my.domain.com/logo.gif"}
包含$template_dir文件夹之外的模板请使用模板资源说明的格式。
例11-7 使用外部模板资源的include函数演示。
{* Linux下使用绝对路径 *}
{include file="/usr/local/include/templates/header.tpl"}
{* 同上 *}
{include file="file:/usr/local/include/templates/header.tpl"}
{*Windows下的绝对路径*}
{include file="file:C:/www/pub/templates/header.tpl"}
{* 从数据库中获取 *}
{include file="db:header.tpl"}
4．insert函数
insert函数类似于include函数，不同之处是insert所包含的内容不会被缓存，每次调用该模板都会重新执行该函数。
例如，在页面上端使用一个带有广告条位置的模板，广告条可以包含任何HTML、图像、Flash等混合信息。因此这里不能使用一个静态的链接，同时也不希望该广告条被缓存。这就需要在insert函数中指定：#banner_location_id#和#site_id#值（从配置文件中取），同时需要一个函数取广告条的内容信息。
例11-8 insert函数演示。
{* 获取banner示例 *}
{insert name="getBanner" lid=#banner_location_id# sid=#site_id#}
5．php函数
如果需要在Smarty模板文件中嵌入PHP脚本，则可以利用php函数。而是否处理这些语句还取决于$php_handling的设置。该语句一般不常使用。
例11-9 php标签演示。
{php}
//在模板文件中包含php代码
include("/path/to/display_weather.php");
{/php}
11.5.2 自定义函数
用户可以使用Smarty自带的一组自定义函数。
1．assign函数
assign函数用于在模板被执行时为模板变量赋值。包含var和value两个必选属性，分别代表被赋值的变量和变量值。
例11-10 assign函数演示。
{assign var="name" value="Bob"}
The value of $name is {$name}.
输出结果为：
The value of $name is Bob.
2．counter函数
counter用于输出一个记数过程。counter保存了每次记数时的当前记数值。用户可以通过调节interval和direction调节该值。其属性描述如表11-3所示。
表11-3 counter函数属性
如果指定了"assign"这个特殊属性，该计数器的输出值将被赋给由assign指定的模板变量，而不是直接输出。
例11-11 counter函数演示。
{* 初始化计数值 *}
{counter start=0 skip=2 print=false}
{counter}<br>
{counter}<br>
{counter}<br>
{counter}<br>
输出结果为：
2<br> 4<br> 6<br> 8<br>
3．cycle函数
cycle用于轮转使用一组值。该特性使得在表格中交替输出颜色或轮转使用数组中的值变得很容易。其属性如表11-4所示。
表11-4 cycle函数属性
例11-12 cycle函数演示。
{section name=rows loop=$data}
<tr bgcolor="{cycle values="#eeeeee,#d0d0d0"}">
<td>{$data[rows]}</td>
</tr>
{/section}
输出结果为：
<tr bgcolor="#eeeeee"> <td>1</td> </tr> <tr bgcolor="#d0d0d0"> <td>2</td> </tr> <tr bgcolor="#eeeeee"> <td>3</td> </tr>
4．eval函数
eval按处理模板的方式计算取得变量的值。该特性可用于在配置文件中的标签/变量中嵌入其他模板标签/变量。其各个属性如表11-5所示。
表11-5 eval函数属性
例11-13 eval函数演示。
setup.conf
----------
emphstart = <b>
emphend = </b>
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}
输出结果为：
This is the contents of foo. Welcome to Foobar Pub & Grill's home page! You must supply a <b>city</b>. You must supply a <b>state</b>.
5．fetch函数
fetch用于从本地文件系统、HTTP或FTP上取得文件并显示文件的内容。其各个属性如表11-6所示。
表11-6 fetch函数属性
如果指定了"assign"这个特殊属性，该函数的输出值将被赋给由assign指定的模板变量，而不是直接输出（Smarty 1.5.0新特性）。
注意：
（1）该函数不支持HTTP重定向，如果要取得Web默认页，比如想取得www.domain.com的主页资料，但是不知道主页的具体名称，可能是index.php或index.htm或default.php等等，可以直接使用该站点的URL，记得在URL结尾处加上反斜线。
（2）如果模板的安全设置打开了，当取本地文件时只能取位于定义为安全文件夹下的资料($secure_dir)。
例11-14 fetch函数演示。
{* 在模板中包含JavaScript文件 *}
{fetch file="/export/httpd/www.domain.com/docs/navbar.js"}
{* 嵌入其他网站的特色文件*}
{fetch file="http://www.myweather.com/68502/"}
{* 从FTP获取文件 *}
{fetch file="ftp://user:password@ftp.domain.com/path/to/
currentheadlines.txt"}
{* 从网站中获取并标记指定文本 *}
{fetch file="http://www.myweather.com/68502/" assign="weather"}
{if $weather ne ""}
<b>{$weather}</b>
{/if}
除此之外，Smarty的自定义函数还有html_image、html_options、math、mailto等，在此就不再一一讲解。