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

Major tidy up

Browse Source
This commit is contained in:
pete_morgan
2006-09-25 19:21:24 +00:00
parent 2a251ef091
commit cffb3cf957
1 changed files with 272 additions and 254 deletions
Download Patch File Download Diff File Expand all files Collapse all files

526
docs/en/designers/language-builtin-functions/language-function-section.xml
View File

@@ -3,22 +3,15 @@
<sect1 id="language.function.section">
<title>{section},{sectionelse}</title>
<para>
Template sections are used for looping over
<emphasis role="bold">arrays of data</emphasis>
(just like <link linkend="language.function.foreach">{foreach}</link>). All
<emphasis>{section}</emphasis> tags must be paired with
<emphasis>{/section}</emphasis> tags. Required parameters are
<emphasis>name</emphasis> and <emphasis>loop</emphasis>. The name
of the {section} can be anything you like, made up of letters,
numbers and underscores. Sections can be nested, and the nested
section names must be unique from each other. The loop variable
(usually an array of values) determines the number of times the
section will loop. When printing a variable within a section, the
section name must be given next to variable name within brackets
[]. <emphasis>{sectionelse}</emphasis> is
executed when there are no values in the loop variable.
</para>
A <varname>{section}</varname>
is for looping over <emphasis role="bold">arrays of data</emphasis>,
unlike <link linkend="language.function.foreach"><varname>{foreach}</varname></link>
which is used to loop over a
<emphasis role="bold">single associative array</emphasis>.
Every <varname>{section}</varname> tag must be paired with
a closing <varname>{/section}</varname> tag.
</para>
<informaltable frame="all">
<tgroup cols="5">
<colspec colname="param" align="center" />
@@ -85,26 +78,81 @@
<entry>show</entry>
<entry>boolean</entry>
<entry>No</entry>
<entry><emphasis>true</emphasis></entry>
<entry><emphasis>&true;</emphasis></entry>
<entry>determines whether or not to show this section</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<example>
<title>{section}</title>
<itemizedlist>
<listitem><para>
Required attributes are <parameter>name</parameter> and <parameter>loop</parameter>.
</para></listitem>
<listitem><para>
The <parameter>name</parameter> of the <varname>{section}</varname> can be
anything you like, made up of letters, numbers and underscores, like
<ulink url="&url.php-manual;language.variables">PHP variables</ulink>.
</para></listitem>
<listitem><para>
Sections can be nested, and the nested
<varname>{section}</varname> names must be unique from each other.
</para></listitem>
<listitem><para>
The <parameter>loop</parameter> attribute,
usually an array of values, determines the number of times the
<varname>{section}</varname> will loop.
</para></listitem>
<listitem><para>When printing a variable within a <varname>{section}</varname>, the
<varname>{section}</varname> <parameter>name</parameter> must be given next
to variable name within [brackets].
</para></listitem>
<listitem><para>
<varname>{sectionelse}</varname> is
executed when there are no values in the loop variable.
</para></listitem>
<listitem><para>
A <varname>{section}</varname> also has its own variables that handle
<varname>{section}</varname> properties.
These properties are accessible as: <link linkend="language.variables.smarty.loops">
<parameter>{$smarty.section.name.property}</parameter></link>
where <quote>name</quote> is the attribute <parameter>name</parameter>.
</para></listitem>
<listitem><para>
<varname>{section}</varname> properties are
<link linkend="section.property.index"><parameter>index</parameter></link>,
<link linkend="section.property.index.prev"><parameter>index_prev</parameter></link>,
<link linkend="section.property.index.next"><parameter>index_next</parameter></link>,
<link linkend="section.property.iteration"><parameter>iteration</parameter></link>,
<link linkend="section.property.first"><parameter>first</parameter></link>,
<link linkend="section.property.last"><parameter>last</parameter></link>,
<link linkend="section.property.rownum"><parameter>rownum</parameter></link>,
<link linkend="section.property.loop"><parameter>loop</parameter></link>,
<link linkend="section.property.show"><parameter>show</parameter></link>,
<link linkend="section.property.total"><parameter>total</parameter></link>.
</para></listitem>
</itemizedlist>
<example>
<title>Looping a simple array with {section}</title>
<para><link linkend="api.assign">assign()</link> an array to Smarty from the php script</para>
<programlisting role="php">
<![CDATA[
<?php
$data = array(1000,1001,1002);
$smarty->assign('custid',$data);
?>
]]>
</programlisting>
<para>The template that outputs the array</para>
<programlisting>
<![CDATA[
{* this example will print out all the values of the $custid array *}
@@ -132,9 +180,11 @@ id: 1001<br />
id: 1000<br />
]]>
</screen>
<para>
Another couple of examples without an assigned array.
</para>
</example>
<example>
<title>{section} without an assigned array</title>
<programlisting>
<![CDATA[
{section name=foo start=10 loop=20 step=2}
@@ -156,11 +206,93 @@ id: 1000<br />
20 18 16 14 12 10
]]>
</screen>
</example>
<example>
<title>Naming a {section}</title>
<para>The <parameter>name</parameter> of the <varname>{section}</varname> can be anything
you like, see <ulink url="&url.php-manual;language.variables">PHP variables</ulink>.
It is used to reference the data within the <varname>{section}</varname>.</para>
<programlisting>
<![CDATA[
{section name=anything loop=$myArray}
{$myArray[anything].foo}
{$name[anything]}
{$address[anything].bar}
{/section}
]]>
</programlisting>
</example>
<example>
<title>{section} loop variable</title>
<title>Looping an associative array's with {section}</title>
<para>This is an example of printing an associative array
of data within a <varname>{section}</varname>. Following is the php script to assign the
<parameter>$contacts</parameter> array to Smarty.</para>
<programlisting role="php">
<![CDATA[
<?php
$data = array(
array('name' => 'John Smith', 'home' => '555-555-5555',
'cell' => '666-555-5555', 'email' => 'john@myexample.com'),
array('name' => 'Jack Jones', 'home' => '777-555-5555',
'cell' => '888-555-5555', 'email' => 'jack@myexample.com'),
array('name' => 'Jane Munson', 'home' => '000-555-5555',
'cell' => '123456', 'email' => 'jane@myexample.com')
);
$smarty->assign('contacts',$data);
?>
]]>
</programlisting>
<para>The template to output <parameter>$contacts</parameter></para>
<programlisting>
<![CDATA[
{section name=customer loop=$contacts}
<p>
name: {$contacts[customer].name}<br />
home: {$contacts[customer].home}<br />
cell: {$contacts[customer].cell}<br />
e-mail: {$contacts[customer].email}
</p>
{/section}
]]>
</programlisting>
<para>
The above example will output:
</para>
<screen>
<![CDATA[
<p>
name: John Smith<br />
home: 555-555-5555<br />
cell: 666-555-5555<br />
e-mail: john@myexample.com
</p>
<p>
name: Jack Jones<br />
home phone: 777-555-5555<br />
cell phone: 888-555-5555<br />
e-mail: jack@myexample.com
</p>
<p>
name: Jane Munson<br />
home phone: 000-555-5555<br />
cell phone: 123456<br />
e-mail: jane@myexample.com
</p>
]]>
</screen>
</example>
<example>
<title>{section} demonstrating the <varname>loop</varname> variable</title>
<para>This example assumes that <parameter>$custid</parameter>, <parameter>$name</parameter>
and <parameter>$address</parameter> are all
arrays containing the same number of values. First the php script that assign's the
arrays to Smarty.</para>
<programlisting role="php">
<![CDATA[
<?php
@@ -171,20 +303,16 @@ $smarty->assign('custid',$id);
$fullnames = array('John Smith','Jack Jones','Jane Munson');
$smarty->assign('name',$fullnames);
$addr = array('253 N 45th', '417 Mulberry ln', '5605 apple st');
$addr = array('253 Abbey road', '417 Mulberry ln', '5605 apple st');
$smarty->assign('address',$addr);
?>
]]>
</programlisting>
<para>The <parameter>loop</parameter> variable only determines the number of times to loop.
You can access ANY variable from the template within the <varname>{section}</varname></para>
<programlisting>
<![CDATA[
{*
the loop variable only determines the number of times to loop.
you can access any variable from the template within the section.
This example assumes that $custid, $name and $address are all
arrays containing the same number of values
*}
{section name=customer loop=$custid}
<p>
id: {$custid[customer]}<br />
@@ -202,7 +330,7 @@ $smarty->assign('address',$addr);
<p>
id: 1000<br />
name: John Smith<br />
address: 253 N 45th
address: 253 Abbey road
</p>
<p>
id: 1001<br />
@@ -218,27 +346,15 @@ $smarty->assign('address',$addr);
</screen>
</example>
<example>
<title>{section} naming</title>
<programlisting>
<![CDATA[
{*
the name of the section can be anything you like,
as it is used to reference the data within the section
*}
{section name=anything loop=$custid}
<p>
id: {$custid[anything]}<br />
name: {$name[anything]}<br />
address: {$address[anything]}
</p>
{/section}
]]>
</programlisting>
</example>
<example>
<title>nested sections</title>
<title>Nested {section}'s</title>
<para>
Sections can be nested as deep as you like. With nested sections,
you can access complex data structures, such as multi-dimensional
arrays. This is a php script thats assign's the arrays.
</para>
<programlisting role="php">
<![CDATA[
<?php
@@ -269,14 +385,10 @@ $smarty->assign('contact_info', $info);
?>
]]>
</programlisting>
<para>In this template, <emphasis>$contact_type[customer]</emphasis> is an array of
contact types for the current customer.</para>
<programlisting>
<![CDATA[
{*
sections can be nested as deep as you like. With nested sections,
you can access complex data structures, such as multi-dimensional
arrays. In this example, $contact_type[customer] is an array of
contact types for the current customer.
*}
{section name=customer loop=$custid}
<hr>
id: {$custid[customer]}<br />
@@ -315,85 +427,22 @@ $smarty->assign('contact_info', $info);
</screen>
</example>
<example>
<title>sections and associative arrays</title>
<programlisting role="php">
<![CDATA[
<?php
$data = array(
array('name' => 'John Smith', 'home' => '555-555-5555',
'cell' => '666-555-5555', 'email' => 'john@myexample.com'),
array('name' => 'Jack Jones', 'home' => '777-555-5555',
'cell' => '888-555-5555', 'email' => 'jack@myexample.com'),
array('name' => 'Jane Munson', 'home' => '000-555-5555',
'cell' => '123456', 'email' => 'jane@myexample.com')
);
$smarty->assign('contacts',$data);
?>
]]>
</programlisting>
<programlisting>
<![CDATA[
{*
This is an example of printing an associative array
of data within a section
*}
{section name=customer loop=$contacts}
<p>
name: {$contacts[customer].name}<br />
home: {$contacts[customer].home}<br />
cell: {$contacts[customer].cell}<br />
e-mail: {$contacts[customer].email}
</p>
{/section}
]]>
</programlisting>
<para>
The above example will output:
</para>
<screen>
<![CDATA[
<p>
name: John Smith<br />
home: 555-555-5555<br />
cell: 666-555-5555<br />
e-mail: john@myexample.com
</p>
<p>
name: Jack Jones<br />
home phone: 777-555-5555<br />
cell phone: 888-555-5555<br />
e-mail: jack@myexample.com
</p>
<p>
name: Jane Munson<br />
home phone: 000-555-5555<br />
cell phone: 123456<br />
e-mail: jane@myexample.com
</p>
]]>
</screen>
<para>Database example (eg using Pear or Adodb)</para>
<example>
<title>Database example with a {sectionelse}</title>
<para>Results of a database search (eg ADODB or PEAR) are assigned to Smarty</para>
<programlisting role="php">
<![CDATA[
<?php
$sql = 'select id, name, home, cell, email from contacts';
$smarty->assign('contacts',$db->getAll($sql) );
$sql = 'select id, name, home, cell, email from contacts '
."where name like '$foo%' ";
$smarty->assign('contacts', $db->getAll($sql));
?>
]]>
</programlisting>
<para>The template to output the database result in a HTML table</para>
<programlisting>
<![CDATA[
{*
output database result in a table
*}
<table>
<tr><th>&nbsp;</th><th>Name></th><th>Home</th><th>Cell</th><th>Email</th></tr>
{section name=co loop=$contacts}
@@ -404,60 +453,42 @@ $smarty->assign('contacts',$db->getAll($sql) );
<td>{$contacts[co].cell}</td>
<td>{$contacts[co].email}</td>
<tr>
{sectionelse}
<tr><td colspan="5">No items found</td></tr>
{/section}
</table>
]]>
</programlisting>
</example>
<example>
<title>{sectionelse}</title>
<programlisting>
<![CDATA[
{* sectionelse will execute if there are no $custid values *}
{section name=customer loop=$custid}
id: {$custid[customer]}<br />
{sectionelse}
there are no values in $custid.
{/section}
]]>
</programlisting>
</example>
<para>
Sections also have their own variables that handle section properties.
These are indicated like so:
<link linkend="language.variables.smarty.loops">{$smarty.section.sectionname.varname}</link>
</para>
<note>
<para>
As of Smarty 1.5.0, the syntax for section property variables has
changed from {%sectionname.varname%} to
{$smarty.section.sectionname.varname}. The old syntax is still
supported, but you will only see examples of the new syntax.
</para>
</note>
<sect2 id="section.property.index">
<title>index</title>
<title>.index</title>
<para>
index is used to display the current array index, starting with zero
(or the start attribute if given), and incrementing by one (or by
the step attribute if given.)
<parameter>index</parameter> contains the current array index, starting with zero
or the <parameter>start</parameter> attribute if given It increments by one or by
the <parameter>step</parameter> attribute if given.
</para>
<note>
<title>Technical Note</title>
<para>
If the step and start section properties are not
If the <parameter>step</parameter> and <parameter>start</parameter>
properties are not
modified, then this works the same as the <link
linkend="section.property.iteration">iteration</link> section
property, except it starts at 0 instead of 1.
linkend="section.property.iteration"><parameter>iteration</parameter></link>
property, except it starts at zero instead of one.
</para>
</note>
<example>
<title>{section} property index</title>
<title>{section} <varname>index</varname> property</title>
<para>
<note><title>FYI</title>
<para><parameter>$custid[customer.index]</parameter> and <varname>$custid[customer]</varname>
are identical in meaning.</para>
</note>
</para>
<programlisting>
<![CDATA[
{* FYI, $custid[customer.index] and $custid[customer] are identical in meaning *}
{section name=customer loop=$custid}
{$smarty.section.customer.index} id: {$custid[customer]}<br />
{/section}
@@ -478,48 +509,47 @@ $smarty->assign('contacts',$db->getAll($sql) );
<sect2 id="section.property.index.prev">
<title>index_prev</title>
<title>.index_prev</title>
<para>
index_prev is used to display the previous loop index.
on the first loop, this is set to -1.
<parameter>index_prev</parameter> is the previous loop index.
On the first loop, this is set to -1.
</para>
</sect2>
<sect2 id="section.property.index.next">
<title>index_next</title>
<title>.index_next</title>
<para>
index_next is used to display the next loop index. On the last
loop, this is still one more than the current index (respecting the
setting of the step attribute, if given.)
<parameter>index_next</parameter> is the next loop index. On the last
loop, this is still one more than the current index, respecting the
setting of the <parameter>step</parameter> attribute, if given.
</para>
<example>
<title>{section} property index_next and index_prev</title>
<title><varname>index</varname>, <varname>index_next</varname>
and <varname>index_prev</varname> properties </title>
<programlisting role="php">
<![CDATA[
<?php
$data = array(1001,1002,1003,1004,1005);
$smarty->assign('custid',$data);
$smarty->assign('rows',$data);
?>
]]>
</programlisting>
<para>Template to output the above array in a table</para>
<programlisting>
<![CDATA[
{* FYI, $custid[cus.index] and $custid[cus] are identical in meaning *}
{* $rows[row.index] and $rows[row] are identical in meaning *}
<table>
<tr>
<th>index</th><th>id</th>
<th>index_prev</th><th>prev_id</th>
<th>index_next</th><th>next_id</th>
</tr>
{section name=cus loop=$custid}
{section name=row loop=$rows}
<tr>
<td>{$smarty.section.cus.index}</td><td>{$custid[cus]}</td>
<td>{$smarty.section.cus.index_prev}</td><td>{$custid[cus.index_prev]}</td>
<td>{$smarty.section.cus.index_next}</td><td>{$custid[cus.index_next]}</td>
<td>{$smarty.section.row.index}</td><td>{$rows[row]}</td>
<td>{$smarty.section.row.index_prev}</td><td>{$rows[row.index_prev]}</td>
<td>{$smarty.section.row.index_next}</td><td>{$rows[row.index_next]}</td>
</tr>
{/section}
</table>
@@ -543,35 +573,37 @@ index id index_prev prev_id index_next next_id
<sect2 id="section.property.iteration">
<title>iteration</title>
<title>.iteration</title>
<para>
iteration is used to display the current loop iteration.
<parameter>iteration</parameter> contains the current loop iteration and starts at one.
</para>
<note>
<para>
This is not affected by the section properties start, step and
max, unlike the <link linkend="section.property.index">index</link>
property. Iteration also starts with 1 instead of 0 like index. <link
linkend="section.property.rownum">rownum</link> is an alias to iteration,
they work identical.
This is not affected by the <varname>{section}</varname> properties
<parameter>start</parameter>, <parameter>step</parameter> and <parameter>max</parameter>,
unlike the <link linkend="section.property.index"><parameter>index</parameter></link>
property. <parameter>iteration</parameter> also starts with one instead of zero
unlike <parameter>index</parameter>. <link
linkend="section.property.rownum"><parameter>rownum</parameter></link> is an alias to
<parameter>iteration</parameter>, they are identical.
</para>
</note>
<example>
<title>{section} property iteration</title>
<title>A section's <varname>iteration</varname> property </title>
<programlisting role="php">
<![CDATA[
<?php
// array of 3000 to 3015
$id = range(3000,3015);
$smarty->assign('custid',$id);
$smarty->assign('arr',$id);
?>
]]>
</programlisting>
<para>Template to output every other element of the <varname>$arr</varname>
array as <varname>step</varname>=2</para>
<programlisting>
<![CDATA[
{section name=cu loop=$custid start=5 step=2}
{section name=cu loop=$arr start=5 step=2}
iteration={$smarty.section.cu.iteration}
index={$smarty.section.cu.index}
id={$custid[cu]}<br />
@@ -592,14 +624,14 @@ iteration=6 index=15 id=3015<br />
]]>
</screen>
<para>
This example uses the iteration property to
output a table header block every five rows
(uses <link linkend="language.function.if">{if}</link>
with the mod operator).
Another example uses the <parameter>iteration</parameter> property to
output a table header block every five rows and
uses <link linkend="language.function.if"><varname>{if}</varname></link>
with the mod operator.
</para>
<programlisting>
<![CDATA[
<table>
<table>
{section name=co loop=$contacts}
{if $smarty.section.co.iteration % 5 == 1}
<tr><th>&nbsp;</th><th>Name></th><th>Home</th><th>Cell</th><th>Email</th></tr>
@@ -620,29 +652,27 @@ iteration=6 index=15 id=3015<br />
<sect2 id="section.property.first">
<title>first</title>
<title>.first</title>
<para>
first is set to true if the current section <link
linkend="section.property.iteration">iteration</link> is the first
one.
<parameter>first</parameter> is set to &true; if the current <varname>{section}</varname>
iteration is the initial one.
</para>
</sect2>
<sect2 id="section.property.last">
<title>last</title>
<title>.last</title>
<para>
last is set to true if the current section <link
linkend="section.property.iteration">iteration</link> is the last
one.
<parameter>last</parameter> is set to &true;
if the current section iteration is the final one.
</para>
<example>
<title>{section} property first and last</title>
<title>{section} property <varname>first</varname> and <varname>last</varname></title>
<para>
This example loops the $customers array;
This example loops the <varname>$customers</varname> array,
outputs a header block on the first iteration and
on the last outputs the footer block
(uses section <link linkend="section.property.total">total</link> property)
on the last outputs the footer block. Also uses the
<link linkend="section.property.total"><parameter>total</parameter></link> property.
</para>
<programlisting>
<![CDATA[
@@ -669,29 +699,30 @@ iteration=6 index=15 id=3015<br />
<sect2 id="section.property.rownum">
<title>rownum</title>
<title>.rownum</title>
<para>
rownum is used to display the current loop iteration,
<parameter>rownum</parameter> contains the current loop iteration,
starting with one. It is an alias to <link
linkend="section.property.iteration">iteration</link>, they work
identically.
linkend="section.property.iteration"><parameter>iteration</parameter></link>,
they work identically.
</para>
</sect2>
<sect2 id="section.property.loop">
<title>loop</title>
<title>.loop</title>
<para>
loop is used to display the last index number that this section
looped. This can be used inside or after the section.
</para>
<parameter>loop</parameter> contains the last index number
that this {section}
looped. This can be used inside or after the <varname>{section}</varname>.
</para>
<example>
<title>{section} property index</title>
<title>{section} property <varname>loop</varname>s</title>
<programlisting>
<![CDATA[
{section name=customer loop=$custid}
{$smarty.section.customer.index} id: {$custid[customer]}<br />
{/section}
There were {$smarty.section.customer.loop} customers shown above.
There are {$smarty.section.customer.loop} customers shown above.
]]>
</programlisting>
<para>
@@ -702,30 +733,28 @@ There were {$smarty.section.customer.loop} customers shown above.
0 id: 1000<br />
1 id: 1001<br />
2 id: 1002<br />
There were 3 customers shown above.
There are 3 customers shown above.
]]>
</screen>
</example>
</sect2>
<sect2 id="section.property.show">
<title>show</title>
<title>.show</title>
<para>
<emphasis>show</emphasis> is used as a parameter to section.
<emphasis>show</emphasis> is a boolean value, true or false. If
false, the section will not be displayed. If there is a {sectionelse}
present, that will be alternately displayed.
<parameter>show</parameter> is used as a parameter to section.
<parameter>show</parameter> is a boolean value, &true; or &false;. If
&false;, the section will not be displayed. If there is a
<varname>{sectionelse}</varname> present, that will be alternately displayed.
</para>
<example>
<title>{section} attribute show</title>
<title><varname>show</varname> property </title>
<para>Boolean <varname>$show_customer_info</varname> has been passed from the PHP
application, to regulate whether or not this section shows.</para>
<programlisting>
<![CDATA[
{*
$show_customer_info (true/false) may have been passed from the PHP
application, to regulate whether or not this section shows
*}
{section name=customer loop=$custid show=$show_customer_info}
{$smarty.section.customer.rownum} id: {$custid[customer]}<br />
{section name=customer loop=$customers show=$show_customer_info}
{$smarty.section.customer.rownum} id: {$customers[customer]}<br />
{/section}
{if $smarty.section.customer.show}
@@ -749,35 +778,24 @@ the section was shown.
</screen>
</example>
</sect2>
<sect2 id="section.property.total">
<title>total</title>
<title>.total</title>
<para>
total is used to display the number of iterations that this section
will loop. This can be used inside or after the section.
<parameter>total</parameter> contains the number of iterations that this
<varname>{section}</varname> will loop. This can be used inside or after a
<varname>{section}</varname>.
</para>
<example>
<title>{section} property total</title>
<title><varname>total</varname> property example</title>
<programlisting>
<![CDATA[
{section name=customer loop=$custid step=2}
{$smarty.section.customer.index} id: {$custid[customer]}<br />
{/section}
There were {$smarty.section.customer.total} customers shown above.
There are {$smarty.section.customer.total} customers shown above.
]]>
</programlisting>
<para>
The above example will output:
</para>
<screen>
<![CDATA[
0 id: 1000<br />
2 id: 1002<br />
4 id: 1004<br />
There were 3 customers shown above.
]]>
</screen>
</example>
<para>
See also <link linkend="language.function.foreach">{foreach}</link>