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 of formatting

Browse Source
This commit is contained in:
pete_morgan
2006-09-27 01:47:51 +00:00
parent 7a82d2caf9
commit e521084a10
6 changed files with 183 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
docs/en/programmers/advanced-features/advanced-features-objects.xml
View File

@@ -3,17 +3,26 @@
<sect1 id="advanced.features.objects">
<title>Objects</title>
<para>
Smarty allows access to PHP
<ulink url="&url.php-manual;object">objects</ulink> through the templates.
There are
two ways to access them. One way is to
<link linkend="api.register.object">register objects</link> to the template,
then use access them via syntax similar to
<link linkend="language.custom.functions">custom functions</link>.
The other way
is to <link linkend="api.assign">assign()</link> objects
to the templates and access them much like any other
assigned variable. The first method has a much nicer template syntax. It
Smarty allows access to PHP
<ulink url="&url.php-manual;object">objects</ulink> through the templates.
There are two ways to access them.
</para>
<itemizedlist spacing="compact">
<listitem><para>
One way is to <link linkend="api.register.object">register objects</link> to
the template, then use access them via syntax similar to
<link linkend="language.custom.functions">custom functions</link>.
</para></listitem>
<listitem><para>
The other way is to <link linkend="api.assign"><varname>assign()</varname>
</link> objects to the templates and access them much like any other
assigned variable.
</para></listitem>
</itemizedlist>
<para>
The first method has a much nicer template syntax. It
is also more secure, as a registered object can be restricted to certain
methods or properties. However,
<emphasis role="bold">a registered object cannot be looped over
@@ -22,9 +31,9 @@
keep template syntax to a minimum.
</para>
<para>
If <link linkend="variable.security">$security</link> is enabled,
no private methods or functions can be accessed
(begininning with "_"). If a method and property of the same name exist,
If <link linkend="variable.security"><parameter>$security</parameter></link>
is enabled, no private methods or functions can be accessed
(begininning with '_'). If a method and property of the same name exist,
the method will be used.
</para>
<para>
@@ -38,19 +47,20 @@
An associative array is passed
as the first parameter, and the smarty object as the second. If you want
the parameters passed one at a time for each argument like traditional
object parameter passing, set the fourth registration parameter to false.
object parameter passing, set the fourth registration parameter to &false;.
</para>
<para>
The optional fifth parameter has only effect with
<parameter>format</parameter> being <literal>true</literal>
<parameter>format</parameter> being &true;
and contains a list of methods that should be treated as
blocks. That means these methods have a closing tag in the
template
(<literal>{foobar->meth2}...{/foobar->meth2}</literal>) and
the parameters to the methods have the same synopsis as the
parameters for
<link linkend="plugins.block.functions">block-function-plugins</link>:
They get 4 parameters
<link linkend="plugins.block.functions">
<varname>block-function-plugins</varname></link>:
They get the four parameters
<parameter>$params</parameter>,
<parameter>$content</parameter>,
<parameter>&amp;$smarty</parameter> and
@@ -58,7 +68,7 @@
block-function-plugins.
</para>
<example>
<title>using a registered or assigned object</title>
<title>Using a registered or assigned object</title>
<programlisting role="php">
<![CDATA[
<?php
@@ -71,14 +81,17 @@ class My_Object {
}
$myobj = new My_Object;
// registering the object (will be by reference)
$smarty->register_object('foobar',$myobj);
// if we want to restrict access to certain methods or properties, list them
$smarty->register_object('foobar',$myobj,array('meth1','meth2','prop1'));
// if you want to use the traditional object parameter format, pass a boolean of false
$smarty->register_object('foobar',$myobj,null,false);
// We can also assign objects. Assign by ref when possible.
// We can also assign objects. assign_by_ref when possible.
$smarty->assign_by_ref('myobj', $myobj);
$smarty->display('index.tpl');
@@ -86,7 +99,7 @@ $smarty->display('index.tpl');
]]>
</programlisting>
<para>
And here's how to access your objects in index.tpl:
And here's how to access your objects in <filename>index.tpl</filename>:
</para>
<programlisting>
<![CDATA[
@@ -104,8 +117,9 @@ the output was {$output}
</example>
<para>
See also <link
linkend="api.register.object">register_object()</link> and <link
linkend="api.assign">assign()</link>
linkend="api.register.object"><varname>register_object()</varname></link>
and
<link linkend="api.assign"><varname>assign()</varname></link>.
</para>
</sect1>
<!-- Keep this comment at the end of the file

37
docs/en/programmers/advanced-features/advanced-features-outputfilters.xml
View File

@@ -3,29 +3,30 @@
<sect1 id="advanced.features.outputfilters">
<title>Output Filters</title>
<para>
When the template is invoked via
<link linkend="api.display">display()</link> or
<link linkend="api.fetch">fetch()</link>, its output can be
sent through one or more output filters. This differs from
<link linkend="advanced.features.postfilters">postfilters</link>
When the template is invoked via
<link linkend="api.display"><varname>display()</varname></link> or
<link linkend="api.fetch"><varname>fetch()</varname></link>, its output can
be sent through one or more output filters. This differs from
<link linkend="advanced.features.postfilters">
<varname>postfilters</varname></link>
because postfilters operate on compiled templates before they are saved to
the disk, whereas output filters operate on the template output when it is
executed.
</para>
<para>
Output filters can be either
Output filters can be either
<link linkend="api.register.outputfilter">registered</link> or loaded
from the
<link linkend="variable.plugins.dir">plugins directory</link> by using the
<link linkend="api.load.filter">load_filter()</link> function or by
setting the
<link linkend="variable.autoload.filters">$autoload_filters</link>
variable. Smarty will pass the template output as the first argument,
from the
<link linkend="variable.plugins.dir">plugins directory</link> by using the
<link linkend="api.load.filter"><varname>load_filter()</varname></link>
method or by setting the <link linkend="variable.autoload.filters">
<parameter>$autoload_filters</parameter></link> variable.
Smarty will pass the template output as the first argument,
and expect the function to return the result of the processing.
</para>
<example>
<title>using a template outputfilter</title>
<title>Using a template outputfilter</title>
<programlisting role="php">
<![CDATA[
<?php
@@ -49,12 +50,12 @@ $smarty->display('index.tpl');
</programlisting>
</example>
<para>
See also
<link linkend="api.register.outputfilter">register_outpurfilter()</link>,
<link linkend="api.load.filter">load_filter()</link>,
<link linkend="variable.autoload.filters">$autoload_filters</link>,
See also
<link linkend="api.register.outputfilter"><varname>register_outpurfilter()</varname></link>,
<link linkend="api.load.filter"><varname>load_filter()</varname></link>,
<link linkend="variable.autoload.filters"><parameter>$autoload_filters</parameter></link>,
<link linkend="advanced.features.postfilters">postfilters</link> and
<link linkend="variable.plugins.dir">$plugins_dir</link>.
<link linkend="variable.plugins.dir"><parameter>$plugins_dir</parameter></link>.
</para>
</sect1>
<!-- Keep this comment at the end of the file

22
docs/en/programmers/advanced-features/advanced-features-postfilters.xml
View File

@@ -4,19 +4,19 @@
<title>Postfilters</title>
<para>
Template postfilters are PHP functions that your templates are ran through
after they are compiled. Postfilters can be either
<emphasis>after they are compiled</emphasis>. Postfilters can be either
<link linkend="api.register.postfilter">registered</link> or loaded
from the <link linkend="variable.plugins.dir">plugins directory</link>
by using the
<link linkend="api.load.filter">load_filter()</link> function or by
setting the
<link linkend="variable.autoload.filters">$autoload_filters</link>
variable. Smarty will pass the compiled template code as the first
by using the
<link linkend="api.load.filter"><varname>load_filter()</varname></link>
function or by setting the <link linkend="variable.autoload.filters">
<parameter>$autoload_filters</parameter></link> variable.
Smarty will pass the compiled template code as the first
argument, and expect the function to return the result of the
processing.
</para>
<example>
<title>using a template postfilter</title>
<title>Using a template postfilter</title>
<programlisting role="php">
<![CDATA[
<?php
@@ -33,7 +33,8 @@ $smarty->display('index.tpl');
]]>
</programlisting>
<para>
This will make the compiled Smarty template index.tpl look like:
The postfilter above will make the compiled Smarty template
<filename>index.tpl</filename> look like:
</para>
<screen>
<![CDATA[
@@ -43,10 +44,11 @@ $smarty->display('index.tpl');
</screen>
</example>
<para>
See also <link linkend="api.register.postfilter">register_postfilter()</link>,
See also
<link linkend="api.register.postfilter"><varname>register_postfilter()</varname></link>,
<link linkend="advanced.features.prefilters">prefilters</link>
and
<link linkend="api.load.filter">load_filter()</link>.
<link linkend="api.load.filter"><varname>load_filter()</varname></link>.
</para>
</sect1>
<!-- Keep this comment at the end of the file

21
docs/en/programmers/advanced-features/advanced-features-prefilters.xml
View File

@@ -4,27 +4,27 @@
<title>Prefilters</title>
<para>
Template prefilters are PHP functions that your templates are ran through
before they are compiled. This is good for preprocessing your templates
to remove unwanted comments, keeping an eye on what people are putting
in their templates, etc.
<emphasis>before they are compiled</emphasis>. This is good for preprocessing
your templates to remove unwanted comments, keeping an eye on what people are
putting in their templates, etc.
</para>
<para>
Prefilters can be either <link
linkend="api.register.prefilter">registered</link> or loaded from
the <link linkend="variable.plugins.dir">plugins directory</link>
by using <link
linkend="api.load.filter">load_filter()</link> function or by setting
the <link linkend="variable.autoload.filters">$autoload_filters</link>
variable.
linkend="api.load.filter"><varname>load_filter()</varname></link> function or
by setting the <link linkend="variable.autoload.filters">
<parameter>$autoload_filters</parameter></link> variable.
</para>
<para>
Smarty will pass the template source code as the first argument, and
expect the function to return the resulting template source code.
</para>
<example>
<title>using a template prefilter</title>
<title>Using a template prefilter</title>
<para>
This will remove all the comments in the template source.
This will remove all the html comments in the template source.
</para>
<programlisting role="php">
<![CDATA[
@@ -43,10 +43,11 @@ $smarty->display('index.tpl');
</programlisting>
</example>
<para>See also <link linkend="api.register.prefilter">register_prefilter()</link>,
<para>See also
<link linkend="api.register.prefilter"><varname>register_prefilter()</varname></link>,
<link linkend="advanced.features.postfilters">postfilters</link>
and
<link linkend="api.load.filter">load_filter()</link>.
<link linkend="api.load.filter"><varname>load_filter()</varname></link>.
</para>
</sect1>
<!-- Keep this comment at the end of the file

94
docs/en/programmers/advanced-features/section-template-cache-handler-func.xml
View File

@@ -4,34 +4,64 @@
<title>Cache Handler Function</title>
<para>
As an alternative to using the default file-based caching mechanism, you
can specify a custom cache handling function that will be used to read,
write and clear cached files.
can specify a custom cache handling function that will be used to
<literal>read</literal>, <literal>write</literal> and
<literal>clear</literal> cached files.
</para>
<para>
Create a function in your application that Smarty will use as a
cache handler. Set the name of it in the
<link linkend="variable.cache.handler.func">$cache_handler_func</link>
class variable. Smarty will now use this to handle cached data. The
first argument is the action, which will be one of 'read', 'write' and
'clear'. The second parameter is the Smarty object. The third parameter
is the cached content. Upon a write, Smarty passes the cached content
in these parameters. Upon a 'read', Smarty expects your function to
accept this parameter by reference and populate it with the cached
data. Upon a 'clear', pass a dummy variable here since it is not used.
The fourth parameter is the name of the template file (needed for
read/write), the fifth parameter is the cache_id (optional), and the
sixth is the compile_id (optional).
</para>
<para>
Note: The last parameter ($exp_time) was added in Smarty-2.6.0.
</para>
<link linkend="variable.cache.handler.func">
<parameter>$cache_handler_func</parameter></link>
class variable. Smarty will now use this to handle cached data.
</para>
<itemizedlist>
<listitem><para>
The first argument is the action, which will be one of
<literal>read</literal>, <literal>write</literal> and
<literal>clear</literal>.
</para></listitem>
<listitem><para>
The second parameter is the Smarty object.
</para></listitem>
<listitem><para>The third parameter
is the cached content. Upon a <literal>write</literal>, Smarty passes the
cached content in these parameters. Upon a <literal>read</literal>,
Smarty expects your function to accept this parameter by reference and
populate it with the cached data. Upon a <literal>clear</literal>, pass a
dummy variable here since it is not used.
</para></listitem>
<listitem><para>
The fourth parameter is the <parameter>name</parameter> of the template
file, needed for read/write.
</para></listitem>
<listitem><para>
The fifth parameter is the optional <parameter>$cache_id</parameter>.
</para></listitem>
<listitem><para>
The sixth is the optional <link linkend="variable.compile.id">
<parameter>$compile_id</parameter></link>.
</para></listitem>
<listitem><para>
The seventh and last parameter <parameter>$exp_time</parameter>
was added in Smarty-2.6.0.
</para></listitem>
</itemizedlist>
<example>
<title>example using MySQL as a cache source</title>
<title>Example using MySQL as a cache source</title>
<programlisting role="php">
<![CDATA[
<?php
/*
/**************************************************
example usage:
include('Smarty.class.php');
@@ -44,7 +74,7 @@ $smarty->display('index.tpl');
mysql database is expected in this format:
create database SMARTY_CACHE;
create table CACHE_PAGES(
@@ -52,7 +82,7 @@ CacheID char(32) PRIMARY KEY,
CacheContents MEDIUMTEXT NOT NULL
);
*/
**************************************************/
function mysql_cache_handler($action, &$smarty_obj, &$cache_content, $tpl_file=null, $cache_id=null, $compile_id=null, $exp_time=null)
{
@@ -62,10 +92,10 @@ function mysql_cache_handler($action, &$smarty_obj, &$cache_content, $tpl_file=n
$db_pass = 'mypass';
$db_name = 'SMARTY_CACHE';
$use_gzip = false;
// create unique cache id
$CacheID = md5($tpl_file.$cache_id.$compile_id);
if(! $link = mysql_pconnect($db_host, $db_user, $db_pass)) {
$smarty_obj->_trigger_error_msg('cache_handler: could not connect to database');
return false;
@@ -77,10 +107,10 @@ function mysql_cache_handler($action, &$smarty_obj, &$cache_content, $tpl_file=n
// read cache from database
$results = mysql_query("select CacheContents from CACHE_PAGES where CacheID='$CacheID'");
if(!$results) {
$smarty_obj->_trigger_error_msg('cache_handler: query failed.');
$smarty_obj->_trigger_error_msg('cache_handler: query failed.');
}
$row = mysql_fetch_array($results,MYSQL_ASSOC);
if($use_gzip && function_exists('gzuncompress')) {
$cache_content = gzuncompress($row['CacheContents']);
} else {
@@ -90,7 +120,7 @@ function mysql_cache_handler($action, &$smarty_obj, &$cache_content, $tpl_file=n
break;
case 'write':
// save cache to database
if($use_gzip && function_exists("gzcompress")) {
// compress the contents for storage efficiency
$contents = gzcompress($cache_content);
@@ -102,7 +132,7 @@ function mysql_cache_handler($action, &$smarty_obj, &$cache_content, $tpl_file=n
'".addslashes($contents)."')
");
if(!$results) {
$smarty_obj->_trigger_error_msg('cache_handler: query failed.');
$smarty_obj->_trigger_error_msg('cache_handler: query failed.');
}
$return = $results;
break;
@@ -110,12 +140,12 @@ function mysql_cache_handler($action, &$smarty_obj, &$cache_content, $tpl_file=n
// clear cache info
if(empty($cache_id) && empty($compile_id) && empty($tpl_file)) {
// clear them all
$results = mysql_query('delete from CACHE_PAGES');
$results = mysql_query('delete from CACHE_PAGES');
} else {
$results = mysql_query("delete from CACHE_PAGES where CacheID='$CacheID'");
$results = mysql_query("delete from CACHE_PAGES where CacheID='$CacheID'");
}
if(!$results) {
$smarty_obj->_trigger_error_msg('cache_handler: query failed.');
$smarty_obj->_trigger_error_msg('cache_handler: query failed.');
}
$return = $results;
break;
@@ -127,7 +157,7 @@ function mysql_cache_handler($action, &$smarty_obj, &$cache_content, $tpl_file=n
}
mysql_close($link);
return $return;
}
?>

80
docs/en/programmers/advanced-features/template-resources.xml
View File

@@ -4,37 +4,42 @@
<title>Resources</title>
<para>
The templates may come from a variety of sources. When you
<link linkend="api.display">display()</link> or
<link linkend="api.fetch">fetch()</link>
<link linkend="api.display"><varname>display()</varname></link> or
<link linkend="api.fetch"><varname>fetch()</varname></link>
a template, or when you include a template from within another template,
you supply a resource type, followed by the appropriate path and template
name. If a resource is not explicitly given the value of <link
linkend="variable.default.resource.type">$default_resource_type</link> is
assumed.
linkend="variable.default.resource.type">
<parameter>$default_resource_type</parameter></link> is assumed.
</para>
<sect2 id="templates.from.template.dir">
<title>Templates from $template_dir</title>
<para>
Templates from the
<link linkend="variable.template.dir">$template_dir</link> do not require a template
resource, although you can use the file: resource for consistancy.
Just supply the path to the template you want to use relative to the
<link linkend="variable.template.dir">$template_dir</link>
root directory.
Templates from the <link linkend="variable.template.dir">
<parameter>$template_dir</parameter></link> do not require a template
resource, although you can use the <literal>file:</literal> resource
for consistancy. Just supply the path to the template you want to use
relative to the <link linkend="variable.template.dir">
<parameter>$template_dir</parameter></link> root directory.
</para>
<example>
<title>using templates from $template_dir</title>
<title>Using templates from the $template_dir</title>
<programlisting role="php">
<![CDATA[
<?php
$smarty->display("index.tpl");
$smarty->display("admin/menu.tpl");
$smarty->display("file:admin/menu.tpl"); // same as one above
$smarty->display('index.tpl');
$smarty->display('admin/menu.tpl');
$smarty->display('file:admin/menu.tpl'); // same as one above
?>
{* from within Smarty template *}
{include file="index.tpl"}
{include file="file:index.tpl"} {* same as one above *}
]]>
</programlisting>
<para>From within a Smarty template</para>
<programlisting>
<![CDATA[
{include file='index.tpl'}
{* below is same as above *}
{include file='file:index.tpl'}
]]>
</programlisting>
</example>
@@ -42,28 +47,27 @@ $smarty->display("file:admin/menu.tpl"); // same as one above
<sect2 id="templates.from.any.dir">
<title>Templates from any directory</title>
<para>
Templates outside of the
<link linkend="variable.template.dir">$template_dir</link>
require the file: template
resource type, followed by the absolute path and name of the
template.
Templates outside of the <link linkend="variable.template.dir">
<parameter>$template_dir</parameter></link>
require the <literal>file:</literal> template resource type, followed by
the absolute path to the template.
</para>
<example>
<title>using templates from any directory</title>
<title>Using templates from any directory</title>
<programlisting role="php">
<![CDATA[
<?php
$smarty->display("file:/export/templates/index.tpl");
$smarty->display("file:/path/to/my/templates/menu.tpl");
$smarty->display('file:/export/templates/index.tpl');
$smarty->display('file:/path/to/my/templates/menu.tpl');
?>
]]>
</programlisting>
<para>
And from within Smarty template:
And from within a Smarty template:
</para>
<programlisting>
<![CDATA[
{include file="file:/usr/local/share/templates/navigation.tpl"}
{include file='file:/usr/local/share/templates/navigation.tpl'}
]]>
</programlisting>
</example>
@@ -73,16 +77,16 @@ $smarty->display("file:/path/to/my/templates/menu.tpl");
<para>
If you are using a Windows machine, filepaths usually include a
drive letter (C:) at the beginning of the pathname. Be sure to use
"file:" in the path to avoid namespace conflicts and get the
desired results.
<literal>file:</literal> in the path to avoid namespace conflicts and
get the desired results.
</para>
<example>
<title>using templates from windows file paths</title>
<title>Using templates from windows file paths</title>
<programlisting role="php">
<![CDATA[
<?php
$smarty->display("file:C:/export/templates/index.tpl");
$smarty->display("file:F:/path/to/my/templates/menu.tpl");
$smarty->display('file:C:/export/templates/index.tpl');
$smarty->display('file:F:/path/to/my/templates/menu.tpl');
?>
]]>
</programlisting>
@@ -91,7 +95,7 @@ $smarty->display("file:F:/path/to/my/templates/menu.tpl");
</para>
<programlisting>
<![CDATA[
{include file="file:D:/usr/local/share/templates/navigation.tpl"}
{include file='file:D:/usr/local/share/templates/navigation.tpl'}
]]>
</programlisting>
</example>
@@ -116,13 +120,13 @@ $smarty->display("file:F:/path/to/my/templates/menu.tpl");
<note>
<para>
Note that you cannot override the built-in
<literal>file</literal> resource, but you can provide a resource
<literal>file:</literal> resource, but you can provide a resource
that fetches templates from the file system in some other way by
registering under another resource name.
</para>
</note>
<example>
<title>using custom resources</title>
<title>Using custom resources</title>
<programlisting role="php">
<![CDATA[
<?php
@@ -185,7 +189,7 @@ $smarty->display("db:index.tpl");
</para>
<programlisting>
<![CDATA[
{include file="db:/extras/navigation.tpl"}
{include file='db:/extras/navigation.tpl'}
]]>
</programlisting>
</example>
@@ -200,7 +204,7 @@ $smarty->display("db:index.tpl");
on-the-fly.
</para>
<example>
<title>using the default template handler function</title>
<title>Using the default template handler function</title>
<programlisting role="php">
<![CDATA[
<?php