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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<sect1 id="language.function.include">
 <title>{include}</title>
 <para>
  {include} tags are used for including other templates in the current
  template. Any variables available in the current template are also
  available within the included template. The {include} tag must have
  the attribute "file", which contains the template resource path.
 </para>
 <para>
  You can optionally pass the <emphasis>'assign'</emphasis> attribute,
  which will specify a template variable name that the output of
  {include} will be assigned to instead of
  displayed.
 </para>
 <para>
  All assigned variables' values are restored after the scope of the
  included template is left. This means you can use all variables from
  the including template inside the included template. But changes to
  variables inside the included template are not visible inside the
  including template after the {include} statement.
 </para>
 <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 template file to include</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 will be assigned to</entry>
    </row>
    <row>
     <entry>[var ...]</entry>
     <entry>[var type]</entry>
     <entry>No</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>variable to pass local to template</entry>
    </row>
   </tbody>
  </tgroup>
 </informaltable>

 <example>
  <title>function {include}</title>
  <programlisting>
<![CDATA[
<html>
<head>
  <title>{$title}</title>
</head>
<body>
{include file='page_header.tpl'}

{* body of template goes here *}
{include file="$tpl_name.tpl"} <-- will replace $tpl_name with value

{include file='page_footer.tpl'}
</body>
</html>
]]>
  </programlisting>
 </example>
 <para>
  You can also pass variables to included templates as 
  <link linkend="language.syntax.attributes">attributes</link>.
  Any variables explicitly passed to an included template as
  attributes are only available within the scope of the included
  file. Attribute variables override current template variables, in
  the case they are named alike.
 </para>
 <example>
  <title>{include} passing variables</title>
  <programlisting>
<![CDATA[
{include file='header.tpl' title='Main Menu' table_bgcolor='#c0c0c0'}

{* body of template goes here *}

{include file='footer.tpl' logo='http://my.example.com/logo.gif'}
]]>
  </programlisting>
  <para>where header.tpl could be</para>
<programlisting>
<![CDATA[
<table border='1' width='100%' bgcolor='{$table_bgcolor|default:"#0000FF"}'>
  <tr><td>
    <h1>{$title}</h1>
  </td></tr>
</table>
]]>
</programlisting>
 </example>


  <example>
   <title>{include} and assign to variable</title>
   <para>This example assigns the contents of nav.tpl to the $navbar variable,
   which is then output at the top and bottom of the page.
   </para>
   <programlisting>
 <![CDATA[
<body>
{include file='nav.tpl' assign=navbar}
{include file='header.tpl' title='Main Menu' table_bgcolor='#effeef'}
{$navbar}

{* body of template goes here *}

{include file='footer.tpl' logo='http://my.example.com/logo.gif'}
{$navbar}
</body>
]]>
   </programlisting>
 </example>


 <para>
  Use the syntax for <link
  linkend="template.resources">template resources</link> to
  include files outside of the <link linkend="variable.template.dir">$template_dir</link>
  directory.
 </para>
 <example>
  <title>{include} template resource examples</title>
  <programlisting>
<![CDATA[
{* absolute filepath *}
{include file='/usr/local/include/templates/header.tpl'}

{* absolute filepath (same thing) *}
{include file='file:/usr/local/include/templates/header.tpl'}

{* windows absolute filepath (MUST use "file:" prefix) *}
{include file='file:C:/www/pub/templates/header.tpl'}

{* include from template resource named "db" *}
{include file='db:header.tpl'}

{* include a $variable template - eg $module = 'contacts' *}
{include file="$module.tpl"} 
{* wont work as its single quotes ie no variable substitution *}
{include file='$module.tpl'}

]]>
  </programlisting>
 </example>
 <para>
  See also
  <link linkend="language.function.include.php">{include_php}</link>,
  <link linkend="language.function.insert.php">{insert}</link>,
  <link linkend="language.function.php">{php}</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
-->
banana split 2004-04-13 08:46:28 +00:00			`<?xml version="1.0" encoding="iso-8859-1"?>`
			`<!-- $Revision$ -->`
* some wz * no tab * add Cdata section 2005-05-10 20:54:42 +00:00			`<sect1 id="language.function.include">`
more patches from Peter: more linking and improvement of examples. thanks :) 2005-05-25 19:13:20 +00:00			`<title>{include}</title>`
added explanation of variables' scope within {include} 2005-12-09 15:30:13 +00:00			`<para>`
			`{include} tags are used for including other templates in the current`
			`template. Any variables available in the current template are also`
			`available within the included template. The {include} tag must have`
			`the attribute "file", which contains the template resource path.`
			`</para>`
			`<para>`
			`You can optionally pass the <emphasis>'assign'</emphasis> attribute,`
			`which will specify a template variable name that the output of`
			`{include} will be assigned to instead of`
			`displayed.`
			`</para>`
			`<para>`
			`All assigned variables' values are restored after the scope of the`
			`included template is left. This means you can use all variables from`
			`the including template inside the included template. But changes to`
			`variables inside the included template are not visible inside the`
			`including template after the {include} statement.`
