smarty/docs/en/programmers/api-variables.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
  <chapter id="api.variables">
   <title>Variables</title>

   <sect1 id="variable.template.dir">
    <title>$template_dir</title>
    <para>
     This is the name of the default template directory. If you do
     not supply a resource type when including files, they will be
     found here. By default this is "./templates", meaning that it
     will look for the templates directory in the same directory as
     the executing php script.
    </para>
    <note>
     <title>Technical Note</title>
     <para>
      It is not recommended to put this directory under
      the web server document root.
     </para>
    </note>
   </sect1>		
   <sect1 id="variable.compile.dir">
    <title>$compile_dir</title>
    <para>
     This is the name of the directory where compiled templates are
     located. By default this is "./templates_c", meaning that it
     will look for the compile directory in the same directory as
     the executing php script.
    </para>
    <note>
     <title>Technical Note</title>
      <para>
       This setting must be either a relative or
       absolute path. include_path is not used for writing files.
      </para>
     </note>
     <note>
      <title>Technical Note</title>
      <para>
       It is not recommended to put this directory under
       the web server document root.
      </para>
     </note>
    </sect1>
    <sect1 id="variable.config.dir">
      <title>$config_dir</title>
      <para>
       This is the directory used to store config files used in the
       templates. Default is "./configs", meaning that it will look
       for the configs directory in the same directory as the
       executing php script.
      </para>
	 <note>
	 <title>Technical Note</title>
	 <para>
       It is not recommended to put this directory under
       the web server document root.
      </para>
	 </note>
     </sect1>
     <sect1 id="variable.plugins.dir">
      <title>$plugins_dir</title>
      <para>
	   This is the directories where Smarty will look for the plugins that it
	   needs. Default is "plugins" under the SMARTY_DIR. If you supply a
	   relative path, Smarty will first look under the SMARTY_DIR, then
	   relative to the cwd (current working directory), then relative to each
	   entry in your PHP include path.
      </para>
	  <note>
	  <title>Technical Note</title>
	  <para>
	  For best performance, do not setup your plugins_dir to have to use the
	  PHP include path. Use an absolute pathname, or a path relative to
	  SMARTY_DIR or the cwd.
	  </para>
	  </note>
     </sect1>
     <sect1 id="variable.debugging">
      <title>$debugging</title>
      <para>
       This enables the <link
        linkend="chapter.debugging.console">debugging console</link>.
       The console is a javascript window that informs you of the
       included templates and assigned variables for the current
       template page.
      </para>
     </sect1>
     <sect1 id="variable.debug.tpl">
      <title>$debug_tpl</title>
      <para>
	   This is the name of the template file used for the debugging console. By
	   default, it is named debug.tpl and is located in the <link
	   linkend="constant.smarty.dir">SMARTY_DIR</link>.
      </para>
     </sect1>
     <sect1 id="variable.debugging.ctrl">
      <title>$debugging_ctrl</title>
      <para>
       This allows alternate ways to enable debugging. NONE means no
       alternate methods are allowed. URL means when the keyword
       SMARTY_DEBUG is found in the QUERY_STRING, debugging is enabled
       for that invocation of the script. If $debugging is true, this
       value is ignored.
      </para>
     </sect1>
     <sect1 id="variable.undefined">
      <title>$undefined</title>
      <para>
       This sets the value of $undefined for Smarty, default is null.
       Currently this is only used to set undefined variables in
       $global_assign to a default value.
      </para>
     </sect1>
     <sect1 id="variable.autoload.filters">
      <title>$autoload_filters</title>
      <para>
       If there are some filters that you wish to load on every template
       invocation, you can specify them using this variable and Smarty will
       automatically load them for you. The variable is an associative array
       where keys are filter types and values are arrays of the filter
       names. For example:
       <informalexample>
        <programlisting role="php">
