smarty-php/smarty
1
0
Fork 0
mirror of https://github.com/smarty-php/smarty.git synced 2025-08-06 19:34:27 +02:00
Code Issues Packages Projects Releases Wiki Activity

Tidy up some formatting

Browse Source
This commit is contained in:
pete_morgan
2006-09-27 03:26:52 +00:00
parent e521084a10
commit 409efbdd68
10 changed files with 205 additions and 132 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
docs/en/programmers/plugins/plugins-block-functions.xml
View File

@@ -11,62 +11,64 @@
</funcprototype> </funcprototype>
</funcsynopsis> </funcsynopsis>
<para> <para>
Block functions are functions of the form: {func} .. {/func}. In other Block functions are functions of the form:
words, they enclose a template block and operate on the contents of <literal>{func} .. {/func}</literal>. In other words, they enclose a
this block. Block functions take precedence over custom functions of template block and operate on the contents of
the same name, that is, you cannot have both custom function {func} and this block. Block functions take precedence over
block function {func} .. {/func}. <link linkend="language.custom.functions">custom functions</link> of
the same name, that is, you cannot have both custom function
<literal>{func}</literal> and block function
<literal>{func}..{/func}</literal>.
</para> </para>
<para>
<itemizedlist>
<listitem><para>
By default your function implementation is called twice by By default your function implementation is called twice by
Smarty: once for the opening tag, and once for the closing tag Smarty: once for the opening tag, and once for the closing tag.
(see <literal>&amp;$repeat</literal> below how to change this). (See <literal>$repeat</literal> below on how to change this.)
</para> </para></listitem>
<para> <listitem><para>
Only the opening tag of the block function may have attributes. All Only the opening tag of the block function may have
<link linkend="language.syntax.attributes">attributes</link>. All
attributes passed to template functions from the template are contained attributes passed to template functions from the template are contained
in the <parameter>$params</parameter> as an associative array. You can in the <parameter>$params</parameter> variable as an associative array.
access those values as e.g. <varname>$params['start']</varname>.
The opening tag attributes are also accessible to your function The opening tag attributes are also accessible to your function
when processing the closing tag. when processing the closing tag.
</para> </para></listitem>
<para> <listitem><para>
The value of <parameter>$content</parameter> variable depends on The value of the <parameter>$content</parameter> variable depends on
whether your function is called for the opening or closing tag. In case whether your function is called for the opening or closing tag. In case
of the opening tag, it will be <literal>null</literal>, and in case of of the opening tag, it will be &null;, and in case of
the closing tag it will be the contents of the template block. the closing tag it will be the contents of the template block.
Note that the template block will have already been processed by Note that the template block will have already been processed by
Smarty, so all you will receive is the template output, not the Smarty, so all you will receive is the template output, not the
template source. template source.
</para> </para></listitem>
<para> <listitem><para>
The parameter <parameter>&amp;$repeat</parameter> is passed by The parameter <parameter>$repeat</parameter> is passed by
reference to the function implementation and provides a reference to the function implementation and provides a
possibility for it to control how many times the block is possibility for it to control how many times the block is
displayed. By default <parameter>$repeat</parameter> is displayed. By default <parameter>$repeat</parameter> is
<literal>true</literal> at the first call of the block-function &true; at the first call of the block-function (the opening tag)
(the block opening tag) and <literal>false</literal> on all and &false; on all subsequent calls to the block function
subsequent calls to the block function (the block's closing tag). (the block's closing tag).
Each time the function implementation returns with Each time the function implementation returns with
<parameter>&amp;$repeat</parameter> being true, the contents between <parameter>$repeat</parameter> being &true;, the contents between
{func} .. {/func} are evaluated and the function implementation <literal>{func}...{/func}</literal> are evaluated and the function
is called again with the new block contents in the parameter implementation is called again with the new block contents in the parameter
<parameter>$content</parameter>. <parameter>$content</parameter>.
</para></listitem>
</para> </itemizedlist>
<para> <para>
If you have nested block functions, it's possible to find out what the If you have nested block functions, it's possible to find out what the
parent block function is by accessing parent block function is by accessing
<varname>$smarty->_tag_stack</varname> variable. Just do a var_dump() <literal>$smarty->_tag_stack</literal> variable. Just do a
<ulink url="&url.php-manual;var_dump"><varname>var_dump()</varname></ulink>
on it and the structure should be apparent. on it and the structure should be apparent.
</para> </para>
<para>
See also:
<link linkend="api.register.block">register_block()</link>,
<link linkend="api.unregister.block">unregister_block()</link>.
</para>
<example> <example>
<title>block function</title> <title>block function</title>
<programlisting role="php"> <programlisting role="php">
@@ -83,16 +85,26 @@
*/ */
function smarty_block_translate($params, $content, &$smarty, &$repeat) function smarty_block_translate($params, $content, &$smarty, &$repeat)
{ {
if (isset($content)) { // only output on the closing tag
$lang = $params['lang']; if(!$repeat){
// do some intelligent translation thing here with $content if (isset($content)) {
return $translation; $lang = $params['lang'];
// do some intelligent translation thing here with $content
return $translation;
}
} }
} }
?> ?>
]]> ]]>
</programlisting> </programlisting>
</example> </example>
<para>
See also:
<link linkend="api.register.block"><varname>register_block()</varname></link>,
<link linkend="api.unregister.block"><varname>unregister_block()</varname></link>.
</para>
</sect1> </sect1>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file