Moved description to top of page and some tweaks 2005-09-13 18:41:44 +00:00			`</para>`
* some wz * no tab * add Cdata section 2005-05-10 20:54:42 +00:00			`<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 template file to include</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 will be assigned to</entry>`
			`</row>`
			`<row>`
			`<entry>[var ...]</entry>`
			`<entry>[var type]</entry>`
			`<entry>No</entry>`
			`<entry><emphasis>n/a</emphasis></entry>`
			`<entry>variable to pass local to template</entry>`
			`</row>`
			`</tbody>`
			`</tgroup>`
			`</informaltable>`
Moved description to top of page and some tweaks 2005-09-13 18:41:44 +00:00
* some wz * no tab * add Cdata section 2005-05-10 20:54:42 +00:00			`<example>`
more linking and WS from Peter 2005-05-27 16:25:02 +00:00			`<title>function {include}</title>`
* some wz * no tab * add Cdata section 2005-05-10 20:54:42 +00:00			`<programlisting>`
			`<![CDATA[`
more linking and WS from Peter 2005-05-27 16:25:02 +00:00			`<html>`
			`<head>`
			`<title>{$title}</title>`
			`</head>`
			`<body>`
Moved description to top of page and some tweaks 2005-09-13 18:41:44 +00:00			`{include file='page_header.tpl'}`
banana split 2004-04-13 08:46:28 +00:00
more linking and WS from Peter 2005-05-27 16:25:02 +00:00			`{* body of template goes here *}`
Moved description to top of page and some tweaks 2005-09-13 18:41:44 +00:00			`{include file="$tpl_name.tpl"} <-- will replace $tpl_name with value`
banana split 2004-04-13 08:46:28 +00:00
Moved description to top of page and some tweaks 2005-09-13 18:41:44 +00:00			`{include file='page_footer.tpl'}`
more linking and WS from Peter 2005-05-27 16:25:02 +00:00			`</body>`
			`</html>`
* some wz * no tab * add Cdata section 2005-05-10 20:54:42 +00:00			`]]>`
			`</programlisting>`
			`</example>`
			`<para>`
minor tweaks 2006-02-17 22:19:14 +00:00			`You can also pass variables to included templates as`
			`<link linkend="language.syntax.attributes">attributes</link>.`
* some wz * no tab * add Cdata section 2005-05-10 20:54:42 +00:00			`Any variables explicitly passed to an included template as`
			`attributes are only available within the scope of the included`
			`file. Attribute variables override current template variables, in`
			`the case they are named alike.`
			`</para>`
			`<example>`
more linking and WS from Peter 2005-05-27 16:25:02 +00:00			`<title>{include} passing variables</title>`
* some wz * no tab * add Cdata section 2005-05-10 20:54:42 +00:00			`<programlisting>`
			`<![CDATA[`
Moved description to top of page and some tweaks 2005-09-13 18:41:44 +00:00			`{include file='header.tpl' title='Main Menu' table_bgcolor='#c0c0c0'}`
banana split 2004-04-13 08:46:28 +00:00
more linking and WS from Peter 2005-05-27 16:25:02 +00:00			`{* body of template goes here *}`
banana split 2004-04-13 08:46:28 +00:00
Moved description to top of page and some tweaks 2005-09-13 18:41:44 +00:00			`{include file='footer.tpl' logo='http://my.example.com/logo.gif'}`
* some wz * no tab * add Cdata section 2005-05-10 20:54:42 +00:00			`]]>`
			`</programlisting>`
more linking and WS from Peter 2005-05-27 16:25:02 +00:00			`<para>where header.tpl could be</para>`
			`<programlisting>`
			`<![CDATA[`
			`<table border='1' width='100%' bgcolor='{$table_bgcolor\|default:"#0000FF"}'>`
			`<tr><td>`
			`<h1>{$title}</h1>`
			`</td></tr>`
			`</table>`
			`]]>`
			`</programlisting>`
* some wz * no tab * add Cdata section 2005-05-10 20:54:42 +00:00			`</example>`
more linking and WS from Peter 2005-05-27 16:25:02 +00:00

			`<example>`
			`<title>{include} and assign to variable</title>`
