Dropdown default text (#213)

Author: ntacheva

_contentTemplates/common/get-model-from-dropdowns.md

@@ -0,0 +1,5 @@
+#get-model-from-dropdowns
+>tip If you are looking for more fields from the view-model that describes the dropdown items, not just the `Value`, see the [Get model from dropodwn]({%slug dropdowns-get-model%}) KB article and the [OnChange](events#onchange) event.
+>
+> You may also want to review/join the discussion and Vote for this request: <a href="https://www.telerik.com/forums/binding-dropdownlist-value-to-complex-model" target="_blank">Binding DropDownList Value to complex model</a>
+#end

components/autocomplete/data-bind.md

@@ -21,6 +21,8 @@ There are two key ways to bind data:
 
 There are also some [considerations](#considerations) to keep in mind.
 
+@[template](/_contentTemplates/common/get-model-from-dropdowns.md#get-model-from-dropdowns)
+
 ## Primitive Types
 
 You can data bind the AutoComplete to a simple collection of `string` data. When you have a concrete list of options for the user to choose from, their string representation is often suitable for display and you do not need special models.
@@ -131,6 +133,7 @@ The AutoComplete component is generic and its type depends on the type of the mo
 }
 ````
 
+
 ### Missing Data
 
 The AutoComplete is, essentially, a textbox. This means that its `Value` is always a string and it is up to you to bind and/or use it. The `Data` parameter, however, is required for the functionality of the component, and it must never be `null`. If there are no suggestions that you wish to provide to the user, consider using a regular TextBox, or creating an empty collection.

components/autocomplete/overview.md

@@ -29,6 +29,7 @@ User input: @TheValue
     Placeholder="Enter your role (can be free text)" ClearButton="true" />
 
 @code{
+    //Current value is null (no item is sellected) which allows the Placeholder to be displayed.
     string TheValue { get; set; }
 
     List<string> Suggestions { get; set; } = new List<string> {
@@ -69,7 +70,7 @@ The AutoComplete is a generic component and its type is determined by the type o
 
 * `MinLength` - how many characters the text has to be before the suggestions list appears. Cannot be `0`. Often works together with [filtering]({%slug autocomplete-filter%}).
 
-* `Placeholder` - the text the user sees as a hint when there is no text in the input.
+* `Placeholder` - the text the user sees as a hint when there is no text in the input. In order for it to be shown, the `Value` parameter should be set to the default value for string (`null`).
 
 * `PopupHeight` - the height of the expanded dropdown list element.
 
@@ -87,6 +88,7 @@ The AutoComplete is a generic component and its type is determined by the type o
 
 * Validation - see the [Input Validation]({%slug common-features/input-validation%}) article for more details.
 
+@[template](/_contentTemplates/common/get-model-from-dropdowns.md#get-model-from-dropdowns)
 
 ## See Also
 

components/combobox/data-bind.md

@@ -46,7 +46,13 @@ To bind the combobox to a primitive type (like `int`, `string`, `double`), you n
 @code {
     protected List<string> MyList = new List<string>() { "first", "second", "third" };
 
-    protected string MyItem { get; set; } = "second";
+    protected string MyItem { get; set; }
+
+    //Define a preselected value when the component initializes
+    protected override void OnInitialized()
+    {
+        MyItem = "second";
+    }
 }
 ````
 
@@ -77,12 +83,20 @@ To bind the ComboBox to a model:
         public string MyTextField { get; set; }
     }
 
-    IEnumerable<MyDdlModel> myDdlData = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x });
+    int selectedValue { get; set; }
+
+    //Define a preselected value when the component initializes
+    protected override void OnInitialized()
+    {
+        selectedValue = 3;
+    }
 
-    int selectedValue { get; set; } = 3; //usually the current value should come from the view model data
+    IEnumerable<MyDdlModel> myDdlData = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x });
 }
 ````
 
