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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<sect1 id="language.function.html.options">
 <title>html_options</title>
 <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>values</entry>
     <entry>array</entry>
     <entry>Yes, unless using options attribute</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>an array of values for dropdown</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 dropdown</entry>
    </row>
    <row>
     <entry>selected</entry>
     <entry>string/array</entry>
     <entry>No</entry>
     <entry><emphasis>empty</emphasis></entry>
     <entry>the selected option 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>name</entry>
     <entry>string</entry>
     <entry>No</entry>
     <entry><emphasis>empty</emphasis></entry>
     <entry>name of select group</entry>
    </row>
   </tbody>
  </tgroup>
 </informaltable>
 <para>
  html_options is a custom function that creates html option 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.
 </para>
 <para>
  If a given value is an array, it will treat it as an html OPTGROUP,
  and display the groups. Recursion is supported with OPTGROUP. All
  output is XHTML compatible.
 </para>
 <para>
  If the optional <emphasis>name</emphasis> attribute is given, the
  &lt;select name="groupname"&gt;&lt;/select&gt; tags will enclose
  the option list. Otherwise only the option list is generated.
 </para>
 <para>
  All parameters that are not in the list above are printed as
  name/value-pairs inside the &lt;select&gt;-tag. They are ignored if
  the optional <emphasis>name</emphasis> is not given.
 </para>
 <example>
  <title>html_options : Example 1</title>
  <programlisting>
<![CDATA[
   index.php:
   ----------

   require('Smarty.class.php');
   $smarty = new Smarty;
   $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);
   $smarty->display('index.tpl');
]]>
  </programlisting>
  <para>
   Where index.tpl is:
  </para>
  <programlisting>
<![CDATA[

   <select name=customer_id>
   {html_options values=$cust_ids selected=$customer_id output=$cust_names}
   </select>
]]>
  </programlisting>
   <para>
    Example 2
   </para>
   <programlisting>
<![CDATA[
   index.php:
   ----------

   require('Smarty.class.php');
   $smarty = new Smarty;
   $smarty->assign('cust_options', array(
   1001 => 'Joe Schmoe',
   1002 => 'Jack Smith',
   1003 => 'Jane Johnson',
   1004 => 'Charlie Brown'));
   $smarty->assign('customer_id', 1001);
   $smarty->display('index.tpl');
]]>
  </programlisting>
  <para>
   Where index.tpl is:
  </para>
  <programlisting>
<![CDATA[

   <select name=customer_id>
   {html_options options=$cust_options selected=$customer_id}
   </select>

]]>
  </programlisting>
  <para>
   Both examples will output:
  </para>
  <screen>
<![CDATA[

   <select name=customer_id>
    <option label="Joe Schmoe" value="1000">Joe Schmoe</option>
    <option label="Jack Smith" value="1001" selected="selected">Jack Smith</option>
    <option label="Jane Johnson" value="1002">Jane Johnson</option>
    <option label="Charlie Brown" value="1003">Charlie Brown</option>
   </select>

]]>
  </screen>
 </example>
</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
-->