Clean up WS, more linking and examples 2005-06-05 19:46:19 +00:00			`<para>This example assigns the contents of nav.tpl to the $navbar variable,`
			`which is then output at the top and bottom of the page.`
more linking and WS from Peter 2005-05-27 16:25:02 +00:00			`</para>`
			`<programlisting>`
			`<![CDATA[`
			`<body>`
Moved description to top of page and some tweaks 2005-09-13 18:41:44 +00:00			`{include file='nav.tpl' assign=navbar}`
			`{include file='header.tpl' title='Main Menu' table_bgcolor='#effeef'}`
more linking and WS from Peter 2005-05-27 16:25:02 +00:00			`{$navbar}`

			`{* body of template goes here *}`

Moved description to top of page and some tweaks 2005-09-13 18:41:44 +00:00			`{include file='footer.tpl' logo='http://my.example.com/logo.gif'}`
more linking and WS from Peter 2005-05-27 16:25:02 +00:00			`{$navbar}`
			`</body>`
Clean up WS, more linking and examples 2005-06-05 19:46:19 +00:00			`]]>`
more linking and WS from Peter 2005-05-27 16:25:02 +00:00			`</programlisting>`
			`</example>`


* some wz * no tab * add Cdata section 2005-05-10 20:54:42 +00:00			`<para>`
			`Use the syntax for <link`
			`linkend="template.resources">template resources</link> to`
updates by Peter Morgan: more cross-linking better distinction between {assign} and assign() and {fetch} and fetch() 2005-05-24 14:01:49 +00:00			`include files outside of the <link linkend="variable.template.dir">$template_dir</link>`
			`directory.`
* some wz * no tab * add Cdata section 2005-05-10 20:54:42 +00:00			`</para>`
			`<example>`
more linking and WS from Peter 2005-05-27 16:25:02 +00:00			`<title>{include} template resource examples</title>`
* some wz * no tab * add Cdata section 2005-05-10 20:54:42 +00:00			`<programlisting>`
			`<![CDATA[`
more linking and WS from Peter 2005-05-27 16:25:02 +00:00			`{* absolute filepath *}`
Moved description to top of page and some tweaks 2005-09-13 18:41:44 +00:00			`{include file='/usr/local/include/templates/header.tpl'}`
banana split 2004-04-13 08:46:28 +00:00
more linking and WS from Peter 2005-05-27 16:25:02 +00:00			`{* absolute filepath (same thing) *}`
Moved description to top of page and some tweaks 2005-09-13 18:41:44 +00:00			`{include file='file:/usr/local/include/templates/header.tpl'}`
banana split 2004-04-13 08:46:28 +00:00
more linking and WS from Peter 2005-05-27 16:25:02 +00:00			`{* windows absolute filepath (MUST use "file:" prefix) *}`
Moved description to top of page and some tweaks 2005-09-13 18:41:44 +00:00			`{include file='file:C:/www/pub/templates/header.tpl'}`
banana split 2004-04-13 08:46:28 +00:00
more linking and WS from Peter 2005-05-27 16:25:02 +00:00			`{* include from template resource named "db" *}`
Moved description to top of page and some tweaks 2005-09-13 18:41:44 +00:00			`{include file='db:header.tpl'}`

			`{* include a $variable template - eg $module = 'contacts' *}`
			`{include file="$module.tpl"}`
			`{* wont work as its single quotes ie no variable substitution *}`
			`{include file='$module.tpl'}`

* some wz * no tab * add Cdata section 2005-05-10 20:54:42 +00:00			`]]>`
			`</programlisting>`
			`</example>`
			`<para>`
			`See also`
			`<link linkend="language.function.include.php">{include_php}</link>,`
minor tweaks 2006-02-17 22:19:14 +00:00			`<link linkend="language.function.insert.php">{insert}</link>,`
* some wz * no tab * add Cdata section 2005-05-10 20:54:42 +00:00			`<link linkend="language.function.php">{php}</link>,`
more linking and WS from Peter 2005-05-27 16:25:02 +00:00			`<link linkend="template.resources">Template Resources</link> and`
* some wz * no tab * add Cdata section 2005-05-10 20:54:42 +00:00			`<link linkend="tips.componentized.templates">Componentized Templates</link>.`
			`</para>`
banana split 2004-04-13 08:46:28 +00:00			`</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`
Clean up: - domain.com => example.com, as suggested by RFC 2606 - fix and introduce more dockbook tags - fix white spaces and use CDATA sections - add some paras to make the text more reader friendly 2004-11-21 02:04:01 +00:00			`-->`
updates by Peter Morgan: more cross-linking better distinction between {assign} and assign() and {fetch} and fetch() 2005-05-24 14:01:49 +00:00