smarty3.0中文手册文档API及使用指南_2-it论坛-计算机论坛

安哥网络

smarty3.0中文手册文档API及使用指南_2-it论坛-计算机论坛
4、Smarty语法基础篇
4.1 变量
模板中的变量主要来源有三种。
1、是由原php文件中分配过来的。
$smarty->assign('name','韩灵稚');    #在源php文件中分配
<span>你好， {$name}</span> #在模板文件中使用
2、是由配置文件中分配过来的。
$smarty->configLoad(“configs/my.conf”)  #在源php文件中载入配置文件，也可以在模板中载入
<span style="color:{#fontcolor#}; font-size:{#fontsize#};">这是{#gv#}</span><br />  #在模板文件中使用
3、是在模板文件中创建的。
{assign var="name" value="韩灵稚" nocache=”false”scope=”global”}   
#在模板中定义的变量，如果之前定义了相同的变量，则以最后一次定义为准。
{$name="韩灵稚"}    #给变量直接赋值，如果该变量原来不存在，自动创建，3.0新特性。
{assign var=foo value=[1,2,3]}     #定义普通数组变量
{assign var=foo value=['y'=>'yellow','b'=>'blue']}    #定义关联数组
{assign var=foo value=[1,[9,8],3]}  #定义数组中的数组
{$foo[]=1}    #增加变量数组$foo的一个元素
<span>你好， {$name}</span> #在模板文件中使用
【相关函数】
$smarty->getVariable($variable, $_ptr = null, $search_parents = true,
$error_enable = true) #获得变量，仅限于获得第一种方式的变量
$smarty->getTemplateVars($varname = null, $_ptr = null, $search_parents = true)   
#获得变量，可以获得第一种和第三种方式的变量（第三种方式变量scope必须为global或者parent），
如果想获得配置变量参看3.4
4.2 Smarty保留变量Smarty系统中保留了一些内置变量，可以快速访问相应的变量。但是不能再源php中获得这些变量。
1、请求访问变量（Request variables）
$smarty.get.变量       #显示通过get方式传过来的指定变量的值。
$smarty.post.变量      #显示通过post方式传过来的指定变量的值。
$smarty.cookies.变量 #显示通过cookie中指定变量的值。
$smarty.server.SERVER_NAME   #显示server变量值，phpinfo()中$_SERVER系列变量
$smarty.env.PATH   #显示系统环境变量值，phpinfo()中$_ENV系列变量
$smarty.session.变量 #显示session中指定变量的值
$smarty.request.变量 #显示通过post、get、cookie中指定变量的值。
2、时间访问变量
{$smarty.now} #显示unix系统时间戳，需要变量调节器格式化，参看4.2.4，也可以使使用{time()}
3、常量访问变量
{$smarty.const._MY_CONST_VAL}   #访问php中的常量包括自定义常量和系统常量
4、{$smarty.capture}  
参看4.4.1
5、配置访问变量
{$smarty.config.配置变量}   #访问配置变量，等同于 #配置变量# 方式
6、{$smarty.section}, {$smarty.foreach}
参看4.4.3和4.4.4
7、{$smarty.template}   #显示模板路径和名称
4.3 变量操作4.2.1赋值{$name = 新值} 比如，{$name=”我的名字叫韩灵稚”}   #新值将替代原值，如果原来无该变量，
则创建变量并赋值。配置变量无法重新赋值。
{$name = 表达式} 比如,{$name = 1+2+$foo['bar']}  #$foo['bar']的值为1， 变量值为4
{$foo['bar']=1}    #给数组的一个元素赋值
{$foo['bar']['blar']=1}   #给多维数组的一个元素赋值
{$foo = array(1,2,3,4,5)}   #利用php函数创建变量$foo，并赋值。
4.2.2访问最简单的访问方法是 {$var}，配置变量访问是{#configvar#}
数组变量的访问可以是{$array[1][1]}，也可以支持{$array.1.1}
对象的访问{$object->method1($x)}，也支持对象链，{$object->method1($x)->method2($y)}
字符串与变量的混合输出
{"大家好，我是$name<br />"}   #Smarty可以识别嵌入在双引号中的变量，
只要此变量只包含数字、字母、下划线。
{"大家好，我是`$name[$obj->a]`<br />"}    #中括号[]、句号. 对象相关 -> ,必须将变量用两个`符号括起。
4.2.3变量名变量与php相同，都支持在变量名称中使用变量，smarty还支持使用表达式。
$foo         #一个普通的变量
$foo_{$bar}   #变量名中包含变量
$foo_{$x+$y}  #变量名中可以支持表达式
$foo_{$bar}_buh_{$blar}   #变量名包含多个变量
4.2.4变量调节器变量调节器主要是对变量进行格式化。
{$var|capitalize}   #将变量首字大写
{$var|count_characters:false}   #计算变量里的字符数，false为不计算空格。
若变量为数值则为数字和小数点等其他运算符的总和
{$var| cat:var2} #将var2连接到var，若为数值以字符串处理。
{$var| count_paragraphs} #计算变量里的段落数量，已“\n“区分
{$var| count_sentences} #计算变量中句子的数量，不好使
{$var| count_words} #计算变量中单词的数量 已非字母和数字的字符分割统计
{$var| date_format :"%H:%M:%S" } #格式化变量日起，具体参数看chm文档
{$var| default:"no title" } #当变量为空时，为变量提供一个默认值
{$var| escape:url}     #对变量值进行转码，具体参数看chm文档
{$var| indent:10:"*"}    #对变量指定具体字符进行缩进,若为空格在html中不会显示出来，具体参数看chm文档
{$var| lower}   #将变量小写
{$var| nl2br }   #将变量中的“\n“转换成”<br />“
{$var| regex_replace:"/[\r\t\n]/":" "} #将变量中的符合正则的内容替换成指定内容
{$var| replace:"Garden":"Vineyard"} #将变量中要求的内容替换成指定内容
{$var| spacify:"^^"} #将变量字符与字符之间插入指定内容，包括空格
{$var|string_format:"%d"}   #将变量中的内容格式化，格式化参数同printf
{$var| strip: "*"}  #用一个空格或一个给定字符替换所有重复空格,换行和制表符
{$var| strip_tags} #删除变量中的html标记, 去除<和>标签,包括在<和>之间的任何内容
{$var| truncate:30:"...":true}    #截取变量的到规定的长度，具体参数看chm文档
{$var| upper}    #将变量大写
{$var| wordwrap:30:"\n":true}    #规定指定的长度强制换行，具体参数看chm文档
修改器可以复合组合。
{$articleTitle|lower|spacify|truncate:30:". . ."}
设置默认变量调节器
$smarty->getDefault_modifiers()    #默认为空数组
$smarty->setDefault_modifiers(array('spacify:"^^"','capitalize')   #设置变量的默认调节器，必须用array
{name}    #模板变量name自动加入上面两个调节器
同时也可以定义自己的调节器，详情请参考6.7.4和6.8.4
4.2.5变量作用域（未写）
4.4 内建函数4.4.1 capturecapture函数的作用是捕获模板输出的数据并将其存储到一个变量里,而不是把它们输出到页面.
任何在 {capture name="foo"}和{/capture}之间的数据将被存储到变量$foo中。
这样可以根据实际情况，选择性的输出一些内容,输出的语法是$smarty.capture.变量。
{capture name="bottom"}
{include file="bottom.tpl" nr="这是底部的内容"}
{/Capture}
{if true }  #进行条件判断，确定是否输出
{$smarty.capture.bottom}
{/if}
4.4.2 config_load参看3.4
4.4.3 foreach,foreachelseforeach 适合于简单数组（元素类型相同）
{foreach name=名称 item=内容 key=键 from=数组}  #2.0中的用法，3.0沿用
正常执行
{foreachelse}
From变量数组没有值时（0个元素）执行。
{/foreach}
例子：
{foreach name=for1 item=num from=$foo}
{$smarty.foreach.for1.index+1}个元素：{$num}<br />
{if is_array($num)}
{foreach name=for2 item=num2 key=key2 from=$num}
{$str|catsmarty.foreach.for2.index+1|cat:"个元素："|catnum2|cat:" key是"|catkey2|indent:1:"."}<br />
{/foreach}
{/if}
{foreachelse}
{$smarty.foreach.for1.index+1}个元素：没有值！<br />
{/foreach}
foreach的内置变量
$smarty.foreach.foreachname.index   #（循环内部使用）显示当前循环的索引,如果数组为空，返回-1
$smarty.foreach.foreachname. iteration    #（循环内部使用）显示当前的循环次数
$smarty.foreach.foreachname.first #（循环内部使用）如果为第一次循环，返回true
$smarty.foreach.foreachname.last #（循环内部使用）如果为最后一次循环，返回true
$smarty.foreach.foreachname.total #（循环内外部使用）显示循环的总次数
foreach 在3.0中做一定的升级，语法更接近于php，内置变量也更简洁。
{foreach $myarray as $var}...{/foreach}
foreach的内置变量，均可在内外部使用
$var@key           #输出元素的键值，简单为012，关联为具体键值。
$var@iteration      #显示当前的循环次数，外部使用为最后一次
$var@index         #显示当前循环的索引,如果数组为空，返回-1，外部使用为最后一次
$var@total          #显示循环的总次数
$var@first           #如果为第一次循环，返回true
$var@last           #如果为最后一次循环，返回true
4.4.4 section,sectionelsesection适用于复杂的数组操作，不适合关联数组。但是在3.0中并为对他做什么升级和修改，
而是直接推出了for命令，for更接近于php语法。可以预见，section将在未来版本中淘汰。
{section name=名称 loop=循环数组(次数) start=开始(0) step=步阶(1) max=最大循环次数 show=是否显示(true)}  
#2.0中的用法，3.0沿用
正常执行
{sectionelse}
loop数组没有值时（0个元素）执行。
{/section }
例子：
{section name=sec1 loop=$foo step=1 start=0 show=true}
第{$smarty.section.sec1.index+1}个元素：{$foo[sec1]}  循环次数是
{$smarty.section.sec1.iteration}<br />
{if is_array($foo[sec1])}
{section name=sec2 loop=$foo[sec1] step=1 start=0 show=true}
第{$smarty.section.sec2.index+1}个元素：{$foo[sec1][sec2]}
循环次数是{$smarty.section.sec2.iteration}<br />
{/section}
{/if}
{sectionelse}
{$smarty.section.sec1.index}个元素：没有值！<br />
{/section}
Section的内置变量与foreach 相同。
4.4.5 include{include file="包含文件" var=”自定义传入包含文件的变量”assign=” 指定一个变量保存待包含模板的输出”}
如果规定了assign ，则包含文件不会马上输出，模板输出的数据将存储到assign指定的变量里,
这样可以根据实际情况，再输出包含文件的内容。原理类似于capture。
4.4.6 include_php{include_php file="包含文件" once=”是否指包含一次(true)”assign=” 指定一个变量保存待包含的输出”}
包含php文件，包含的文件正常编译，并提供输出。如果规定了assign ，
则包含文件不会马上输出，输出的数据将存储到assign指定的变量里,
这样可以根据实际情况，再输出包含文件的内容。
4.4.7 insertInsert最大的特点是不缓存。他的参数可能会缓存。但是insert所调用的函数内部不缓存。
{insert name=”函数名称” script=”包含函数的脚本”var….=”函数参数” assign=” 指定一个变量保存调用的输出”}
Insert调用的函数有特别的规定，函数格式必须是“smarty_insert_函数名称($params,&$smarty)”，
从insert传入的参数，会统一放到数组变量中，参数名为该数组的键值。
例子：
{insert name="maxnum" script="s2.php" x=12 y=13 assign=nn}   #模板文件，script为保存调用函数的脚本
{foreach $nn as $n}
{$n}
{/foreach}

function smarty_insert_maxnum($arr)   #函数脚本文件
{
return $arr['x']>$arr['y']?$arr['x']arr['y'];
}
如果规定了assign ，则调用函数的记过不会马上输出，输出的数据将存储到assign指定的变量里,
这样可以根据实际情况，再输出包含文件的内容。
Insert也可以定义成组件，写入组件库中，详情请参考6.8.5
4.4.8 if,elseif,else{if $name eq "Fred"}
Welcome Sir.
{elseif $name eq "Wilma"}
Welcome Ma'am.
{else}
Welcome, whatever you are.
{/if}
这个没有什么太好说的。比较操作符可以是 “==、>=”等，也可以是”eq、ne”等，这个看手册吧。
4.4.9 ldelim,rdelim这个也很简单，分别替换smarty当前规定的左边界符和右边界符。一般成对使用。
4.4.10 literalLiteral 标签区域内的数据将被当作文本处理，此时模板将忽略其内部的所有字符信息。
该特性用于显示有可能包含大括号等字符信息的 js、css 。当这些信息处于 {literal}{/literal} 标签中时，
模板引擎将不分析它们，而直接显示。
4.4.11 stripSmarty 在显示前将除去任何位于 {strip}{/strip} 标记中数据的首尾空格和回车。
4.4.12 phpphp 标签允许在模板中直接嵌入 php 脚本。 {php}标签默认是关闭的，可以通过如下方式打开
$smarty->setAllow_php_tag(true)   #设置开启识别php的标签
$smarty->getAllow_php_tag()       #获得当前对{php}的支持状态
4.4.13 for,while这是3.0新增的函数。语法类似于php，这两个函数都不适合关联数组
{for $x=0, $y=count($foo); $x<$y; $x++}  ....  {/for}
{for $x=0 to count($foo)-1 step 1}
第二种方法，支持for的内置变量。第一种不支持。
$x@iteration   #当前循环次数
$x@total     #总循环次数
$x@first  #循环第一次
$x@last     #循环最后一次

{while true}….{/while}
While没有内置变量。
4.5 系统自定义函数4.5.1 assign{assign var="name" value="韩灵稚" nocache=”false”scope=”global”}  #在模板中定义
$smarty->assign($tpl_var, $value = null, $nocache = false, $scope = SMARTY_LOCAL_SCOPE)
#在php文件中定义
nocache决定了是否需要不缓存该变量（前提是需要启动缓存）。
scope 决定了变量的作用范围，有global、parent、local
【相关函数】
$smarty->assignGlobal($varname, $value = null, $nocache = false)   #直接分配一个全局的变量
$smarty->assignByRef($tpl_var, &$value, $nocache = false, $scope = SMARTY_LOCAL_SCOPE)
  #分配一个引用变量，适合传递的变量较大，比如对象类型，可以防止内存拷贝。
$smarty->clearAssign($tpl_var)   #清楚特定的变量
$smarty->clearAllAssign()    #清除所有分配的变量

4.5.2 append3.0新增的函数，向模板中分配的变量，该变量可以接受多个值，从而成为变量数组。
$smarty->append($tpl_var, $value = null, $merge = false, $nocache = false, $scope = SMARTY_LOCAL_SCOPE)   
#php文件中
{append var="name" value="2"}    #模板文件中
例子：
$smarty->assign('nh', 'var1);   #分配一个变量模板，值为var1
$smarty->append('nh','var2');   #对同一个变量，在追加一个值。nh模板变量为数组。
{$nh[0]}  #在模板文件中使用第一个值
$merge,应该是是否合并原值，目前版本测试的时候，不起任何作用。
【相关函数】
$smarty->appendByRef($tpl_var, &$value, $merge = false)  #添加一个引用变量到模板变量中，$merge不起作用。
4.5.3 counter计数器。当第一次出现{counter}时开始计数，每次出现{counter}按照规定的计数。
{counter start=开始(1) skip=步阶(1) direction=递增/递减(up/down) print=是否显示(true) assign=输出给模板变量}
counter除了start和assign ，其他属性的设置，会对一下次的counter起作用。如果规定了assign ，
则包含文件不会马上输出，模板输出的数据将存储到assign指定的变量里, 这样可以根据实际情况，
再输出包含文件的内容。
4.5.4 cycle用于轮转使用一组值。当第一次出现{cycle}时开始，每次出现{cycle}轮换每个值。
{cycle name=名称 values=一组值 print=是否输出(true) advance=是否使用下一个值(true)
delimiter=一组值中的分隔符(,) assign=输出给模板变量}
4.5.5 debug什么也不说了，一个字强大。用了你就知道了，在需要设断点的地方写入{debug}
如果使用fetch()，则debug失效。只能使用display()。
{debug output=输出的格式(javascript/html) }   #模板声明调试,，可以选择输出的方式默认是js窗口。
$smarty->getDebugging()    #得到当前是进行调试，默认false
$smarty->setDebugging(true)    #对后续调用的模板进行调试。
$smarty->getDebug_tpl()   #获得调试所需要的tpl模板，可以自己修改。
$smarty->setDebug_tpl('new_debug.tpl')   #重新指定新的用于调试的模板

4.5.6 evaleval 按处理模板的方式计算取得变量的值。个人感觉用处不大，对缓存支持不好。
4.5.7 fetchfetch 用于从本地文件系统、HTTP或FTP上取得文件并显示文件的内容。
如果文件名称以"http://"开头，将取得该网站页面并显示。
如果文件名称以"ftp://"开头，将从ftp服务器取得该文件并显示。
{fetch file="/export/httpd/www.domain.com/docs/navbar.js"}
{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}
调用的文件内容，如果能被html解析，则会输出解析内容
【相关函数】
$smarty->fetch($template, $cache_id = null, $compile_id = null, $parent = null)  
#将模板输出的内容放入变量中，供以后使用，如果规定了编译id，
比如3，则编译后的文件名称为“3^常规名称”，缓存id同理。
$output = $smarty->fetch("index.tpl");
// do something with $output here// 对将要输出的内容进行处理
echo $output;
4.5.8 mathmath 允许模板设计者在模板中进行数学表达式运算.
{math equation=自定义公式 [var…]=变量值 format=结果格式化字符串 assign=输出给模板变量}
4.5.9 popup_init,popup输出javascript窗口。
{popup_init src="/javascripts/overlib.js"}  #popup_init载入js文件，必须的。
{popup text=”弹出信息”}     #个人感觉意义不大，参数很多，可以看chm
4.5.10 textformattextformat 用于格式化文本。该函数主要清理空格和特殊字符，对段落按单词边界换行和行缩进等段落格式化处理。
与变量调节器类似，优点是可以调整段落，参数具体看文档。
{textformat [修改参数….]}
需要修改的段落
{/textformat}
4.5.11 html_checkboxes根据函数生成checkboxes（多选）页面元素。
{html_checkboxes  name=名称(checkbox)  values=值数组  ouput=显示数组  
selected=已显示的元素或者数组，数组值为values  options=代替(value+output)可用关联数组  
separator=分隔每个复选按钮的字符串  label=是否为每个复选按钮添加 <label> 标签(true)}

{assign var=cb_values value=[1,2,3,4,5,6] scope="global"}
{assign var=cb_content value=['北京','广州','天津','石家庄','太原','济南'] scope="global"}
{assign var=cb value=['1'=>'北京','3'=>'广州','2'=>'天津','4'=>'石家庄','5'=>'太原','6'=>'济南'] scope="global"}
{assign var=cb_selected value=[1,2]}
{html_checkboxes name="checkbox" values=$cb_values output=$cb_content selected=$cb_selected
separator="|"}
{html_checkboxes name="checkbox" options=$cb selected=$cb_selected separator="|"}
4.5.12 html_image意义不大，直接写html可能会更好，不能生成img标签的id和name属性
{html_image file=图片路径和名称 border=边框 height=高度 width=宽度 alt=alt内容 href=图片url}
4.5.13 html_options{html_options  name=下拉菜单名称  values=值数组  ouput=显示数组  selected=已显示的元素  
options=代替(value+output)可用关联数组}
注意，如果没有添加name属性，需要自己加入<select></select>标记。
如果selected是一个数组且不能多选，则选择数组的最后一个值作为以选择的。
4.5.14 html_radios{html_radios  name=名称(radio)  values=值数组  ouput=显示数组  
selected=已显示的元素options=代替(value+output)可用关联数组  separator=分隔每个复选按钮的字符串}
4.5.15 html_select_date,html_select_time，html_table意义不大，有局限性，不如手写。看手册吧。
4.5.16 mailto{mailto address=发送邮箱 cc=抄送邮箱 bcc=暗送邮箱 subject=主题 text=链接内容 encode=编码形式(javascript/hex)}
具体看手册吧，测试中字符集格式转换有问题。
4.6 模板中自定义函数3.0以后可以在模板内创建函数，而不需要一定先注册或者建立组件。
{function name=函数名 [var…]=默认值}   #定义函数
函数体。。
{/function}
{call name=函数名 [var…]=传值}   #调用函数，调用函数的代码一定要放在函数定义代码之后
{函数名 [var…]=传值}    #也可以这样调用

查看 smarty3.0中文手册文档API及使用指南_1
本文摘自：http://hi.baidu.com/xunaohai/item/12669e1463fa10fd746a84c7