23
docs/en/programmers/plugins/plugins-compiler-functions.xml
View File

@@ -5,8 +5,8 @@
Compiler functions are called only during compilation of the template. Compiler functions are called only during compilation of the template.
They are useful for injecting PHP code or time-sensitive static They are useful for injecting PHP code or time-sensitive static
content into the template. If there is both a compiler function and a content into the template. If there is both a compiler function and a
custom function registered under the same name, the compiler function <link linkend="language.custom.functions">custom function</link> registered
has precedence. under the same name, the compiler function has precedence.
</para> </para>
<funcsynopsis> <funcsynopsis>
<funcprototype> <funcprototype>
@@ -21,13 +21,9 @@
delimiter, and the Smarty object. It's supposed to return the PHP code delimiter, and the Smarty object. It's supposed to return the PHP code
to be injected into the compiled template. to be injected into the compiled template.
</para> </para>
<para>
See also
<link linkend="api.register.compiler.function">register_compiler_function()</link>,
<link linkend="api.unregister.compiler.function">unregister_compiler_function()</link>.
</para>
<example> <example>
<title>simple compiler function</title> <title>A simple compiler function</title>
<programlisting role="php"> <programlisting role="php">
<![CDATA[ <![CDATA[
<?php <?php
@@ -52,8 +48,10 @@ function smarty_compiler_tplheader($tag_arg, &$smarty)
This function can be called from the template as: This function can be called from the template as:
</para> </para>
<programlisting> <programlisting>
<![CDATA[
{* this function gets executed at compile time only *} {* this function gets executed at compile time only *}
{tplheader} {tplheader}
]]>
</programlisting> </programlisting>
<para> <para>
The resulting PHP code in the compiled template would be something like this: The resulting PHP code in the compiled template would be something like this:
@@ -66,6 +64,15 @@ echo 'index.tpl compiled at 2002-02-20 20:02';
]]> ]]>
</programlisting> </programlisting>
</example> </example>
<para>
See also
<link linkend="api.register.compiler.function">
<varname>register_compiler_function()</varname></link>,
<link linkend="api.unregister.compiler.function">
<varname>unregister_compiler_function()</varname></link>.
</para>
</sect1> </sect1>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file

30
docs/en/programmers/plugins/plugins-functions.xml
View File

@@ -9,26 +9,25 @@
</funcprototype> </funcprototype>
</funcsynopsis> </funcsynopsis>
<para> <para>
All attributes passed to template functions from the template are All <link linkend="language.syntax.attributes">attributes</link> passed to
contained in the <parameter>$params</parameter> as an associative template functions from the template are contained in the
array. <parameter>$params</parameter> as an associative array.
</para> </para>
<para> <para>
The output (return value) of the function will be substituted in place of the The output (return value) of the function will be substituted in place of
function tag in the template (<function>fetch</function> function, for the function tag in the template, eg the
example). Alternatively, the function can simply perform some other <link linkend="language.function.fetch"><varname>{fetch}</varname></link>
task without any output (<function>assign</function> function). function. Alternatively, the function can simply perform some other
task without any output, eg the <link linkend="language.function.assign">
<varname>{assign}</varname></link> function.
</para> </para>
<para> <para>
If the function needs to assign some variables to the template or use If the function needs to assign some variables to the template or use
some other Smarty-provided functionality, it can use the supplied some other Smarty-provided functionality, it can use the supplied
<parameter>$smarty</parameter> object to do so. <parameter>$smarty</parameter> object to do so eg
</para> <literal>$smarty->foo()</literal>.
<para>
See also:
<link linkend="api.register.function">register_function()</link>,
<link linkend="api.unregister.function">unregister_function()</link>.
</para> </para>
<para> <para>
<example> <example>
<title>function plugin with output</title> <title>function plugin with output</title>
@@ -101,6 +100,11 @@ function smarty_function_assign($params, &$smarty)
]]> ]]>
</programlisting> </programlisting>
</example> </example>
</para>
<para>
See also:
<link linkend="api.register.function"><varname>register_function()</varname></link>,
<link linkend="api.unregister.function"><varname>unregister_function()</varname></link>.
</para> </para>
</sect1> </sect1>

