smarty/docs/en/designers/language-builtin-functions/language-function-insert.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
		<sect1 id="language.function.insert">
			<title>insert</title>
            <informaltable frame="all">
                <tgroup cols="5">
                <colspec colname="param" align="center" />
                <colspec colname="type" align="center" />
                <colspec colname="required" align="center" />
                <colspec colname="default" align="center" />
                <colspec colname="desc" />
                <thead>
                    <row>
                        <entry>Attribute Name</entry>
                        <entry>Type</entry>
                        <entry>Required</entry>
                        <entry>Default</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>name</entry>
                        <entry>string</entry>
                        <entry>Yes</entry>
                        <entry><emphasis>n/a</emphasis></entry>
                        <entry>The name of the insert function (insert_name)</entry>
                    </row>
                    <row>
                        <entry>assign</entry>
                        <entry>string</entry>
                        <entry>No</entry>
                        <entry><emphasis>n/a</emphasis></entry>
                        <entry>The name of the template variable the output will
						be assigned to</entry>
                    </row>
                    <row>
                        <entry>script</entry>
                        <entry>string</entry>
                        <entry>No</entry>
                        <entry><emphasis>n/a</emphasis></entry>
                        <entry>The name of the php script that is included before
						the insert function is called</entry>
                    </row>
                    <row>
                        <entry>[var ...]</entry>
                        <entry>[var type]</entry>
                        <entry>No</entry>
                        <entry><emphasis>n/a</emphasis></entry>
                        <entry>variable to pass to insert function</entry>
                    </row>
                </tbody>
                </tgroup>
            </informaltable>
			<para>
			Insert tags work much like include tags, except that insert tags
			are not cached when you have template <link
			linkend="caching">caching</link> enabled. They will be
			executed on every invocation of the template.
			</para>
            <para>
             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.
			</para>
<example>
<title>function insert</title>
<programlisting>
{* example of fetching a banner *}
{insert name="getBanner" lid=#banner_location_id# sid=#site_id#}</programlisting>
</example>
			<para>
			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.
			</para>
			<para>
			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.
			</para>
			<para>
			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.
			</para>
			<para>
			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.
			</para>
			<note>
			<title>Technical Note</title>
			<para>
            It is possible to have portions of the template not
            cached. If you have <link linkend="caching">caching</link>
            turned on, insert tags will not be cached. They will run
            dynamically every time the page is created, even within cached
            pages. This works good for things like banners, polls, live
            weather, search results, user feedback areas, etc.
			</para>
			</note>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->