smarty-php/smarty
1
0
Fork 0
mirror of https://github.com/smarty-php/smarty.git synced 2025-08-06 03:14: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>
</funcsynopsis>
<para>
Block functions are functions of the form: {func} .. {/func}. In other
words, they enclose a template block and operate on the contents of
this block. Block functions take precedence over custom functions of
the same name, that is, you cannot have both custom function {func} and
block function {func} .. {/func}.
Block functions are functions of the form:
<literal>{func} .. {/func}</literal>. In other words, they enclose a
template block and operate on the contents of
this block. Block functions take precedence over
<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>
<itemizedlist>
<listitem><para>
By default your function implementation is called twice by
Smarty: once for the opening tag, and once for the closing tag
(see <literal>&amp;$repeat</literal> below how to change this).
</para>
<para>
Only the opening tag of the block function may have attributes. All
Smarty: once for the opening tag, and once for the closing tag.
(See <literal>$repeat</literal> below on how to change this.)
</para></listitem>
<listitem><para>
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
in the <parameter>$params</parameter> as an associative array. You can
access those values as e.g. <varname>$params['start']</varname>.
in the <parameter>$params</parameter> variable as an associative array.
The opening tag attributes are also accessible to your function
when processing the closing tag.
</para>
<para>
The value of <parameter>$content</parameter> variable depends on
</para></listitem>
<listitem><para>
The value of the <parameter>$content</parameter> variable depends on
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.
Note that the template block will have already been processed by
Smarty, so all you will receive is the template output, not the
template source.
</para>
</para></listitem>
<para>
The parameter <parameter>&amp;$repeat</parameter> is passed by
<listitem><para>
The parameter <parameter>$repeat</parameter> is passed by
reference to the function implementation and provides a
possibility for it to control how many times the block is
displayed. By default <parameter>$repeat</parameter> is
<literal>true</literal> at the first call of the block-function
(the block opening tag) and <literal>false</literal> on all
subsequent calls to the block function (the block's closing tag).
&true; at the first call of the block-function (the opening tag)
and &false; on all subsequent calls to the block function
(the block's closing tag).
Each time the function implementation returns with
<parameter>&amp;$repeat</parameter> being true, the contents between
{func} .. {/func} are evaluated and the function implementation
is called again with the new block contents in the parameter
<parameter>$repeat</parameter> being &true;, the contents between
<literal>{func}...{/func}</literal> are evaluated and the function
implementation is called again with the new block contents in the parameter
<parameter>$content</parameter>.
</para>
</para></listitem>
</itemizedlist>
<para>
If you have nested block functions, it's possible to find out what the
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.
</para>
<para>
See also:
<link linkend="api.register.block">register_block()</link>,
<link linkend="api.unregister.block">unregister_block()</link>.
</para>
<example>
<title>block function</title>
<programlisting role="php">
@@ -83,16 +85,26 @@
*/
function smarty_block_translate($params, $content, &$smarty, &$repeat)
{
if (isset($content)) {
$lang = $params['lang'];
// do some intelligent translation thing here with $content
return $translation;
// only output on the closing tag
if(!$repeat){
if (isset($content)) {
$lang = $params['lang'];
// do some intelligent translation thing here with $content
return $translation;
}
}
}
?>
]]>
</programlisting>
</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>
<!-- 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.
They are useful for injecting PHP code or time-sensitive static
content into the template. If there is both a compiler function and a
custom function registered under the same name, the compiler function
has precedence.
<link linkend="language.custom.functions">custom function</link> registered
under the same name, the compiler function has precedence.
</para>
<funcsynopsis>
<funcprototype>
@@ -21,13 +21,9 @@
delimiter, and the Smarty object. It's supposed to return the PHP code
to be injected into the compiled template.
</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>
<title>simple compiler function</title>
<title>A simple compiler function</title>
<programlisting role="php">
<![CDATA[
<?php
@@ -52,8 +48,10 @@ function smarty_compiler_tplheader($tag_arg, &$smarty)
This function can be called from the template as:
</para>
<programlisting>
<![CDATA[
{* this function gets executed at compile time only *}
{tplheader}
]]>
</programlisting>
<para>
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>
</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>
<!-- Keep this comment at the end of the file

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

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

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

@@ -3,7 +3,7 @@
<sect1 id="plugins.inserts"><title>Inserts</title>
<para>
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.
</para>
<funcsynopsis>
@@ -19,7 +19,7 @@
</para>
<para>
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.
</para>
<example>
@@ -29,7 +29,7 @@
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* -------------------------------------------------------------
* File: insert.time.php
* Type: time
* Name: time

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

@@ -2,9 +2,9 @@
<!-- $Revision$ -->
<sect1 id="plugins.modifiers"><title>Modifiers</title>
<para>
Modifiers 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.
<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>
@@ -15,20 +15,16 @@
</funcsynopsis>
<para>
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
optional, depending on what kind of operation is supposed to be
performed.
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 return the result of its processing.
</para>
<para>
See also
<link linkend="api.register.modifier">register_modifier()</link>,
<link linkend="api.unregister.modifier">unregister_modifier()</link>.
The modifier has to <ulink url="&url.php-manual;return">return</ulink>
the result of its processing.
</para>
<example>
<title>simple modifier plugin</title>
<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.
@@ -55,7 +51,7 @@ function smarty_modifier_capitalize($string)
</example>
<para></para>
<example>
<title>more complex modifier plugin</title>
<title>More complex modifier plugin</title>
<programlisting role="php">
<![CDATA[
<?php
@@ -66,7 +62,7 @@ function smarty_modifier_capitalize($string)
* Type: modifier
* Name: truncate
* 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.
* -------------------------------------------------------------
*/
@@ -91,6 +87,11 @@ function smarty_modifier_truncate($string, $length = 80, $etc = '...',
]]>
</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

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

@@ -7,7 +7,7 @@
convention in order to be located by Smarty.
</para>
<para>
The plugin files must be named as follows:
<emphasis role="bold">plugin files</emphasis> must be named as follows:
<blockquote>
<para>
<filename>
@@ -16,7 +16,9 @@
</para>
</blockquote>
</para>
<para>
<itemizedlist>
<listitem><para>
Where <literal>type</literal> is one of these plugin types:
<itemizedlist spacing="compact">
<listitem><simpara>function</simpara></listitem>
@@ -30,27 +32,41 @@
<listitem><simpara>insert</simpara></listitem>
</itemizedlist>
</para>
<para>
And <literal>name</literal> should be a valid identifier (letters,
numbers, and underscores only).
</listitem>
<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>
</listitem>
</itemizedlist>
<para>
Some examples: <literal>function.html_select_date.php</literal>,
<literal>resource.db.php</literal>,
<literal>modifier.spacify.php</literal>.
</para>
<para>
The plugin functions inside the plugin files must be named as follows:
<emphasis role="bold">plugin functions</emphasis> inside the PHP files must be named as follows:
<blockquote>
<para>
<function>smarty_<replaceable>type</replaceable>_<replaceable>name</replaceable></function>
</para>
</blockquote>
</para>
<para>
<itemizedlist>
<listitem><para>
The meanings of <literal>type</literal> and <literal>name</literal> are
the same as before.
</para>
the same as above.
</para></listitem>
<listitem><para>
An example modifier name <varname>foo</varname> would be <literal>function smarty_modifier_foo()</literal>.
</para></listitem>
</itemizedlist>
<para>
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

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

@@ -19,7 +19,7 @@
the processing and return the results.
</para>
<example>
<title>output filter plugin</title>
<title>An output filter plugin</title>
<programlisting role="php">
<![CDATA[
<?php
@@ -29,7 +29,7 @@
* File: outputfilter.protect_email.php
* Type: outputfilter
* 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
* -------------------------------------------------------------
*/
@@ -42,6 +42,13 @@
]]>
</programlisting>
</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>
<!-- 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>
</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>
<!-- 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>
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
the first parameter and the Smarty object as the last parameter. The
rest of parameters depend on the function.
@@ -39,44 +39,44 @@
</funcprototype>
</funcsynopsis>
<para>
The first function is supposed to retrieve the resource. Its second
parameter is a variable passed by reference where the result should be
stored. The function is supposed to return <literal>true</literal> if
it was able to successfully retrieve the resource and
<literal>false</literal> otherwise.
</para>
<itemizedlist>
<listitem><para>
The first function, <literal>source()</literal> is supposed to retrieve
the resource. Its second parameter <parameter>$source</parameter> is a
variable passed by reference where the result should be
stored. The function is supposed to return &true; if
it was able to successfully retrieve the resource and &false; otherwise.
</para></listitem>
<para>
The second function is supposed to retrieve the last modification time
of the requested resource (as a UNIX timestamp). The second parameter
<listitem><para>
The second function, <literal>timestamp()</literal> is supposed to
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.
The function is supposed to return <literal>true</literal> if the
timestamp could be succesfully determined, and <literal>false</literal>
otherwise.
</para>
The function is supposed to return &true; if the timestamp could be
succesfully determined, or &false; otherwise.
</para></listitem>
<para>
The third function is supposed to return <literal>true</literal> or
<literal>false</literal>, depending on whether the requested resource
is secure or not. This function is used only for template resources but
<listitem><para>
The third function, <literal>secure()</literal>is supposed to return
&true; or &false;, depending on whether the requested resource is secure
or not. This function is used only for template resources but
should still be defined.
</para>
</para></listitem>
<para>
The fourth function is supposed to return <literal>true</literal> or
<literal>false</literal>, depending on whether the requested resource
<listitem><para>
The fourth function, <literal>trusted()</literal> is supposed to return
&true; or &false;, depending on whether the requested resource
is trusted or not. This function is used for only for PHP script
components requested by <command>include_php</command> tag or
<command>insert</command> tag with <structfield>src</structfield>
attribute. However, it should still be defined even for template
resources.
</para>
<para>
See also
<link linkend="api.register.resource">register_resource()</link>,
<link linkend="api.unregister.resource">unregister_resource()</link>.
</para>
components requested by <link linkend="language.function.include.php">
<varname>{include_php}</varname></link> tag or
<link linkend="language.function.insert"><varname>{insert}</varname></link>
tag with the <parameter>src</parameter> attribute. However, it should still
be defined even for template resources.
</para></listitem>
</itemizedlist>
<example>
<title>resource plugin</title>
<programlisting role="php">
@@ -84,7 +84,7 @@
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* -------------------------------------------------------------
* File: resource.db.php
* Type: resource
* Name: db
@@ -136,6 +136,13 @@ function smarty_resource_db_trusted($tpl_name, &$smarty)
]]>
</programlisting>
</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>
<!-- 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>
<para>
As a general rule, Smarty object is always passed to the plugins
as the last parameter (with two exceptions: modifiers do not get
passed the Smarty object at all and blocks get passed
<parameter>&amp;$repeat</parameter> after the Smarty object to keep
backwards compatibility to older versions of Smarty).
</para>
as the last parameter with two exceptions:
</para>
<itemizedlist>
<listitem><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>
<!-- Keep this comment at the end of the file