From 864785e0c868cbcb0095d22c27cab715cebe3eb1 Mon Sep 17 00:00:00 2001
From: Nancy Nicoles <jn2@phpexercises.com>
Date: Sat, 23 Apr 2011 15:57:52 -0500
Subject: [PATCH] Issue #1132602 by jn2: Fixed #empty_value and #empty_option properties form documentation.

---
 developer/topics/forms_api_reference.html |   69 ++++++++++++++++++++++++++++-
 1 files changed, 67 insertions(+), 2 deletions(-)

diff --git a/developer/topics/forms_api_reference.html b/developer/topics/forms_api_reference.html
index 278590f..49c0539 100644
--- a/developer/topics/forms_api_reference.html
+++ b/developer/topics/forms_api_reference.html
@@ -417,7 +417,45 @@ API QuickStart guide</a>.</p>
 <!-- textfield --> <td>-</td>
 <!-- vertical_tabs --> <td>-</td>
 <!-- weight --> </tr>
-    <tr>
+     <tr>
+      <th scope="row"><a href="#empty_option">#empty_option</a></th>
+<!-- checkbox --> <td>-</td>
+<!-- checkboxes --> <td>-</td>
+<!-- date --> <td>-</td>
+<!-- fieldset --> <td>-</td>
+<!-- file --> <td>-</td>
+<!-- machine_name --> <td>-</td>
+<!-- managed_file --><td>-</td>
+<!-- password --> <td>-</td>
+<!-- password_confirm --> <td>-</td>
+<!-- radio --> <td>-</td>
+<!-- radios --> <td>-</td>
+<!-- select --> <td class="x"><strong>X</strong></td>
+<!-- tableselect --> <td>-</td>
+<!-- textarea --> <td>-</td>
+<!-- textfield --> <td>-</td>
+<!-- vertical_tabs --> <td>-</td>
+<!-- weight --> <td>-</td></tr>
+     <tr>
+      <th scope="row"><a href="#empty_value">#empty_value</a></th>
+<!-- checkbox --> <td>-</td>
+<!-- checkboxes --> <td>-</td>
+<!-- date --> <td>-</td>
+<!-- fieldset --> <td>-</td>
+<!-- file --> <td>-</td>
+<!-- machine_name --> <td>-</td>
+<!-- managed_file --><td>-</td>
+<!-- password --> <td>-</td>
+<!-- password_confirm --> <td>-</td>
+<!-- radio --> <td>-</td>
+<!-- radios --> <td>-</td>
+<!-- select --> <td class="x"><strong>X</strong></td>
+<!-- tableselect --> <td>-</td>
+<!-- textarea --> <td>-</td>
+<!-- textfield --> <td>-</td>
+<!-- vertical_tabs --> <td>-</td>
+<!-- weight --> <td>-</td></tr>
+<tr>
       <th scope="row"><a href="#field_prefix">#field_prefix</a></th>
       <td>-</td>
 <!-- checkbox --> <td>-</td>
@@ -2078,7 +2116,10 @@ selection box.</p>
 
 <p><strong>Properties</strong>: <a href="#access">#access</a>, <a href="#after_build">#after_build</a>, <a href="#ajax">#ajax</a>, <a href="#attributes">#attributes</a>, <a href="#default_value"><strong>#default_value</strong></a>,
 <a href="#description">#description</a>, <a href="#disabled">#disabled</a>,
-<a href="#element_validate">#element_validate</a>, <a href="#multiple"><strong>#multiple</strong></a>,
+<a href="#element_validate">#element_validate</a>,
+<a href="#empty_option">#empty_option</a>,
+<a href="#empty_value">#empty_value</a>,
+<a href="#multiple"><strong>#multiple</strong></a>,
 <a href="#options"><strong>#options</strong></a>, <a href="#parents">#parents</a>,
 <a href="#post_render">#post_render</a>, <a href="#prefix">#prefix</a>,
 <a href="#pre_render">#pre_render</a>, <a href="#process">#process</a>,
@@ -3044,6 +3085,30 @@ property is empty.</p>
 <p><strong>Values</strong>: Text, enclosed in the t() translation
 function.</p>
 
+<h3><a name="empty_option" id="empty_option">#empty_option</a></h3>
+
+<p><strong>Used by</strong>: <a href="#select">select</a></p>
+
+<p><strong>Description</strong>: The label to show for the default option in a
+select element. By default, the label is automatically set to "- Select -"
+for a required field and "- None -" for an optional field.</p>
+
+<p><strong>Values</strong>: Text, enclosed in the t() translation
+function.</p>
+
+<h3><a name="empty_value" id="empty_value">#empty_value</a></h3>
+
+<p><strong>Used by</strong>: <a href="#select">select</a></p>
+
+<p><strong>Description</strong>: The value for the default option in a select
+element, which is used to determine whether the user submitted a value or not.</p>
+
+<p><strong>Values</strong>: Empty string. Note: If <a href="#required">#required</a>
+is not TRUE and this value or #empty_option above are not set, then no extra
+option is added to the select control, leaving the control in a slightly
+illogical state, because there's no way for the user to select nothing, since
+all user agents automatically preselect the first available option. </p>
+
 <h3><a name="error" id="error">#error</a></h3>
 
 <p>INTERNAL. Indicates whether or not a form
-- 
1.7.1