3.0.x使用指南 · smarty3中文手冊

<table summary="Header navigation table" width="100%" border="0" cellpadding="0" cellspacing="0"><tr><th colspan="3" align="center">Smarty - the compiling PHP template engine</th></tr><tr><td width="25%" align="left" valign="bottom"><a href="smarty3.smarty2.bc.notes.html" accesskey="P">Prev</a></td><td width="50%" align="center" valign="bottom">Smarty3.0.x Installation Package</td><td width="25%" align="right" valign="bottom"><a href="list.html">Next</a></td></tr></table> # README[ 3.0.x使用指南] Smarty 3.0.8 Author: Monte Ohrt <monte at ohrt dot com > Author: Uwe Tews 澤注 | 因原英文章節太長，已去掉，只留翻譯的文字。 | |-----| smarty3 說明 3.0.5版本發布說明：現在smarty版本隨著php默認error_reporting級別的發展進行改進，如果php（模版）未注明E_NOTICE，而你又試圖使用一個未定義的變量，你將會得到一個E_NOTICE警告。如果不習慣這種改變可以設置回以前的模式： $smarty->error_reporting = E_ALL & ~E_NOTICE; 3.0發布說明：一些API在由RC4（過渡）到3.0發布版時進行了調整。我們覺得現在作改變會比等3.0發布后再調整好，到3.1時必須立即放棄這些舊的API。在網上可以找到新手冊，里面有關于兩者不同的介紹。不同之處： ---API由RC4到3.0版的改變--- $smarty->register->* $smarty->unregister->* $smarty->utility->* $samrty->cache->* 上述API全部改為調用內置方法，例如： $smarty->clearAllCache() $smarty->registerFoo() $smarty->unregisterFoo() $smarty->testInstall() 等等函數、塊、編譯器、插件調節器的注冊、注銷合并到由下面兩個API調用： $smarty->registerPlugin(...) $smarty->unregisterPlugin(...) pre、post、output和變量過濾器的注冊、注銷合并到由下面兩個API調用： $smarty->registerFilter(...) $smarty->unregisterFilter(...) 關于所有具體的變化，請參考在線手冊 ---- 為了一致性和模塊化，Smarty3的API已經重構了語法。仍然支持Smarty2 API語法，但會拋出一個過時提示。你可以屏蔽提示，不過嚴重推薦調整到Smarty3語法，因為Smarty2語法必須通過一個額外的包裝器改道運行。基本上，現在所有Smarty方法改用“fooBarBaz”式駝峰語法命名。同時，現在所有Smarty屬性可取和可設，例如，$smarty->cache_dir屬性可用$smarty->setCacheDir('foo/')設置，而且可用$smarty->getCacheDir()取回值。一些Smarty3的API廢除了諸如“is*”格式的方法，因為這些方法只是現在的“get*”方法的復制函數，所以沒必要存在重復的方法/函數。下面這些是Smarty3 API的大致綱要： <table border="0" bgcolor="#E0E0E0" width="100%"><tr><td>$smarty->fetch($template, $cache_id = null, $compile_id = null, $parent = null) $smarty->display($template, $cache_id = null, $compile_id = null, $parent = null) $smarty->isCached($template, $cache_id = null, $compile_id = null) $smarty->createData($parent = null) $smarty->createTemplate($template, $cache_id = null, $compile_id = null, $parent = null) $smarty->enableSecurity() $smarty->disableSecurity() $smarty->setTemplateDir($template_dir) $smarty->addTemplateDir($template_dir) $smarty->templateExists($resource_name) $smarty->loadPlugin($plugin_name, $check = true) $smarty->loadFilter($type, $name) $smarty->setExceptionHandler($handler) $smarty->addPluginsDir($plugins_dir) $smarty->getGlobal($varname = null) $smarty->getRegisteredObject($name) $smarty->getDebugTemplate() $smarty->setDebugTemplate($tpl_name) $smarty->assign($tpl_var, $value = null, $nocache = false) $smarty->assignGlobal($varname, $value = null, $nocache = false) $smarty->assignByRef($tpl_var, &$value, $nocache = false) $smarty->append($tpl_var, $value = null, $merge = false, $nocache = false) $smarty->appendByRef($tpl_var, &$value, $merge = false) $smarty->clearAssign($tpl_var) $smarty->clearAllAssign() $smarty->configLoad($config_file, $sections = null) $smarty->getVariable($variable, $_ptr = null, $search_parents = true, $error_enable = true) $smarty->getConfigVariable($variable) $smarty->getStreamVariable($variable) $smarty->getConfigVars($varname = null) $smarty->clearConfig($varname = null) $smarty->getTemplateVars($varname = null, $_ptr = null, $search_parents = true) $smarty->clearAllCache($exp_time = null, $type = null) $smarty->clearCache($template_name, $cache_id = null, $compile_id = null, $exp_time = null, $type = null) $smarty->registerPlugin($type, $tag, $callback, $cacheable = true, $cache_attr = array()) $smarty->registerObject($object_name, $object_impl, $allowed = array(), $smarty_args = true, $block_methods = array()) $smarty->registerFilter($type, $function_name) $smarty->registerResource($resource_type, $function_names) $smarty->registerDefaultPluginHandler($function_name) $smarty->registerDefaultTemplateHandler($function_name) $smarty->unregisterPlugin($type, $tag) $smarty->unregisterObject($object_name) $smarty->unregisterFilter($type, $function_name) $smarty->unregisterResource($resource_type) $smarty->compileAllTemplates($extention = '.tpl', $force_compile = false, $time_limit = 0, $max_errors = null) $smarty->clearCompiledTemplate($resource_name = null, $compile_id = null, $exp_time = null) $smarty->testInstall() //所有getters/setters，對所有屬性有效，下面是一小部份： $caching = $smarty->getCaching(); // get $smarty->caching $smarty->setCaching(true); // set $smarty->caching $smarty->setDeprecationNotices(false); // set $smarty->deprecation_notices $smarty->setCacheId($id); // set $smarty->cache_id $debugging = $smarty->getDebugging(); // get $smarty->debugging </td> </tr></table> 文件結構 Smarty3的文件結構與Smarty2非常相似： | ~~~ /libs/ Smarty.class.php /libs/sysplugins/ internal.* /libs/plugins/ function.mailto.php modifier.escape.php ... ~~~ | |-----| 很多Smarty3的核心功能位于sysplugins目錄；你不必更改這里的文件。/libs/plugins/放置Smarty插件。你可以將自己的插件放進來，或者建立一個獨立的插件目錄，這些與Smarty2一樣。你仍然需要建立自己的/cache/、/templates/、 /templates_c/、/configs/文件夾。確定/cache/和/templates_c/可寫。 Smarty3的典型使用方式看起來應該也很熟悉： | ~~~ require('Smarty.class.php'); $smarty = new Smarty; $smarty->assign('foo','bar'); $smarty->display('index.tpl'); ~~~ | |-----| 然而，Smarty3內部的工作方式完全不同。Smarty3大部份向后兼容Smarty2，除了下面內容： *) Smarty3只適用于php5，不再支持php4。 *) [{php｝](#)默認情況下關閉，如果確實需要可以設置$marty->allow_php_tag = true。 *) 分隔符內左右出現空格符時將不再當作Smarty標簽對待，因此{ foo }會被Smarty忽略，但{foo}則可識別。這個改變是為javascript/css讓路，但前述改變不包括必須用到的[{literal}](#)，這個特性可用設置$smarty->auto_literal = false去掉。 *) Smarty3 API有點不同。大部份Smarty2 API已被棄用，但仍能工作。你應該升級到Smarty3，以發揮最大效能。 Smarty3有很多新事物，這里列下重要的清單：語法分析/解析器 ============ Smarty3提供了一個語法分析器給解析器/編譯器。從根本上說，這意味著Smarty有一些附加語法讓工作更輕松，例如模板內計算、簡寫/直觀函數參數選項、無窮函數遞歸、更多精確錯誤處理等等。 Smarty模板語法有什么新變化 ===================== Smarty3允許在任何地方放置表達式。表達式可以包含php函數，只要沒有被安全策略、對象方法、對象屬性等這些禁止。{math}插件不再是必須，但仍向前支持。 | ~~~ Examples:{$x+$y} 輸出x、y的和{$foo = strlen($bar)} 表達式用在賦值函數{assign var=foo value= $x+$y} 表達式作為屬性{$foo = myfunct( ($x+$y)*3 )} 作為函數參數{$foo[$x+3]} 作為數組索引 ~~~ | |-----| Smarty標簽可以作為值包含進其它標簽內。 | ~~~ Example: {$foo={counter}+3} ~~~ | |-----| Smarty標簽同樣可以用在雙引號字符串內。 | ~~~ Example: {$foo="this is message {counter}"} ~~~ | |-----| 你可以在模板內定義數組。 | ~~~ Examples: {assign var=foo value=[1,2,3]} {assign var=foo value=['y'=>'yellow','b'=>'blue']} Arrays can be nested. 數組可以嵌套 {assign var=foo value=[1,[9,8],3]} ~~~ | |-----| 這是個分配變量（變量賦值）的新簡寫語法方式。 | ~~~ Example: {$foo=$bar+2} ~~~ | |-----| 可以為一個指定的數組元素賦值。如果變量存在但不是數組，那么在賦值之前將會自動轉為數組。 | ~~~ Examples: {$foo['bar']=1} {$foo['bar']['blar']=1} ~~~ | |-----| 可以添加一個值到數組。如果變量存在但不是數組，那么在賦值之前將會自動轉為數組。 | ~~~ Example: {$foo[]=1} ~~~ | |-----| 可以使用php式的語法訪問數組元素，同樣支持原始的dot（.）符號。 | ~~~ Examples:{$foo[1]} 普通訪問形式{$foo['bar']}{$foo['bar'][1]}{$foo[$x+$x]} 下標（索引）可以包含任何表達式{$foo[$bar[1]]} 嵌套下標{$foo[section_name]} 訪問Smarty配置文件的節塊名，而不是訪問數組！ ~~~ | |-----| 保留原始的“.”符號，但有改進 | ~~~ Examples:{$foo.a.b.c} => $foo['a']['b']['c'] {$foo.a.$b.c} => $foo['a'][$b]['c'] 用于變量索引{$foo.a.{$b+4}.c} => $foo['a'][$b+4]['c'] 用表達式作索引{$foo.a.{$b.c}} => $foo['a'][$b['c']] 用于嵌套索引 ~~~ | |-----| 注意當嵌套“.”索引時，“{”和“}”用于分清模棱兩可、容易產生岐義的地址邊界。變量名本身可以是變量（類似php5中的可變變量）和可以包含表達式。 | ~~~ Examples:$foo 普通變量$foo_{$bar} 變量名包含其它變量 $foo_{$x+$y} 變量名包含表達式$foo_{$bar}_buh_{$blar} 多段變量名{$foo_{$x}} 如果$x值為1，則輸出變量$foo_1。 ~~~ | |-----| 執行對象方法鏈 | ~~~ Example: {$object->method1($x)->method2($y)} ~~~ | |-----| {for}標簽被加入到循環（替換{section}標簽）: {for $x=0, $y=count($foo); $x<$y; $x++} .... {/for} 在{for}中，許多語句可用空格隔開，作為第一個表達式。 {for $x = $start to $end step $step} ... {/for}用來求和。同樣可用： {for $x = $start to $end} ... {/for} 在這種情況下，step值會依start和end的值自動加1或減1。你也可以用表達式來替換$start和$end變量。在循環里面可以訪問下面的這些特殊變量： $x@iteration = 迭代（循環）次數 $x@total = 總的迭代（循環、遍歷）數 $x@first = 如果是第一個迭代則為true $x@last = 如果為最后一個迭代則為true Smarty2的{section}語法仍受支持。新的短式{foreach}語法遍歷數組。 | ~~~ Example: {foreach $myarray as $var}...{/foreach} ~~~ | |-----| 遍歷循環里面，通過下列方式訪問屬性： $var@key 遍歷$var數組鍵 $var@iteration 遍歷當前迭代count (1,2,3...) $var@index 遍歷當前索引count (0,1,2...) $var@total 遍歷$var數組總數 $var@first 如果是第一個迭代則返回true $var@last 如果是最后一個迭代則返回true Smarty2{foreach}標簽語法仍受支持。注意 | {$bar[foo]}的意思仍然是名為foo的{section}里面的一個變量。如果你想通過索引foo訪問數組元素，必須用引號，如{$bar['foo']}，或者使用“.”語法{$bar.foo}。 | |-----| 這樣執行while塊標簽： {while $foo}...{/while} {while $x lt 10}...{/while} 直接訪問php函數：正如你可以直接使用php函數作為調節器，你現在可以直接訪問php函數，假如安全設置為允許的話： | ~~~ {time()} ~~~ | |-----| 現在有個新的{function}...{/function}塊標簽執行模板函數。它允許像插件函數一樣重用代碼序列。它可以調用自身遞歸。模板函數必須經由新的{call name=foo...}標簽調用。 <table border="0" bgcolor="#E0E0E0" width="100%"><tr><td>Example: Template file: {function name=menu level=0} <ul class="level{$level}"> {foreach $data as $entry} {if is_array($entry)} <li>{$entry@key}</li> {call name=menu data=$entry level=$level+1} {else} <li>{$entry}</li> {/if} {/foreach} </ul> {/function} {$menu = ['item1','item2','item3' => ['item3-1','item3-2','item3-3' => ['item3-3-1','item3-3-2']],'item4']} {call name=menu data=$menu} Generated output: * item1 * item2 * item3 --o item3-1 --o item3-2 --o item3-3 ----+ item3-3-1 ----+ item3-3-2 * item4 </td> </tr></table> 函數標簽必須有“name”屬性，調用函數時“name”為標簽名。函數標簽可以有若干附加屬性。這些屬性默認由局部變量設置。新[{nocache}](#)塊函數：當模板啟用緩存時，{nocache}...{/nocache}必須指明模板節塊（section）不緩存。新nocache屬性：你可以通過nocache屬性指明變量/函數禁止輸出緩存。 <table border="0" bgcolor="#E0E0E0" width="100%"><tr><td>Examples: {$foo nocache=true} {$foo nocache} /* same */ {foo bar="baz" nocache=true} {foo bar="baz" nocache} /* same */ {time() nocache=true} {time() nocache} /* same */ </td> </tr></table> 或者你可以在腳本中像這樣分配不緩存變量： $smarty->assign('foo',$something,true); //第三個參數為nocache設置 [$smarty.current_dir](#)返回當前模板目錄名。你可以通過“string”[資源](#)類型使用直接字符串作為模板。 | ~~~ Examples:$smarty->display('string:This is my template, {$foo}!'); // php{include file="string:This is my template, {$foo}!"} // template ~~~ | |-----| 變量作用域 / 變量貯存 ================ 在Smarty2中，所有賦值變量全部貯存在Smarty對象里面。因此，所有在php里面分配的變量是后面通過調用fetch和display模板來訪問的。在smarty3中，我們可以選擇分配變量給主Smarty對象、自建數據對象和自建模板對象，這些對象支持鏈式。這些對象在鏈的末尾可以訪問所有模板變量和父對象里面的所有變量。 Smarty對象只能作為鏈的根，但鏈可以從Smarty對象中分離出來。所有已知Smarty分配接口將作用于數據和模板對象。除此之外，上述對象同時還是個特殊的全局變量存區。可像下面一樣建立一個Smarty數據對象： <table border="0" bgcolor="#E0E0E0" width="100%"><tr><td>$data = $smarty->createData(); // 建立根數據對象 $data->assign('foo','bar'); // 像平常一樣分配變量 $data->config_load('my.conf'); // 加載配置文件 $data= $smarty->createData($smarty); // 建立一個有父對象的數據對象，該父對象為Smarty對象 $data2= $smarty->createData($data); // 建立一個有父對象的數據對象，該父對象為$data數據對象</td> </tr></table> 可以使用createTemplate方法建立模板對象。它有與[fetch()](#)或[display()](#)方法一樣的分配參數。函數定義： function createTemplate($template, $cache_id = null, $compile_id = null, $parent = null) 第一個參數可以是模板名、Smarty對象或數據對象。 <table border="0" bgcolor="#E0E0E0" width="100%"><tr><td>Examples: $tpl = $smarty->createTemplate('mytpl.tpl'); // 建立一個不用$parent的模板對象 $tpl->assign('foo','bar'); // 直接分配變量 $tpl->config_load('my.conf'); // 加載配置文件 $tpl = $smarty->createTemplate('mytpl.tpl',$smarty); // 建立模板，帶parent，鏈至Smarty對象 $tpl = $smarty->createTemplate('mytpl.tpl',$data); // 建立模板，帶parent，鏈至$data對象</td> </tr></table> 標準的fetch()和display()方法會暗中建立一個模板對象。如果$parent參數沒有在這些方法調用中指明，那么模板對象會鏈回Smarty對象作為parent。如果模板被另一個模板通過{include...}標簽調用，那么子模板鏈回調用它的模板作為parent。可訪問所有局部變量或父模板變量。如果模板通過使用{assign var=foo...}或{$foo=...}標簽建立或修改一個變量，這些新變量也只有局部作用域。當退出模板時，新變量或修改后的變量在父模板中不可見。在Smarty2中具有同樣行為。（不過在）在Smarty3中我們（多了件武器），可以通過*scope*屬性分配變量，這樣就允許這些新變量或修改后的變量具有全局作用域的可訪問性（如在父模板中可見）。 scopes的可能值為*local*、*parent*、*root*和*global*。 <table border="0" bgcolor="#E0E0E0" width="100%"><tr><td>Examples: {assign var=foo value='bar'} // 沒有指定scope，默認為‘local’ {$foo='bar'} // 同上 {assign var=foo value='bar' scope='local'} // 同上，local作用域 {assign var=foo value='bar' scope='parent'} // 父模板可以訪問該值 {$foo='bar' scope='parent'} // （普通的調用模板） {assign var=foo value='bar' scope='root'} // 值將輸出到根對象， {$foo='bar' scope='root'} // 因此該值在使用同一根的所有模板中可見 {assign var=foo value='bar' scope='global'} // 值將輸送至全局變量存區 {$foo='bar' scope='global'} // 這些值在任何、所有模板中可見</td> </tr></table> scope屬性同樣可附加至[{include...}](#)標簽中。在這種情況下，指定scope則指定包含模板里面所有已分配變量具有同樣作用域。插件 === Smarty3使用與Smarty2一樣的編碼規則。不同之處在于前者將模板對象作為第三個參數傳遞（到插件）。 smarty_plugintype_name (array $params, object $smarty, object $template) 仍然兼容Smarty2插件，只要這些插件沒有使用特殊的Smarty2內部結構。模板繼承： ======= 通過模板繼承你可以定義塊，這些塊區域可被子模板覆蓋，因此，你的模板可以這樣做： <table border="0" bgcolor="#E0E0E0" width="100%"><tr><td>parent.tpl: <html> <head> <title>{block name='title'}My site name{/block}</title> </head> <body> <h1>{block name='page-title'}Default page title{/block}</h1> <div id="content"> {block name='content'} Default content {/block} </div> </body> </html> child.tpl: {extends file='parent.tpl'} {block name='title'} Child title {/block} grandchild.tpl: {extends file='child.tpl'} {block name='title'}Home - {$smarty.block.parent}{/block} {block name='page-title'}My home{/block} {block name='content'} {foreach $images as $img} <img src="{$img.url}" alt="{$img.description}" /> {/foreach} {/block}</td> </tr></table> 我們在這里重定義了所有塊，然而，在標題塊方面我們用了[{$smarty.block.parent}](#)，它告訴Smarty，在這塊地方插入取自父模板的默認內容。內容塊被顯示的圖像文件覆蓋，同時，頁面標題同樣被不同的標題所覆蓋。如果渲染grandchild.tpl須取得這些： | ~~~ <html> <head> <title>Home - Child title</title> </head> <body> <h1>My home</h1> <div id="content"> <img src="/example.jpg" alt="image" /> <img src="/example2.jpg" alt="image" /> <img src="/example3.jpg" alt="image" /> </div> </body></html> ~~~ | |-----| 注意 | 在子模板中，{extends}或{block}標簽節塊外的所有內容被忽略。 | |-----| 繼承樹大小沒有規定，只要你愿意你想搞多大都可以（意為你繼承的文件上面有個父文件，父文件上面可以有個爺文件，爺文件上面有個曾祖父文件...生生不息無窮盡），但需要注意所有文件都必須在運行時檢查修改設置，更多的繼承意味著更大的開銷。不用在子模板文件中使用{extends}標簽定義parent/child關系，你可以像下面一樣使用資源： $smarty->display('extends:parent.tpl|child.tpl|grandchild.tpl'); 子{block}標簽有*append*添加、*prepend*追加兩個可選屬性。在這樣的情況下，父塊內容可添加或追加子塊內容。 {block name='title' append} My title {/block} php數據流： ======== (see online documentation) 參見在線手冊變量過濾器： ========= (see online documentation) 參見在線手冊訪問靜態類與命名空間支持 =================== 你可以在模板中通過namespace命名空間選項注冊類，如下： $smarty->register->templateClass('foo','name\name2\myclass'); 在模板中像這樣使用： | ~~~ {foo::method()} 等等 ~~~ | |-----| ======================= Please look through it and send any questions/suggestions/etc to the forums. 瀏覽下面這個網址，在論壇中發表任何問題、建議等 [http://www.phpinsider.com/smarty-forum/viewtopic.php?t=14168](http://www.phpinsider.com/smarty-forum/viewtopic.php?t=14168) Monte and Uwe <table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0"><tr><td width="33%" align="left" valign="top"><a href="smarty3.smarty2.bc.notes.html" accesskey="P">Prev</a></td><td width="34%" align="center" valign="top"><a href="index.html" accesskey="H">Home</a></td><td width="33%" align="right" valign="top"><a href="list.html">Next</a></td></tr><tr><td width="33%" align="left" valign="top">SMARTY2_BC_NOTES 2.x版本升級至3.x版本的提示</td><td width="34%" align="center" valign="top"><a href="appendixes.html" accesskey="U">Up</a></td><td width="33%" align="right" valign="top">LIST 翻譯人員列表</td></tr></table>