smarty/docs/en/programmers/plugins/plugins-modifiers.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
   <sect1 id="plugins.modifiers"><title>Modifiers</title>
    <para>
     <link linkend="language.modifiers">Modifiers</link> are little functions
     that are applied to a variable in the template before it is displayed or
     used in some other context. Modifiers can be chained together.
    </para>
    <funcsynopsis>
     <funcprototype>
      <funcdef>mixed <function>smarty_modifier_<replaceable>name</replaceable></function></funcdef>
      <paramdef>mixed <parameter>$value</parameter></paramdef>
      <paramdef>[mixed <parameter>$param1</parameter>, ...]</paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     The first parameter to the modifier plugin is the value on which
     the modifier is to operate. The rest of the parameters are optional,
     depending on what kind of operation is to be  performed.
    </para>
    <para>
     The modifier has to <ulink url="&url.php-manual;return">return</ulink>
     the result of its processing.
    </para>

    <example>
     <title>A simple modifier plugin</title>
     <para>
      This plugin basically aliases one of the built-in PHP functions. It
      does not have any additional parameters.
     </para>
     <programlisting role="php">
<![CDATA[
<?php
/*
 * Smarty plugin
 * -------------------------------------------------------------
 * File:     modifier.capitalize.php
 * Type:     modifier
 * Name:     capitalize
 * Purpose:  capitalize words in the string
 * -------------------------------------------------------------
 */
function smarty_modifier_capitalize($string)
{
    return ucwords($string);
}
?>
]]>
</programlisting>
    </example>
    <para></para>
    <example>
     <title>More complex modifier plugin</title>
     <programlisting role="php">
<![CDATA[
<?php
/*
 * Smarty plugin
 * -------------------------------------------------------------
 * File:     modifier.truncate.php
 * Type:     modifier
 * Name:     truncate
 * Purpose:  Truncate a string to a certain length if necessary,
 *           optionally splitting in the middle of a word, and
 *           appending the $etc string.
 * -------------------------------------------------------------
 */
function smarty_modifier_truncate($string, $length = 80, $etc = '...',
                                  $break_words = false)
{
    if ($length == 0)
        return '';

    if (strlen($string) > $length) {
        $length -= strlen($etc);
        $fragment = substr($string, 0, $length+1);
        if ($break_words)
            $fragment = substr($fragment, 0, -1);
        else
            $fragment = preg_replace('/\s+(\S+)?$/', '', $fragment);
        return $fragment.$etc;
    } else
        return $string;
}
?>
]]>
     </programlisting>
    </example>
     <para>
     See also
     <link linkend="api.register.modifier"><varname>register_modifier()</varname></link>,
     <link linkend="api.unregister.modifier"><varname>unregister_modifier()</varname></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
-->