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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<sect1 id="language.function.include.php">
 <title>{include_php}</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>file</entry>
     <entry>string</entry>
     <entry>Yes</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>The name of the php file to include</entry>
    </row>
    <row>
     <entry>once</entry>
     <entry>boolean</entry>
     <entry>No</entry>
     <entry><emphasis>true</emphasis></entry>
     <entry>whether or not to include the php file more than
      once if included multiple times</entry>
    </row>
    <row>
     <entry>assign</entry>
     <entry>string</entry>
     <entry>No</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>The name of the variable that the output of
      include_php will be assigned to</entry>
    </row>
   </tbody>
  </tgroup>
 </informaltable>
 <note>
  <title>Technical Note</title>
  <para>
   {include_php} is pretty much deprecated from Smarty, you can
   accomplish the same functionality via a custom template function.
   The only reason to use {include_php} is if you really have a need to
   quarantine the php function away from the
   <link linkend="variable.plugins.dir">plugins</link>
   directory or your
   application code. See the <link
   linkend="tips.componentized.templates">componentized template
   example</link> for details.
  </para>
 </note>
 <para>
  {include_php} tags are used to include a php script in your template.
  If <link linkend="variable.security">security is enabled</link>,
  then the php script must be located in the <link
  linkend="variable.trusted.dir">$trusted_dir</link> path.
  The {include_php} tag must have the attribute
  "file", which contains the path to the included php file, either
  relative to
  <link linkend="variable.trusted.dir">$trusted_dir</link>,
  or an absolute path.
 </para>
 <para>
  {include_php} is a nice way to handle <link
  linkend="tips.componentized.templates">componentized templates</link>, and
  keep PHP code separate from the template files. Lets say you have a
  template that shows your site navigation, which is pulled
  dynamically from a database. You can keep your PHP logic that grabs
  database content in a separate directory, and include it at the top
  of the template. Now you can include this template anywhere without
  worrying if the database information was assigned by the application
  before hand.
 </para>
 <para>
  By default, php files are only included once even if called
  multiple times in the template. You can specify that it should be
  included every time with the <emphasis>once</emphasis> attribute.
  Setting once to false will include the php script each time it is
  included in the template.
 </para>
 <para>
  You can optionally pass the <emphasis>assign</emphasis> attribute,
  which will specify a template variable name that the output of
  <emphasis>{include_php}</emphasis> will be assigned to instead of
  displayed.
 </para>
 <para>
  The smarty object is available as $this within the PHP script that you
  include.
 </para>
 <example>
  <title>function {include_php}</title>
  <para>load_nav.php</para>
  <programlisting role="php">
<![CDATA[
<?php

// load in variables from a mysql db and assign them to the template
require_once("MySQL.class.php");
$sql = new MySQL;
$sql->query("select * from site_nav_sections order by name",SQL_ALL);
$this->assign('sections',$sql->record);

?>
]]>
  </programlisting>
  <para>
   Where index.tpl is:
  </para>
  <programlisting>
<![CDATA[
{* absolute path, or relative to $trusted_dir *}
{include_php file="/path/to/load_nav.php"}

{foreach item="curr_section" from=$sections}
  <a href="{$curr_section.url}">{$curr_section.name}</a><br />
{/foreach}
]]>
  </programlisting>
 </example>

 <para>
  See also
  <link linkend="language.function.include">{include}</link>,
   <link linkend="language.function.php">{php}</link>,
    <link linkend="language.function.capture">{capture}</link>,
    <link linkend="template.resources">Template Resources</link> and
    <link linkend="tips.componentized.templates">Componentized Templates</link>
 </para>

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