6
docs/en/programmers/plugins/plugins-inserts.xml
View File

@@ -3,7 +3,7 @@
<sect1 id="plugins.inserts"><title>Inserts</title> <sect1 id="plugins.inserts"><title>Inserts</title>
<para> <para>
Insert plugins are used to implement functions that are invoked by Insert plugins are used to implement functions that are invoked by
<link linkend="language.function.insert">{insert}</link> <link linkend="language.function.insert"><varname>{insert}</varname></link>
tags in the template. tags in the template.
</para> </para>
<funcsynopsis> <funcsynopsis>
@@ -19,7 +19,7 @@
</para> </para>
<para> <para>
The insert function is supposed to return the result which will be The insert function is supposed to return the result which will be
substituted in place of the <command>{insert}</command> tag in the substituted in place of the <varname>{insert}</varname> tag in the
template. template.
</para> </para>
<example> <example>
@@ -29,7 +29,7 @@
<?php <?php
/* /*
* Smarty plugin * Smarty plugin
* ------------------------------------------------------------- * -------------------------------------------------------------
* File: insert.time.php * File: insert.time.php
* Type: time * Type: time
* Name: time * Name: time

31
docs/en/programmers/plugins/plugins-modifiers.xml
View File

@@ -2,9 +2,9 @@
<!-- $Revision$ --> <!-- $Revision$ -->
<sect1 id="plugins.modifiers"><title>Modifiers</title> <sect1 id="plugins.modifiers"><title>Modifiers</title>
<para> <para>
Modifiers are little functions that are applied to a variable in the <link linkend="language.modifiers">Modifiers</link> are little functions
template before it is displayed or used in some other context. that are applied to a variable in the template before it is displayed or
Modifiers can be chained together. used in some other context. Modifiers can be chained together.
</para> </para>
<funcsynopsis> <funcsynopsis>
<funcprototype> <funcprototype>
@@ -15,20 +15,16 @@
</funcsynopsis> </funcsynopsis>
<para> <para>
The first parameter to the modifier plugin is the value on which The first parameter to the modifier plugin is the value on which
the modifier is supposed to operate. The rest of the parameters can be the modifier is to operate. The rest of the parameters are optional,
optional, depending on what kind of operation is supposed to be depending on what kind of operation is to be performed.
performed.
</para> </para>
<para> <para>
The modifier has to return the result of its processing. The modifier has to <ulink url="&url.php-manual;return">return</ulink>
</para> the result of its processing.
<para>
See also
<link linkend="api.register.modifier">register_modifier()</link>,
<link linkend="api.unregister.modifier">unregister_modifier()</link>.
</para> </para>
<example> <example>
<title>simple modifier plugin</title> <title>A simple modifier plugin</title>
<para> <para>
This plugin basically aliases one of the built-in PHP functions. It This plugin basically aliases one of the built-in PHP functions. It
does not have any additional parameters. does not have any additional parameters.
@@ -55,7 +51,7 @@ function smarty_modifier_capitalize($string)
</example> </example>
<para></para> <para></para>
<example> <example>
<title>more complex modifier plugin</title> <title>More complex modifier plugin</title>
<programlisting role="php"> <programlisting role="php">
<![CDATA[ <![CDATA[
<?php <?php
@@ -66,7 +62,7 @@ function smarty_modifier_capitalize($string)
* Type: modifier * Type: modifier
* Name: truncate * Name: truncate
* Purpose: Truncate a string to a certain length if necessary, * Purpose: Truncate a string to a certain length if necessary,
* optionally splitting in the middle of a word, and * optionally splitting in the middle of a word, and
* appending the $etc string. * appending the $etc string.
* ------------------------------------------------------------- * -------------------------------------------------------------
*/ */
@@ -91,6 +87,11 @@ function smarty_modifier_truncate($string, $length = 80, $etc = '...',
]]> ]]>
</programlisting> </programlisting>
</example> </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> </sect1>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file

44
docs/en/programmers/plugins/plugins-naming-conventions.xml
View File

