Added support to prompt list item.

4 files changed, 69 insertions, 0 deletions

diff --git a/HISTORY b/HISTORY
index 0801645c..6f9472ce 100644
--- a/HISTORY
+++ b/HISTORY
@@ -23,6 +23,7 @@ ENH: Ticket#709 - Added TDbCache.ConnectionID (Qiang)
 ENH: Added THead requirement check (Qiang)
 ENH: Added TOutputCache.CacheTime (Qiang)
 ENH: Added "remember login" support to TAuthManager and the related modules/classes (Qiang)
+ENH: Added prompt text support to TDropDownList and TListBox (Qiang)
 CHG: Ticket#685 - Slashes and backslashes mixup in PradoBase (Qiang)
 CHG: Ticket#705 - TImage will not set border style by default (Qiang)
 CHG: GeSHi is replaced with Text_Highlighter (Christophe)
diff --git a/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page b/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page
index faf3b9b1..9db74476 100644
--- a/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page
+++ b/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page
@@ -18,6 +18,7 @@ This page summarizes the main new features that are introduced in each PRADO rel
 <li>Added support to allow configuring page properties and authorization rules using <a href="?page=Configurations.PageConfig">relative page paths</a> in application and page configurations. Added support to allow <a href="?page=Advanced.Auth">authorization</a> based on remote host address.</li>

 <li>Added a new page state persister <tt>TCachePageStatePersister</tt>. It allows page state to be stored using a cache module (e.g. TMemCache, TDbCache, etc.)

 <li>Added support to the <a href="?page=Advanced.Auth">auth framework</a> to allow remembering login.</li>

+<li>Added support to display a prompt item in TDropDownList and TListBox (something like 'Please select:' as the first list item.)</li>

 </ul>

 

 <h2 id="8006">Version 3.1.0</h2>

diff --git a/framework/Web/UI/WebControls/TDropDownList.php b/framework/Web/UI/WebControls/TDropDownList.php
index 3270ad16..883073c5 100644
--- a/framework/Web/UI/WebControls/TDropDownList.php
+++ b/framework/Web/UI/WebControls/TDropDownList.php
@@ -28,6 +28,10 @@ Prado::using('System.Web.UI.WebControls.TListControl');
  *  // or <com:TListItem Attributes.Group="Group Name" .../> in template

  * </code>

  *

+ * Since v3.1.1, TDropDownList starts to support prompt text. That is, a prompt item can be

+ * displayed as the first list item by specifying {@link setPromptText PromptText}. Choosing

+ * the prompt item will unselect the TDropDownList.

+ *

  * @author Qiang Xue <qiang.xue@gmail.com>

  * @version $Id$

  * @package System.Web.UI.WebControls

diff --git a/framework/Web/UI/WebControls/TListControl.php b/framework/Web/UI/WebControls/TListControl.php
index bb51934c..6e478550 100644
--- a/framework/Web/UI/WebControls/TListControl.php
+++ b/framework/Web/UI/WebControls/TListControl.php
@@ -704,6 +704,44 @@ abstract class TListControl extends TDataBoundControl implements IDataRenderer
 	}

 

 	/**

+	 * @return string the prompt text which is to be displayed as the first list item. Defaults to empty, meaning no prompt.

+	 * @since 3.1.1

+	 */

+	public function getPromptText()

+	{

+		return $this->getViewState('PromptText','');

+	}

+

+	/**

+	 * @param string the prompt text which is to be displayed as the first list item. If empty, {@link getPromptValue PromptValue} will be displayed.

+	 * @since 3.1.1

+	 */

+	public function setPromptText($value)

+	{

+		$this->setViewState('PromptText',$value,'');

+	}

+

+	/**

+	 * @return string the prompt selection value. Defaults to empty, meaning no prompt.

+	 * @see getPromptText

+	 * @since 3.1.1

+	 */

+	public function getPromptValue()

+	{

+		return $this->getViewState('PromptValue','');

+	}

+

+	/**

+	 * @param string the prompt selection value. If empty, {@link getPromptText PromptText} will be used as the value.

+	 * @see setPromptText

+	 * @since 3.1.1

+	 */

+	public function setPromptValue($value)

+	{

+		$this->setViewState('PromptValue',(string)$value,'');

+	}

+

+	/**

 	 * Raises OnSelectedIndexChanged event when selection is changed.

 	 * This method is invoked when the list control has its selection changed

 	 * by end-users.

@@ -727,6 +765,29 @@ abstract class TListControl extends TDataBoundControl implements IDataRenderer
 	}

 

 	/**

+	 * Renders the prompt text, if any.

+	 * @param THtmlWriter writer

+	 * @since 3.1.1

+	 */

+	protected function renderPrompt($writer)

+	{

+		$text=$this->getPromptText();

+		$value=$this->getPromptValue();

+		if($text==='')

+			$text=$value;

+		if($value==='')

+			$value=$text;

+		if($text!=='')

+		{

+			$writer->addAttribute('value',$value);

+			$writer->renderBeginTag('option');

+			$writer->write(THttpUtility::htmlEncode($text));

+			$writer->renderEndTag();

+			$writer->writeLine();

+		}

+	}

+

+	/**

 	 * Renders body content of the list control.

 	 * This method renders items contained in the list control as the body content.

 	 * @param THtmlWriter writer

@@ -736,6 +797,8 @@ abstract class TListControl extends TDataBoundControl implements IDataRenderer
 		if($this->_items)

 		{

 			$writer->writeLine();

+			if($this->_items->getCount())

+				$this->renderPrompt($writer);

 			$previousGroup=null;

 			foreach($this->_items as $item)

 			{