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