From 6dce87a2ac347e387e1c15ccc516bc68e41b4fb4 Mon Sep 17 00:00:00 2001
From: scottjehl <scott@scottjehl.com>
Date: Fri, 3 Dec 2010 11:32:48 -0500
Subject: [PATCH] hide placeholder options in selectmenu overlays. Fixes #607

---
 docs/forms/forms-selects.html                 | 50 +++++++++++++++++++
 js/jquery.mobile.forms.select.js              | 13 ++++-
 themes/default/jquery.mobile.forms.select.css |  2 +-
 3 files changed, 62 insertions(+), 3 deletions(-)

diff --git a/docs/forms/forms-selects.html b/docs/forms/forms-selects.html
index 9e289e6b..aa776cb9 100755
--- a/docs/forms/forms-selects.html
+++ b/docs/forms/forms-selects.html
@@ -122,7 +122,57 @@
 			<option value="edit">Edit</option>
 			<option value="delete">Delete</option>
 		</select>
+	</div>	
+	
+	
+	<h2>Placeholder options</h2>
+	<p>It's common for developers to include a "null" option in their select element to force a user to choose an option. jQuery Mobile detects these null options and hides them in the overlay menu, showing only valid choices to the user. Examples of null options are either:</p>
+	<ul>
+		<li>An option with no value attribute (or an empty value attribute)</li>
+		<li>An option with no text node</li>
+		<li>An option with a <code>data-placeholder="true"</code> attribute. (This allows you to use an option that has a value and a textnode as a placeholder option).</li>
+	</ul>
+	
+	
+	
+	
+	<p>Here's a demo of various placeholder options:</p>
+		 
+		 
+	<div data-role="fieldcontain">
+		<label for="select-choice-4" class="select">Choose shipping method:</label>
+		<select name="select-choice-4" id="select-choice-4">
+			<option></option>
+			<option value="standard">Standard: 7 day</option>
+			<option value="rush">Rush: 3 days</option>
+			<option value="express">Express: next day</option>
+			<option value="overnight">Overnight</option>
+		</select>
+	</div>	 
+		 
+		 
+	<div data-role="fieldcontain">
+		<label for="select-choice-5" class="select">Choose shipping method:</label>
+		<select name="select-choice-5" id="select-choice-5">
+			<option>Choose one...</option>
+			<option value="standard">Standard: 7 day</option>
+			<option value="rush">Rush: 3 days</option>
+			<option value="express">Express: next day</option>
+			<option value="overnight">Overnight</option>
+		</select>
 	</div>		 
+		 
+		 
+	<div data-role="fieldcontain">
+		<label for="select-choice-6" class="select">Choose shipping method:</label>
+		<select name="select-choice-6" id="select-choice-6">
+			<option value="choose-one" data-placeholder="true">Choose one...</option>
+			<option value="standard">Standard: 7 day</option>
+			<option value="rush">Rush: 3 days</option>
+			<option value="express">Express: next day</option>
+			<option value="overnight">Overnight</option>
+		</select>
+	</div>	 
 
 	</form>
 	
diff --git a/js/jquery.mobile.forms.select.js b/js/jquery.mobile.forms.select.js
index 4f993196..30873002 100644
--- a/js/jquery.mobile.forms.select.js
+++ b/js/jquery.mobile.forms.select.js
@@ -16,7 +16,8 @@ $.widget( "mobile.selectmenu", $.mobile.widget, {
 		shadow: true,
 		iconshadow: true,
 		menuPageTheme: 'b',
-		overlayTheme: 'a'
+		overlayTheme: 'a',
+		hidePlaceholderMenuItems: true
 	},
 	_create: function(){
 	
@@ -155,7 +156,9 @@ $.widget( "mobile.selectmenu", $.mobile.widget, {
 	},
 	
 	_buildList: function(){
-		var self = this, optgroups = [];
+		var self = this, 
+			optgroups = [],
+			o = this.options;
 		
 		self.list.empty().filter('.ui-listview').listview('destroy');
 		
@@ -192,6 +195,12 @@ $.widget( "mobile.selectmenu", $.mobile.widget, {
 					.addClass("ui-disabled")
 					.attr("aria-disabled", true);
 			}
+			
+			if( o.hidePlaceholderMenuItems ){
+				if( !this.getAttribute('value') || $(this).text().length == 0 || $(this).data('placeholder')){
+					item.addClass('ui-selectmenu-placeholder');
+				}
+			}
 
 			item
 				.append( anchor )
diff --git a/themes/default/jquery.mobile.forms.select.css b/themes/default/jquery.mobile.forms.select.css
index dfda9958..d7f05d6f 100644
--- a/themes/default/jquery.mobile.forms.select.css
+++ b/themes/default/jquery.mobile.forms.select.css
@@ -21,7 +21,7 @@ label.ui-select { font-size: 16px; line-height: 1.4;  font-weight: normal; margi
 .ui-selectmenu-screen { position: absolute; top: 0; left: 0; width: 100%; height: 100%;  z-index: 99; }
 .ui-screen-hidden, .ui-selectmenu-list .ui-li .ui-icon { display: none; }
 .ui-selectmenu-list .ui-btn-active .ui-icon { display: block; }
-
+.ui-selectmenu .ui-selectmenu-placeholder { display: none; }
 
 .min-width-480px label.ui-select { display: inline-block;  width: 20%;  margin: 0 2% 0 0; }
 .min-width-480px .ui-select { width: 60%; display: inline-block; } 
\ No newline at end of file