smarty/docs/en/designers/language-modifiers.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<chapter id="language.modifiers">
 <title>Variable Modifiers</title>
 <para>
  Variable modifiers can be applied to
  <link linkend="language.syntax.variables">variables</link>,
  <link linkend="language.custom.functions">custom functions</link> or strings.
  To apply a modifier, specify the value followed by a <literal>|</literal>
  (pipe) and the modifier name. A modifier may accept additional parameters
  that affect its behavior. These parameters follow the modifer name and are
  separated by a <literal>:</literal> (colon). Also,
  <emphasis>all php-functions can be used as modifiers implicitly</emphasis>
  (more below) and modifiers can be
  <link linkend="language.combining.modifiers">combined</link>.
  .
 </para>
 <example>
  <title>Modifier examples</title>
  <programlisting>
<![CDATA[
{* apply modifier to a variable *}
{$title|upper}

{* modifier with parameters *}
{$title|truncate:40:'...'}

{* apply modifier to a function parameter *}
{html_table loop=$myvar|upper}

{* with parameters *}
{html_table loop=$myvar|truncate:40:'...'}

{* apply modifier to literal string *}
{'foobar'|upper}

{* using date_format to format the current date *}
{$smarty.now|date_format:"%Y/%m/%d"}

{* apply modifier to a custom function *}
{mailto|upper address='smarty@example.com'}

{* using  php's str_repeat *}
{'='|str_repeat:80}

{* php's count *}
{$myArray|@count}

{* php's shuffle on servers's ip *}
{$smarty.server.SERVER_ADDR|shuffle}

(* this will uppercase and truncate the whole array *}
<select name="name_id">
{html_options output=$myArray|upper|truncate:20}
</select>
]]>
  </programlisting>
 </example>
 <itemizedlist>

 <listitem><para>
  If you apply a modifier to an array variable instead of a single value variable,
  the modifier will be applied to every value in that array. If you really want
  the modifier to work on an entire array as a value, you must prepend the
  modifier name with a <literal>@</literal> symbol.
  <note>
  <title>Example</title>
  <para><literal>{$articleTitle|@count}</literal> - will print out the number of
  elements in the <parameter>$articleTitle</parameter> array using the php
  <ulink url="&url.php-manual;count"><varname>count()</varname></ulink>
  function as a modifier.
  </para></note>
  </para> </listitem>

 <listitem><para>
  Modifiers are autoloaded from the <link
  linkend="variable.plugins.dir"><parameter>$plugins_dir</parameter></link>
  or can be registered explicitly with the <link
  linkend="api.register.modifier"><varname>register_modifier()</varname></link>
  function. The later is useful for sharing a function between
   php scripts and smarty templates.
  </para></listitem>

  <listitem><para>
  All php-functions can be used as modifiers implicitly, as demonstrated in the
  example above.
  However, using php-functions as modifiers has two little pitfalls:
   <itemizedlist>
  <listitem><para>First - sometimes the order of the function-parameters is
   not the desirable one. Formatting <literal>$foo</literal>  with
   <literal>{"%2.f"|sprintf:$foo}</literal> actually
   works, but asks for the more intuitive, like
   <literal>{$foo|string_format:"%2.f"}</literal> that is provided by
   the Smarty distribution.
  </para></listitem>
   <listitem><para>
   Secondly - if <link linkend="variable.security">
   <parameter>$security</parameter></link> is enabled, all php-functions that
   are to be used as modifiers have to be declared trusted in the
   <literal>MODIFIER_FUNCS</literal> element of the
   <link linkend="variable.security.settings">
   <parameter>$security_settings</parameter></link> array.
  </para></listitem>
   </itemizedlist>
 </para></listitem>
  </itemizedlist>

 <para>
  See also
  <link linkend="api.register.modifier"><varname>register_modifier()</varname></link>,
  <link linkend="language.combining.modifiers">combining modifiers</link>.
  and
  <link linkend="plugins">extending smarty with plugins</link>
 </para>

 &designers.language-modifiers.language-modifier-capitalize;
 &designers.language-modifiers.language-modifier-cat;
 &designers.language-modifiers.language-modifier-count-characters;
 &designers.language-modifiers.language-modifier-count-paragraphs;
 &designers.language-modifiers.language-modifier-count-sentences;
 &designers.language-modifiers.language-modifier-count-words;
 &designers.language-modifiers.language-modifier-date-format;
 &designers.language-modifiers.language-modifier-default;
 &designers.language-modifiers.language-modifier-escape;
 &designers.language-modifiers.language-modifier-indent;
 &designers.language-modifiers.language-modifier-lower;
 &designers.language-modifiers.language-modifier-nl2br;
 &designers.language-modifiers.language-modifier-regex-replace;
 &designers.language-modifiers.language-modifier-replace;
 &designers.language-modifiers.language-modifier-spacify;
 &designers.language-modifiers.language-modifier-string-format;
 &designers.language-modifiers.language-modifier-strip;
 &designers.language-modifiers.language-modifier-strip-tags;
 &designers.language-modifiers.language-modifier-truncate;
 &designers.language-modifiers.language-modifier-upper;
 &designers.language-modifiers.language-modifier-wordwrap;

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