@@ -7,7 +7,7 @@
convention in order to be located by Smarty. convention in order to be located by Smarty.
</para> </para>
<para> <para>
The plugin files must be named as follows: <emphasis role="bold">plugin files</emphasis> must be named as follows:
<blockquote> <blockquote>
<para> <para>
<filename> <filename>
@@ -16,7 +16,9 @@
</para> </para>
</blockquote> </blockquote>
</para> </para>
<para>
<itemizedlist>
<listitem><para>
Where <literal>type</literal> is one of these plugin types: Where <literal>type</literal> is one of these plugin types:
<itemizedlist spacing="compact"> <itemizedlist spacing="compact">
<listitem><simpara>function</simpara></listitem> <listitem><simpara>function</simpara></listitem>
@@ -30,27 +32,41 @@
<listitem><simpara>insert</simpara></listitem> <listitem><simpara>insert</simpara></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<para> </listitem>
And <literal>name</literal> should be a valid identifier (letters,
numbers, and underscores only). <listitem><para>
And <literal>name</literal> should be a valid identifier; letters,
numbers, and underscores only, see
<ulink url="&url.php-manual;language.variables">php variables</ulink>.
</para></listitem>
<listitem><para>
Some examples: <filename>function.html_select_date.php</filename>,
<filename>resource.db.php</filename>,
<filename>modifier.spacify.php</filename>.
</para> </para>
</listitem>
</itemizedlist>
<para> <para>
Some examples: <literal>function.html_select_date.php</literal>, <emphasis role="bold">plugin functions</emphasis> inside the PHP files must be named as follows:
<literal>resource.db.php</literal>,
<literal>modifier.spacify.php</literal>.
</para>
<para>
The plugin functions inside the plugin files must be named as follows:
<blockquote> <blockquote>
<para> <para>
<function>smarty_<replaceable>type</replaceable>_<replaceable>name</replaceable></function> <function>smarty_<replaceable>type</replaceable>_<replaceable>name</replaceable></function>
</para> </para>
</blockquote> </blockquote>
</para> </para>
<para>
<itemizedlist>
<listitem><para>
The meanings of <literal>type</literal> and <literal>name</literal> are The meanings of <literal>type</literal> and <literal>name</literal> are
the same as before. the same as above.
</para> </para></listitem>
<listitem><para>
An example modifier name <varname>foo</varname> would be <literal>function smarty_modifier_foo()</literal>.
</para></listitem>
</itemizedlist>
<para> <para>
Smarty will output appropriate error messages if the plugin file it Smarty will output appropriate error messages if the plugin file it
needs is not found, or if the file or the plugin function are named needs is not found, or if the file or the plugin function are named

11
docs/en/programmers/plugins/plugins-outputfilters.xml
View File

@@ -19,7 +19,7 @@
the processing and return the results. the processing and return the results.
</para> </para>
<example> <example>
<title>output filter plugin</title> <title>An output filter plugin</title>
<programlisting role="php"> <programlisting role="php">
<![CDATA[ <![CDATA[
<?php <?php
@@ -29,7 +29,7 @@
* File: outputfilter.protect_email.php * File: outputfilter.protect_email.php
* Type: outputfilter * Type: outputfilter
* Name: protect_email * Name: protect_email
* Purpose: Converts @ sign in email addresses to %40 as * Purpose: Converts @ sign in email addresses to %40 as
* a simple protection against spambots * a simple protection against spambots
* ------------------------------------------------------------- * -------------------------------------------------------------
*/ */
@@ -42,6 +42,13 @@
]]> ]]>
</programlisting> </programlisting>
</example> </example>
<para>
See also
<link linkend="api.register.outputfilter">
<varname>register_outputfilter()</varname></link>,
<link linkend="api.unregister.outputfilter">
<varname>unregister_outputfilter()</varname></link>.
</para>
</sect1> </sect1>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file

11
docs/en/programmers/plugins/plugins-prefilters-postfilters.xml
View File

@@ -82,6 +82,17 @@
]]> ]]>
</programlisting> </programlisting>
</example> </example>
<para>
See also
<link linkend="api.register.prefilter">
<varname>register_prefilter()</varname></link>,
<link linkend="api.unregister.prefilter">
<varname>unregister_prefilter()</varname></link>
<link linkend="api.register.postfilter">
<varname>register_postfilter()</varname></link>,
<link linkend="api.unregister.postfilter">
<varname>unregister_postfilter()</varname></link>.
</para>
</sect1> </sect1>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file

75
docs/en/programmers/plugins/plugins-resources.xml
View File