+@[template](/_contentTemplates/common/get-model-from-dropdowns.md#get-model-from-dropdowns)
+
 ## Considerations
 
 The ComboBox component attempts to infer the type of its model and value based on the provided `Data` and initial `Value`. This affects the way its [reference is obtained](#component-reference) and what happens [if you can't provide data or a value](#missing-value-or-data). Providing a [value that is not in the data source](#value-out-of-range) needs to be taken into account be the app, because the component will not change it.
@@ -115,7 +129,13 @@ The ComboBox is a generic component and its type comes from the model it is boun
 
     protected List<string> MyList = new List<string>() { "first", "second", "third" };
 
-    string initialValue { get; set; } = "third";
+    string initialValue { get; set; }
+
+    //Define a preselected value when the component initializes
+    protected override void OnInitialized()
+    {
+        initialValue = "third";
+    }
 }
 ````
 ````Model

components/combobox/overview.md

@@ -33,7 +33,13 @@ Selected value: @selectedValue
 @code {
     IEnumerable<MyDdlModel> myComboData = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x });
 
-    int selectedValue { get; set; } = 3; //usually the current value should come from the model data
+    int selectedValue { get; set; }
+
+    //Define a preselected value when the component initializes. Placeholder will not be shown as the selected value is defined.
+    protected override void OnInitialized()
+    {
+        selectedValue = 3;
+    }
 
     //in a real case, the model is usually in a separate file
     //the model type and value field type must be provided to the dropdpownlist
@@ -75,7 +81,7 @@ The ComboBox is a generic component and its type is determined by the type of th
 
 * `Id` - renders as the `id` attribute on the `<input />` element, so you can attach a `<label for="">` to the input.
 
-* `Placeholder` - the text the user sees as a hint when no item is selected (the `Value` is `null` or an empty string).
+* `Placeholder` - the text the user sees as a hint when no item is selected. In order for it to be shown, the `Value` parameter should be set to a default value depending on the type defined in the `ValueField` parameter. For example, `0` for an `int`, and `null` for an `int?` or `string`. You need to make sure that it does not match the value of an existing item in the data source.
 
 * `PopupHeight` - the height of the expanded dropdown list element.
 
@@ -129,10 +135,7 @@ Missing selection is most common when the initial value is `null` as data source
 | No match | No item is selected. `Value` is updated to the custom one. | No item is selected. `Value` is updated to `default(typeof(Value))`. The `OnChange` event does not fire for the value clearing. |
 
 
