smarty/docs/en/designers/language-custom-functions/language-function-html-checkboxes.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<sect1 id="language.function.html.checkboxes">
 <title>{html_checkboxes}</title>
  <para>
   {html_checkboxes} is a
   <link linkend="language.custom.functions">custom function</link>
   that creates an html checkbox
   group with provided data. It takes care of which item(s) are
   selected by default as well. Required attributes are values and
   output, unless you use options instead. All output is XHTML
   compliant.
 </para>
 
 <informaltable frame="all">
  <tgroup cols="5">
   <colspec colname="param" align="center" />
   <colspec colname="type" align="center" />
   <colspec colname="required" align="center" />
   <colspec colname="default" align="center" />
   <colspec colname="desc" />
   <thead>
    <row>
     <entry>Attribute Name</entry>
     <entry>Type</entry>
     <entry>Required</entry>
     <entry>Default</entry>
     <entry>Description</entry>
    </row>
   </thead>
   <tbody>
    <row>
     <entry>name</entry>
     <entry>string</entry>
     <entry>No</entry>
     <entry><emphasis>checkbox</emphasis></entry>
     <entry>name of checkbox list</entry>
    </row>
    <row>
     <entry>values</entry>
     <entry>array</entry>
     <entry>Yes, unless using options attribute</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>an array of values for checkbox buttons</entry>
    </row>
    <row>
     <entry>output</entry>
     <entry>array</entry>
     <entry>Yes, unless using options attribute</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>an array of output for checkbox buttons</entry>
    </row>
    <row>
     <entry>selected</entry>
     <entry>string/array</entry>
     <entry>No</entry>
     <entry><emphasis>empty</emphasis></entry>
     <entry>the selected checkbox element(s)</entry>
    </row>
    <row>
     <entry>options</entry>
     <entry>associative array</entry>
     <entry>Yes, unless using values and output</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>an associative array of values and output</entry>
    </row>
    <row>
     <entry>separator</entry>
     <entry>string</entry>
     <entry>No</entry>
     <entry><emphasis>empty</emphasis></entry>
     <entry>string of text to separate each checkbox item</entry>
    </row>
    <row>
     <entry>labels</entry>
     <entry>boolean</entry>
     <entry>No</entry>
     <entry><emphasis>true</emphasis></entry>
     <entry>add &lt;label&gt;-tags to the output</entry>
    </row>
    <row>
     <entry>assign</entry>
     <entry>string</entry>
     <entry>No</entry>
     <entry><emphasis>empty</emphasis></entry>
     <entry>assign the output to an array with each checkbox's output
      as one element.</entry>
    </row>
   </tbody>
  </tgroup>
 </informaltable>

 <para>
  All parameters that are not in the list above are printed as
  name/value-pairs inside each of the created &lt;input&gt;-tags.
 </para>
 <example>
  <title>{html_checkboxes}</title>
  <programlisting role="php">
<![CDATA[
<?php

$smarty->assign('cust_ids', array(1000,1001,1002,1003));
$smarty->assign('cust_names', array(
                                'Joe Schmoe',
                                'Jack Smith',
                                'Jane Johnson',
                                'Charlie Brown')
                              );
$smarty->assign('customer_id', 1001);

?>
]]>
  </programlisting>
  <para>
where template is
  </para>
  <programlisting>
<![CDATA[
{html_checkboxes name='id' values=$cust_ids output=$cust_names
   selected=$customer_id  separator='<br />'}
]]>
  </programlisting>
  <para>
   or where PHP code is:
  </para>
  <programlisting role="php">
<![CDATA[
<?php

$smarty->assign('cust_checkboxes', array(
                                     1000 => 'Joe Schmoe',
                                     1001 => 'Jack Smith',
                                     1002 => 'Jane Johnson',
                                     1003 => 'Charlie Brown')
                                   );
$smarty->assign('customer_id', 1001);

?>
]]>
  </programlisting>
  <para>
  and the template is
  </para>
  <programlisting>
<![CDATA[
{html_checkboxes name='id' options=$cust_checkboxes 
   selected=$customer_id separator='<br />'}
]]>
  </programlisting>
  <para>
   both examples will output:
  </para>
  <screen>
<![CDATA[
<label><input type="checkbox" name="id[]" value="1000" />Joe Schmoe</label><br />
<label><input type="checkbox" name="id[]" value="1001" checked="checked" />Jack Smith</label>
<br />
<label><input type="checkbox" name="id[]" value="1002" />Jane Johnson</label><br />
<label><input type="checkbox" name="id[]" value="1003" />Charlie Brown</label><br />
]]>
  </screen>
 </example>
  <example>
    <title>
      Database example (eg PEAR or ADODB):
  </title>
  <programlisting role="php">
<![CDATA[
<?php

$sql = 'select type_id, types from contact_types order by type';
$smarty->assign('contact_types',$db->getAssoc($sql));

$sql = 'select contact_id, contact_type_id, contact '
       .'from contacts where contact_id=12';
$smarty->assign('contact',$db->getRow($sql));

?>
]]>
  </programlisting>
<programlisting>
<![CDATA[
{html_checkboxes name='contact_type_id' options=$contact_types 
        selected=$contact.contact_type_id separator='<br />'}
]]>
</programlisting>
 </example>
 <para>
  See also
  <link linkend="language.function.html.radios">{html_radios}</link>
  and
  <link linkend="language.function.html.options">{html_options}</link>
 </para>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->