<![CDATA[
<?php
$smarty->autoload_filters = array('pre' => array('trim', 'stamp'),
                                  'output' => array('convert'));
?>
]]>
        </programlisting>
       </informalexample> 
      </para>
     </sect1>
     <sect1 id="variable.compile.check">
      <title>$compile_check</title>
      <para>
	   Upon each invocation of the PHP application, Smarty tests to see if the
	   current template has changed (different time stamp) since the last time
	   it was compiled. If it has changed, it recompiles that template. If the
	   template has not been compiled, it will compile regardless of this
	   setting. By default this variable is set to true. Once an application is
	   put into production (templates won't be changing), the compile_check
	   step is no longer needed. Be sure to set $compile_check to "false" for
	   maximal performance. Note that if you change this to "false" and a
	   template file is changed, you will *not* see the change since the
	   template will not get recompiled. If caching is enabled and
	   compile_check is enabled, then the cache files will get regenerated if
	   an involved template file or config file was updated. See <link
	   linkend="variable.force.compile">$force_compile</link> or <link
	   linkend="api.clear.compiled.tpl">clear_compiled_tpl</link>.
      </para>
     </sect1>
     <sect1 id="variable.force.compile">
      <title>$force_compile</title>
      <para>
       This forces Smarty to (re)compile templates on every
       invocation. This setting overrides $compile_check. By default
       this is disabled. This is handy for development and debugging.
       It should never be used in a production environment. If caching
       is enabled, the cache file(s) will be regenerated every time.
      </para>
     </sect1>
     <sect1 id="variable.caching">
      <title>$caching</title>
      <para>
	   This tells Smarty whether or not to cache the output of the templates.
	   By default this is set to 0, or disabled. If your templates generate
	   redundant redundant content, it is advisable to turn on caching. This
	   will result in significant performance gains. You can also have multiple
	   caches for the same template. A value of 1 or 2 enables caching. 1 tells
	   Smarty to use the current $cache_lifetime variable to determine if the
	   cache has expired. A value of 2 tells Smarty to use the cache_lifetime
	   value at the time the cache was generated. This way you can set the
	   cache_lifetime just before fetching the template to have granular
	   control over when that particular cache expires. See also <link
	   linkend="api.is.cached">is_cached</link>.
      </para>
      <para>
	   If $compile_check is enabled, the cached content will be regenerated if
	   any of the templates or config files that are part of this cache are
	   changed. If $force_compile is enabled, the cached content will always be
	   regenerated.
      </para>
     </sect1>
     <sect1 id="variable.cache.dir">
      <title>$cache_dir</title>
      <para>
       This is the name of the directory where template caches are
       stored. By default this is "./cache", meaning that it will look
       for the cache directory in the same directory as the executing
       php script. You can also use your own custom cache handler
       function to control cache files, which will ignore this
       setting.
      </para>
	  <note>
	  <title>Technical Note</title>
	  <para>
       This setting must be either a relative or
       absolute path. include_path is not used for writing files.
      </para>
	  </note>
	  <note>
		  <title>Technical Note</title>
		  <para>
    	   It is not recommended to put this directory under
    	   the web server document root.
    	  </para>
	  </note>
     </sect1>
     <sect1 id="variable.cache.lifetime">
      <title>$cache_lifetime</title>
      <para>
	   This is the length of time in seconds that a template cache is valid.
	   Once this time has expired, the cache will be regenerated. $caching must
	   be set to "true" for $cache_lifetime to have any purpose. A value of -1
	   will force the cache to never expire. A value of 0 will cause the cache
	   to always regenerate (good for testing only, to disable caching a more
	   efficient method is to set <link
	   linkend="variable.caching">$caching</link> = false.)
      </para>
	  <para>
	   If <link linkend="variable.force.compile">$force_compile</link> is
	   enabled, the cache files will be regenerated every time, effectively
	   disabling caching. You can clear all the cache files with the <link
	   linkend="api.clear.all.cache">clear_all_cache()</link> function, or
	   individual cache files (or groups) with the <link
	   linkend="api.clear.cache">clear_cache()</link> function.
	  </para>
	  <note>
	  <title>Technical Note</title>
	  <para>
	  If you want to give certain templates their own cache lifetime, you could
	  do this by setting <link linkend="variable.caching">$caching</link> = 2,
	  then set $cache_lifetime to a unique value just before calling display()
	  or fetch().
	  </para>
	  </note>
     </sect1>
     <sect1 id="variable.cache.handler.func">
      <title>$cache_handler_func</title>
      <para>
       You can supply a custom function to handle cache files instead
       of using the built-in method using the $cache_dir. See the
       custom  <link linkend="section.template.cache.handler.func">cache
       handler function section</link> for details.
      </para>
     </sect1>
     <sect1 id="variable.cache.modified.check">
      <title>$cache_modified_check</title>
      <para>
       If set to true, Smarty will respect the If-Modified-Since
       header sent from the client. If the cached file timestamp has
       not changed since the last visit, then a "304 Not Modified"
       header will be sent instead of the content. This works only on
       cached content without <command>insert</command> tags.
      </para>
     </sect1>
     <sect1 id="variable.config.overwrite">
      <title>$config_overwrite</title>
      <para>
       If set to true, variables read in from config files will overwrite each
	   other. Otherwise, the variables will be pushed onto an array. This is
	   helpful if you want to store arrays of data in config files, just list
	   each element multiple times. true by default.
      </para>
     </sect1>
     <sect1 id="variable.config.booleanize">
      <title>$config_booleanize</title>
      <para>
	   If set to true, config file values of on/true/yes and off/false/no get
	   converted to boolean values automatically. This way you can use the
	   values in the template like so: {if #foobar#} ... {/if}. If foobar was
	   on, true or yes, the {if} statement will execute. true by default.
      </para>
     </sect1>
     <sect1 id="variable.config.read.hidden">
      <title>$config_read_hidden</title>
      <para>
	   If set to true, hidden sections (section names beginning with a period)
	   in config files can be read from templates. Typically you would leave
	   this false, that way you can store sensitive data in the config files
	   such as database parameters and not worry about the template loading
	   them. false by default.
	   </para>
     </sect1>
     <sect1 id="variable.config.fix.newlines">
      <title>$config_fix_newlines</title>
      <para>
	   If set to true, mac and dos newlines (\r and \r\n) in config files are
	   converted to \n when they are parsed. true by default.
	   </para>
     </sect1>
     <sect1 id="variable.default.template.handler.func">
      <title>$default_template_handler_func</title>
      <para>
       This function is called when a template cannot be obtained from
       its resource.
      </para>
     </sect1>
     <sect1 id="variable.php.handling">
      <title>$php_handling</title>
      <para>
       This tells Smarty how to handle PHP code embedded in the
       templates. There are four possible settings, default being
       SMARTY_PHP_PASSTHRU. Note that this does NOT affect php code
       within <link linkend="language.function.php">{php}{/php}</link>
       tags in the template.
      </para>    
      <itemizedlist>
       <listitem><para>SMARTY_PHP_PASSTHRU - Smarty echos tags as-is.</para></listitem>
       <listitem><para>SMARTY_PHP_QUOTE - Smarty quotes the tags as
         html entities.</para></listitem>
       <listitem><para>SMARTY_PHP_REMOVE - Smarty removes the tags from
         the templates.</para></listitem>
       <listitem><para>SMARTY_PHP_ALLOW - Smarty will execute the tags
         as PHP code.</para></listitem>
      </itemizedlist>
      <para>
       NOTE: Embedding PHP code into templates is highly discouraged.
       Use <link linkend="language.custom.functions">custom functions</link> or
       <link linkend="language.modifiers">modifiers</link> instead.
      </para>
     </sect1>
     <sect1 id="variable.security">
      <title>$security</title>
      <para>
       $security true/false, default is false. Security is good for
       situations when you have untrusted parties editing the templates
       (via ftp for example) and you want to reduce the risk of system
       security compromises through the template language. Turning on
       security enforces the following rules to the template language,
       unless specifially overridden with $security_settings:
      </para>
      <itemizedlist>
       <listitem><para>If $php_handling is set to SMARTY_PHP_ALLOW, this is
         implicitly changed to SMARTY_PHP_PASSTHRU</para></listitem>
       <listitem><para>PHP functions are not allowed in IF statements,
         except those specified in the $security_settings</para></listitem>
       <listitem><para>templates can only be included from directories
         listed in the $secure_dir array</para></listitem>
       <listitem><para>local files can only be fetched from directories
         listed in the $secure_dir array using {fetch}</para></listitem>
       <listitem><para>{php}{/php} tags are not allowed</para></listitem>
       <listitem><para>PHP functions are not allowed as modifiers, except
         those specified in the $security_settings</para></listitem>
      </itemizedlist>
     </sect1>
     <sect1 id="variable.secure.dir">
      <title>$secure_dir</title>
      <para>
       This is an array of all local directories that are considered
       secure. {include} and {fetch} use this when security is enabled.
      </para>
     </sect1>
     <sect1 id="variable.security.settings">
      <title>$security_settings</title>
      <para>
       These are used to override or specify the security settings when
       security is enabled. These are the possible settings:
      </para>
      <itemizedlist>
       <listitem><para>PHP_HANDLING - true/false. If set to true, the
         $php_handling setting is not checked for security.</para></listitem>
       <listitem><para>IF_FUNCS - This is an array of the names of permitted
         PHP functions in IF statements.</para></listitem>
       <listitem><para>INCLUDE_ANY - true/false. If set to true, any
         template can be included from the file system, regardless of the
         $secure_dir list.</para></listitem>
       <listitem><para>PHP_TAGS - true/false. If set to true, {php}{/php}
         tags are permitted in the templates.</para></listitem>
       <listitem><para>MODIFIER_FUNCS - This is an array of the names of permitted
         PHP functions used as variable modifiers.</para></listitem>
      </itemizedlist>
     </sect1>
     <sect1 id="variable.trusted.dir">
      <title>$trusted_dir</title>
      <para>
	   $trusted_dir is only for use when $security is enabled. This is an array
	   of all directories that are considered trusted. Trusted directories are
	   where you keep php scripts that are executed directly from the templates
	   with <link linkend="language.function.include.php">{include_php}</link>.
      </para>
     </sect1>
     <sect1 id="variable.left.delimiter">
      <title>$left_delimiter</title>
      <para>
       This is the left delimiter used by the template language.
       Default is "{".			
      </para>
     </sect1>
     <sect1 id="variable.right.delimiter">
      <title>$right_delimiter</title>
      <para>
       This is the right delimiter used by the template language.
       Default is "}".			
      </para>
     </sect1>
     <sect1 id="variable.compiler.class">
      <title>$compiler_class</title>
      <para>
       Specifies the name of the compiler class that Smarty will use
       to compile the templates. The default is 'Smarty_Compiler'. For
       advanced users only.
      </para>
     </sect1>
     <sect1 id="variable.request.vars.order">
      <title>$request_vars_order</title>
      <para>
       The order in which request variables are registered, similar to
       variables_order in php.ini
      </para>
     </sect1>
     <sect1 id="variable.request.use.auto.globals">
      <title>$request_use_auto_globals</title>
      <para>
	   Specifies if Smarty should use php's $HTTP_*_VARS[]
	   ($request_use_auto_globals=false which is the default value) or
	   $_*[] ($request_use_auto_globals=true). This affects templates
	   that make use of {$smarty.request.*}, {$smarty.get.*} etc. .
	   Caution: If you set $request_use_auto_globals to true, <link
	   linkend="variable.request.vars.order">variable.request.vars.order
	   </link> has no effect but php's configuration value
	   <literal>gpc_order</literal> is used.
      </para>
     </sect1>
     <sect1 id="variable.error.reporting">
      <title>$error_reporting</title>
      <para>
           When this value is set to a non-null-value it's value is
           used as php's error_reporting-level inside of display() and
           fetch(). When debugging is enabled this value is ignored
           and the error-level is left untouched.
      </para>
     </sect1>
     <sect1 id="variable.compile.id">
      <title>$compile_id</title>
      <para>
	   Persistant compile identifier. As an alternative to passing the same
	   compile_id to each and every function call, you can set this compile_id
	   and it will be used implicitly thereafter.
      </para>
     </sect1>
     <sect1 id="variable.use.sub.dirs">
      <title>$use_sub_dirs</title>
      <para>
	  Set this to false if your PHP environment does not allow the creation of
	  sub directories by Smarty. Sub directories are more efficient, so use them
	  if you can.
      </para>
      <note>
      <title>Technical Note</title>
      <para>
          Since Smarty-2.6.2 <varname>use_sub_dirs</varname> defaults to false.
      </para>
      </note>
     </sect1>
     <sect1 id="variable.default.modifiers">
      <title>$default_modifiers</title>
      <para>
	  This is an array of modifiers to implicitly apply to every variable in a
	  template. For example, to HTML-escape every variable by default, use
	  array('escape:"htmlall"'); To make a variable exempt from default
	  modifiers, pass the special "smarty" modifier with a parameter value of
	  "nodefaults" modifier to it, such as
	  {$var|smarty:nodefaults}.
      </para>
     </sect1>
     <sect1 id="variable.default.resource.type">
      <title>$default_resource_type</title>
      <para>
	  This tells smarty what resource type to use implicitly. The default value
	  is 'file', meaning that $smarty->display('index.tpl'); and
	  $smarty->display('file:index.tpl'); are identical in meaning. See the
	  <link linkend="template.resources">resource</link> chapter for details.
      </para>
     </sect1>
</chapter>
<!-- 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
-->