insert

Insert tags work much like include tags, except that insert tags are not cached when you have template caching enabled. They will be executed on every invocation of the template.

insert 標籤的功能與 include 標籤類似，差別在當你將樣版的 caching 開啟後 insert 標籤的內容不會被快取住，除此之外這兩個函式都能依照我們的想法而運作。

Let's say you have a template with a banner slot at the top of the page. The banner can contain any mixture of HTML, images, flash, etc. so we can't just use a static link here, and we don't want this contents cached with the page. In comes the insert tag: the template knows #banner_location_id# and #site_id# values (gathered from a config file), and needs to call a function to get the banner contents.

假設現在你有一個樣版，其上端有一個狹長的橫幅標題，這個橫幅標題可 以是 HTML, images, flash 等等的結合，所以我們不能只是使用一個靜態連結而已，且我們不 希望內容會被快取住。在 insert 標籤內：樣版可以辨認出 #banner_location_id# 與 #site_id# 的值（從組態檔中獲得），且使用一個函式就可以取得標題內容。

{* example of fetching a banner *}
{insert name="getBanner" lid=#banner_location_id# sid=#site_id#}

In this example, we are using the name "getBanner" and passing the parameters #banner_location_id# and #site_id#. Smarty will look for a function named insert_getBanner() in your PHP application, passing the values of #banner_location_id# and #site_id# as the first argument in an associative array. All insert function names in your application must be prepended with "insert_" to remedy possible function name-space conflicts. Your insert_getBanner() function should do something with the passed values and return the results. These results are then displayed in the template in place of the insert tag. In this example, Smarty would call this function: insert_getBanner(array("lid" => "12345","sid" => "67890")); and display the returned results in place of the insert tag.

在此範例中，我們使用名稱 "getBanner" 與傳遞參數 #banner_location_id# 和 #site_id#。Smarty 會在 PHP 程式當中尋找名稱為 insert_getBanner() 的函式，以關聯 陣列作為第一個參數傳 #banner_location_id# 與 #site_id# 值。所有在你的程式中插入函式 的名稱前都要以 "insert_" 為開頭用以補救可能的函式名稱空間衝突。你的 insert_getBanner() 函式必須對所傳遞的值有所動作與回傳結果，然後回傳結果在樣版中的 insert 標籤中顯示。在這個例子中，Smarty 會呼叫： insert_getBanner(array("lid" => "12345","sid" => "67890"))； 且列印出回傳結果在 insert 標籤中。

If you supply the "assign" attribute, the output of the insert tag will be assigned to this template variable instead of being output to the template. NOTE: assigning the output to a template variable isn't too useful with caching enabled.

如果你使用 "assign" 屬性，insert 標籤的輸出結果會指定給樣版變數而非 輸出給樣版。注意：當將輸出結果指定給樣版變數時開啟快取功能是沒有作用的。

If you supply the "script" attribute, this php script will be included (only once) before the insert function is executed. This is the case where the insert function may not exist yet, and a php script must be included first to make it work. The path can be either absolute, or relative to $trusted_dir. When security is enabled, the script must reside in $trusted_dir.

在使用 "script" 屬性時，php 程式碼只會在 insert 函式執行前被包含進去 一次。如此一來在還沒使用 insert 函式前且 php 程式碼又必須先行插入樣版中的狀況下，所 包含的路徑可以是絕對路徑或是相對於 $trusted_dir 的路徑，當 security 功能開啟時，程式 碼的所在位置必須包含在 $trusted_dir 設定中。

The Smarty object is passed as the second argument. This way you can reference and modify information in the Smarty object from within the insert function.

Smarty 物件被當作第二個參數傳遞，如此一來你可以參照與修改使用 insert 函式取出的 Smarty 物件中的資訊。