From 26399298164f1fb6eaa4764b543b876766dacf0a Mon Sep 17 00:00:00 2001
From: Derek Jones <derek.jones@ellislab.com>
Date: Wed, 8 Apr 2009 16:14:17 +0000
Subject: added form_multiselect() to form helper to make it easier to create
 multiselect fields, and to make it a bit more semantically correct to boot

---
 system/helpers/form_helper.php      | 25 +++++++++++++++++++++++++
 user_guide/changelog.html           |  1 +
 user_guide/helpers/form_helper.html |  8 ++++++++
 3 files changed, 34 insertions(+)

diff --git a/system/helpers/form_helper.php b/system/helpers/form_helper.php
index 0173340c5..4716e4975 100644
--- a/system/helpers/form_helper.php
+++ b/system/helpers/form_helper.php
@@ -246,6 +246,31 @@ if ( ! function_exists('form_textarea'))
 
 // ------------------------------------------------------------------------
 
+/**
+ * Multi-select menu
+ *
+ * @access	public
+ * @param	string
+ * @param	array
+ * @param	mixed
+ * @param	string
+ * @return	type
+ */
+if (! function_exists('form_multiselect'))
+{
+	function form_multiselect($name = '', $options = array(), $selected = array(), $extra = '')
+	{
+		if ( ! strpos($extra, 'multiple'))
+		{
+			$extra .= ' multiple="multiple"';
+		}
+	
+		return form_dropdown($name, $options, $selected, $extra);
+	}
+}
+
+// --------------------------------------------------------------------
+
 /**
  * Drop-down Menu
  *
diff --git a/user_guide/changelog.html b/user_guide/changelog.html
index e4d57f6b1..b5d3fe7d9 100644
--- a/user_guide/changelog.html
+++ b/user_guide/changelog.html
@@ -79,6 +79,7 @@ SVN Revision: </p>
 	</li>
 	<li>Helpers
 		<ul>
+			<li>Added <kbd>form_multiselect()</kbd> to the <a href="helpers/form_helper.html">Form helper</a>.</li>
 			<li>Modified <kbd>form_hidden()</kbd> in the <a href="helpers/form_helper.html">Form helper</a> to accept multi-dimensional arrays.</li>
 		</ul>
 	</li>
diff --git a/user_guide/helpers/form_helper.html b/user_guide/helpers/form_helper.html
index 1958721c0..6f17a6bba 100644
--- a/user_guide/helpers/form_helper.html
+++ b/user_guide/helpers/form_helper.html
@@ -241,6 +241,14 @@ echo form_dropdown('shirts', $options, 'large', $js);</code>
 
 <p>If the array passed as $options is a multidimensional array, form_dropdown() will produce an &lt;optgroup&gt; with the array key as the label.</p>
 
+<h2>form_multiselect()</h2>
+
+<p>Lets you create a standard multiselect field.  The first parameter will contain the name of the field,
+the second parameter will contain an associative array of options, and the third parameter will contain the
+value or values you wish to be selected.  The parameter usage is identical to using <kbd>form_dropdown()</kbd> above,
+except of course that the name of the field will need to use POST array syntax, e.g. <samp>foo[]</samp>.</p>
+
+
 <h2>form_fieldset()</h2>
 
 <p>Lets you generate fieldset/legend fields.</p>
-- 
cgit v1.2.3-24-g4f1b