@@ -8,7 +8,7 @@
</para> </para>
<para> <para>
There are a total of 4 functions that need to be registered for each There are a total of four functions that need to be registered for each
type of resource. Every function will receive the requested resource as type of resource. Every function will receive the requested resource as
the first parameter and the Smarty object as the last parameter. The the first parameter and the Smarty object as the last parameter. The
rest of parameters depend on the function. rest of parameters depend on the function.
@@ -39,44 +39,44 @@
</funcprototype> </funcprototype>
</funcsynopsis> </funcsynopsis>
<para> <itemizedlist>
The first function is supposed to retrieve the resource. Its second <listitem><para>
parameter is a variable passed by reference where the result should be The first function, <literal>source()</literal> is supposed to retrieve
stored. The function is supposed to return <literal>true</literal> if the resource. Its second parameter <parameter>$source</parameter> is a
it was able to successfully retrieve the resource and variable passed by reference where the result should be
<literal>false</literal> otherwise. stored. The function is supposed to return &true; if
</para> it was able to successfully retrieve the resource and &false; otherwise.
</para></listitem>
<para> <listitem><para>
The second function is supposed to retrieve the last modification time The second function, <literal>timestamp()</literal> is supposed to
of the requested resource (as a UNIX timestamp). The second parameter retrieve the last modification time of the requested resource, as a UNIX
timestamp. The second parameter <parameter>$timestamp</parameter>
is a variable passed by reference where the timestamp should be stored. is a variable passed by reference where the timestamp should be stored.
The function is supposed to return <literal>true</literal> if the The function is supposed to return &true; if the timestamp could be
timestamp could be succesfully determined, and <literal>false</literal> succesfully determined, or &false; otherwise.
otherwise. </para></listitem>
</para>
<para> <listitem><para>
The third function is supposed to return <literal>true</literal> or The third function, <literal>secure()</literal>is supposed to return
<literal>false</literal>, depending on whether the requested resource &true; or &false;, depending on whether the requested resource is secure
is secure or not. This function is used only for template resources but or not. This function is used only for template resources but
should still be defined. should still be defined.
</para> </para></listitem>
<para> <listitem><para>
The fourth function is supposed to return <literal>true</literal> or The fourth function, <literal>trusted()</literal> is supposed to return
<literal>false</literal>, depending on whether the requested resource &true; or &false;, depending on whether the requested resource
is trusted or not. This function is used for only for PHP script is trusted or not. This function is used for only for PHP script
components requested by <command>include_php</command> tag or components requested by <link linkend="language.function.include.php">
<command>insert</command> tag with <structfield>src</structfield> <varname>{include_php}</varname></link> tag or
attribute. However, it should still be defined even for template <link linkend="language.function.insert"><varname>{insert}</varname></link>
resources. tag with the <parameter>src</parameter> attribute. However, it should still
</para> be defined even for template resources.
<para> </para></listitem>
See also </itemizedlist>
<link linkend="api.register.resource">register_resource()</link>,
<link linkend="api.unregister.resource">unregister_resource()</link>.
</para>
<example> <example>
<title>resource plugin</title> <title>resource plugin</title>
<programlisting role="php"> <programlisting role="php">
@@ -84,7 +84,7 @@
<?php <?php
/* /*
* Smarty plugin * Smarty plugin
* ------------------------------------------------------------- * -------------------------------------------------------------
* File: resource.db.php * File: resource.db.php
* Type: resource * Type: resource
* Name: db * Name: db
@@ -136,6 +136,13 @@ function smarty_resource_db_trusted($tpl_name, &$smarty)
]]> ]]>
</programlisting> </programlisting>
</example> </example>
<para>
See also
<link linkend="api.register.resource"><varname>register_resource()</varname></link>,
<link linkend="api.unregister.resource"><varname>unregister_resource()</varname></link>.
</para>
</sect1> </sect1>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file

18
docs/en/programmers/plugins/plugins-writing.xml
View File

@@ -26,11 +26,19 @@ require_once $smarty->_get_plugin_filepath('function', 'html_options');
</programlisting> </programlisting>
<para> <para>
As a general rule, Smarty object is always passed to the plugins As a general rule, Smarty object is always passed to the plugins
as the last parameter (with two exceptions: modifiers do not get as the last parameter with two exceptions:
passed the Smarty object at all and blocks get passed </para>
<parameter>&amp;$repeat</parameter> after the Smarty object to keep <itemizedlist>
backwards compatibility to older versions of Smarty). <listitem><para>
</para> modifiers do not get passed the Smarty object at all
</para></listitem>
<listitem><para>
blocks get passed
<parameter>$repeat</parameter> after the Smarty object to keep
backwards compatibility to older versions of Smarty.
</para></listitem>
</itemizedlist>
</sect1> </sect1>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file