->tip If you are looking for more fields from the view-model that describes the dropdown items, not just the `Value`, see the [Get model from dropodwn]({%slug dropdowns-get-model%}) KB article and the [OnChange](events#onchange) event.
->
-> You may also want to review/join the discussion and Vote for this request: <a href="https://www.telerik.com/forums/binding-dropdownlist-value-to-complex-model" target="_blank">Binding DropDownList Value to complex model</a>
-
+@[template](/_contentTemplates/common/get-model-from-dropdowns.md#get-model-from-dropdowns)
 
 ## See Also
 

components/dropdownlist/data-bind.md

@@ -21,10 +21,10 @@ There are two key ways to bind data:
 
 and some considerations you may find useful, such as showing the `DefaultText` when the value is out of the data source range:
 
-* [Considerations](#considerations)
-	* [Value Out of Range](#value-out-of-range)
-	* [Component Reference](#component-reference)
-	* [Missing Value or Data](#missing-value-or-data)
+  * [Considerations](#considerations)
+    * [Value Out of Range](#value-out-of-range)
+    * [Component Reference](#component-reference)
+    * [Missing Value or Data](#missing-value-or-data)
 
 ## Primitive Types
 
@@ -44,9 +44,15 @@ Bind to a List of a primitive type (stirng, int,...)
 </TelerikDropDownList>
 
 @code {
-	protected List<string> MyList = new List<string>() { "first", "second", "third" };
+    protected List<string> MyList = new List<string>() { "first", "second", "third" };
 
-	protected string MyItem { get; set; } = "second";
+    protected string MyItem { get; set; }
+
+    //Define a preselected value when the component initializes
+    protected override void OnInitialized()
+    {
+        MyItem = "second";
+    }
 }
 ````
 
@@ -69,20 +75,28 @@ Bind to a collection of models
 </TelerikDropDownList>
 
 @code {
-	//in a real case, the model is usually in a separate file
-	//the model type and value field type must be provided to the dropdpownlist
-	public class MyDdlModel
-	{
-		public int MyValueField { get; set; }
-		public string MyTextField { get; set; }
-	}
+    //in a real case, the model is usually in a separate file
+    //the model type and value field type must be provided to the dropdpownlist
+    public class MyDdlModel
+    {
+        public int MyValueField { get; set; }
+        public string MyTextField { get; set; }
+    }
 
-	IEnumerable<MyDdlModel> myDdlData = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x });
+    int selectedValue { get; set; }
+
+    //Define a preselected value when the component initializes
+    protected override void OnInitialized()
+    {
+        selectedValue = 3;
+    }
 
-	int selectedValue { get; set; } = 3; //usually the current value should come from the view model data
+    IEnumerable<MyDdlModel> myDdlData = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x });
 }
 ````
 
+@[template](/_contentTemplates/common/get-model-from-dropdowns.md#get-model-from-dropdowns)
+
 ## Considerations
 
 The DropDownList component attempts to infer the type of its model and value based on the provided `Data` and initial `Value`. This affects the way its [reference is obtained](#component-reference) and what happens [if you can't provide data or a value](#missing-value-or-data). Providing a [value that is not in the data source](#value-out-of-range) needs to be taken into account be the app, because the component will not change it.
@@ -109,9 +123,15 @@ Reference type when binding to primitive values
     //the type of the generic component is determined by the type of the model you pass to it, and the type of its value field
     Telerik.Blazor.Components.TelerikDropDownList<string, string> myDdlRef;
 
-	protected List<string> MyList = new List<string>() { "first", "second", "third" };
+    protected List<string> MyList = new List<string>() { "first", "second", "third" };
+
+    string initialValue { get; set; }
 
-    string initialValue {get;set;} = "third";
+    //Define a preselected value when the component initializes
+    protected override void OnInitialized()
+    {
+        initialValue = "third";
+    }
 }
 ````
 ````Model

components/dropdownlist/overview.md

@@ -29,17 +29,23 @@ Selected value: @selectedValue
 </TelerikDropDownList>
 
 @code {
-	//in a real case, the model is usually in a separate file
-	//the model type and value field type must be provided to the dropdpownlist
-	public class MyDdlModel
-	{
-		public int MyValueField { get; set; }
-		public string MyTextField { get; set; }
-	}
+    //in a real case, the model is usually in a separate file
+    //the model type and value field type must be provided to the dropdpownlist
+    public class MyDdlModel
+    {
+        public int MyValueField { get; set; }
+        public string MyTextField { get; set; }
+    }
 
-	IEnumerable<MyDdlModel> myDdlData = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x });
+    int selectedValue { get; set; }
 
-	int selectedValue { get; set; } = 3; //usually the current value should come from the model data
+    //Define a preselected value when the component initializes
+    protected override void OnInitialized()
+    {
+        selectedValue = 3;
+    }
+
+    IEnumerable<MyDdlModel> myDdlData = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x });
 }
 ````
 
@@ -61,7 +67,7 @@ The DropDownList provides the following features:
 
 * `Data` - allows you to provide the data source. Required.
 
-* `DefaultText` - sets the hint that is shown if the `Value` has the `default` value for the type of the `ValueField`. For example, `0` for an `int`, and `null` for an `int?` or `string`. You need to make sure that it does not match the value of an existing item in the data source. You can find examples in the [Examples section](#examples) in this article and in the [Input Validation]({%slug common-features/input-validation%}#dropdownlist) article.
+* `DefaultText` -  simple hint to be displayed when no item is selected yet. In order for it to be shown, the `Value` parameter should be set to a default value depending on the type defined in the `ValueField` parameter. For example, `0` for an `int`, and `null` for an `int?` or `string`. You need to make sure that it does not match the value of an existing item in the data source. See the first example in the [Examples section](#examples) in this article and in the [Input Validation]({%slug common-features/input-validation%}#dropdownlist) article.
 
 * `Enabled` - whether the component is enabled.
 
@@ -97,6 +103,15 @@ The DropDownList provides the following features:
 * Validation - see the [Input Validation]({%slug common-features/input-validation%}) article for more details.
 
 
+## Selected Item and DefaultText
+
+By default, if no `Value` is provided and no `DefaultText` is defined, the DropDownList will appear empty.
+
+* To display `DefaultText` - `Value` should be `0` or `null` depending on the data type you are using in the `ValueField` and the `DefaultText` should be defined.
+
+* To display a selected item when the component renders - provide the `Value` of the desired element. Note that it must match an item of the component's data source. 
+
+
 ## Examples
 
 >caption Default text (hint) to show when no actual item is selected
@@ -116,41 +131,17 @@ The DropDownList provides the following features:
 @code {
     protected List<string> MyStringList = new List<string>() { "first", "second", "third" };
 
+    //Current value is null (no item is sellected) which allows the DefaultText to be displayed.
     protected string MyStringItem { get; set; }
 
     protected List<int> MyIntList = new List<int>() { 1, 2, 3 };
 
+    //Current value is 0 (no item is sellected) which allows the DefaultText to be displayed.
     protected int MyIntItem { get; set; }
 }
 ````
 
 
-
->caption Show default item only when there is no selection by toggling the DefaultText parameter value depending on your business logic
-
-````CSHTML
-Selected value: @selectedValue
-<br />
-
-<TelerikDropDownList Data="@myDdlData" TextField="MyTextField" ValueField="MyValueField" @bind-Value="selectedValue"
-                     DefaultText="@( selectedValue == 0 ? "Please Select" : null )">
-</TelerikDropDownList>
-
-@code {
-    int selectedValue { get; set; }
-    
-    IEnumerable<MyDdlModel> myDdlData = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x });
-    
-    public class MyDdlModel
-    {
-        public int MyValueField { get; set; }
-        public string MyTextField { get; set; }
-    }
-}
-````
-
-
-
 >caption Get selected item from external code
 
 ````CSHTML
@@ -193,10 +184,7 @@ Selected value: @selectedValue
 ````
 
 
->tip If you are looking for more fields from the view-model that describes the dropdown items, not just the `Value`, see the [Get model from dropodwn]({%slug dropdowns-get-model%}) KB article and the [OnChange](events#onchange) event.
->
-> You may also want to review/join the discussion and Vote for this request: <a href="https://www.telerik.com/forums/binding-dropdownlist-value-to-complex-model" target="_blank">Binding DropDownList Value to complex model</a>
-
+@[template](/_contentTemplates/common/get-model-from-dropdowns.md#get-model-from-dropdowns)
 
 
 ## See Also

components/multiselect/data-bind.md

@@ -124,6 +124,8 @@ To bind the MultiSelect to a model:
 }
 ````
 
+@[template](/_contentTemplates/common/get-model-from-dropdowns.md#get-model-from-dropdowns)
+
 ## Considerations
 
 The MultiSelect component attempts to infer the type of its model and value based on the provided `Data` and initial `Value`. This affects the way its [reference is obtained](#reference) and what happens [if you can't provide data or a value](#missing-value-or-data).

components/multiselect/overview.md

@@ -190,6 +190,8 @@ The MultiSelect is a generic component and its type is determined by the type of
 }
 ````
 
+@[template](/_contentTemplates/common/get-model-from-dropdowns.md#get-model-from-dropdowns)
+
 ## See Also
 
   * [Data Binding]({%slug multiselect-databind%})