{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.

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.

{* 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.

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.

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.

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.