View source for Documentation:Databound Placeholder text

You can show context-specific hint text in an empty input by adding a companion ''_Placeholder'' column to the [[Documentation:ViewModel|ViewModel]]; this is intended for developers building MDriven Turnkey or WPF user interfaces.
== What placeholder text does ==
A '''placeholder''' is text displayed inside an input control while that control has no value. It disappears when the user enters or selects a value.

For example, an empty search field can show ''Enter a search string...''. The text helps the user understand what to enter, but it is not the field value.

Use a placeholder for a short entry hint. Use [[Documentation:Input Controls|helper text]] when guidance must remain visible below the control.

<message>Write the content here to display this box</message>
Placeholder text is the text shown as a hint to the User while the control is empty. As soon as the User enters a value, the placeholder text is not shown.
[[File:Input control with placeholder.png|none|thumb]]
== Add a databound placeholder ==
Create a second ViewModel column whose name is the input column name followed by <code>_Placeholder</code>. The value produced by that companion column is used as the placeholder text.

For an input column named <code>SearchText</code>, create:

{| class="wikitable"
! ViewModel column
! Purpose
! Example value
|-
| <code>SearchText</code>
| The input value edited by the user.
| <code>bike</code>
|-
| <code>SearchText_Placeholder</code>
| The hint shown while <code>SearchText</code> is empty.
| <code>Enter a search string...</code>
|}

# Open the ViewModel in the ViewModel Editor.
# Locate the column that provides the input value, for example <code>SearchText</code>.
# Add a column named <code>SearchText_Placeholder</code> at the same ViewModel level.
# Set its expression or value to the text you want to show. For example, set it to <code>'Enter a search string...'</code>.
# Keep the input column and its <code>_Placeholder</code> column next to each other in the ViewModel Editor. This makes the name relationship clear during maintenance.
# Run the application. When <code>SearchText</code> is empty, the UI uses the value of <code>SearchText_Placeholder</code> as its hint.

The companion column can be databound, so its result can change with the ViewModel state. For example, a <code>SearchText_Placeholder</code> expression can provide different instructions for different search modes.

This naming pattern is available in Turnkey from early 2022. [[Documentation:Input Controls|Input Controls]] documents the corresponding Turnkey input behavior and related conventions such as <code>_HelperText</code>, <code>Texttype</code>, and input icons.
== Do not use the legacy tagged value ==
The earlier approach was to set the <code>Placeholder</code> tagged value directly on the input ViewModel column. That approach is deprecated.

For new ViewModels, use <code>&lt;InputColumn&gt;_Placeholder</code>. When updating an existing ViewModel, move the old fixed text into the companion column so that Turnkey and custom clients can use the same naming convention.
== WPF implementation ==
Standard WPF controls do not provide placeholder text out of the box. If your WPF application uses the MaterialDesignThemes package, you can bind Material Design's <code>HintAssist.HintProperty</code> to the companion column during control placement.

The following example handles <code>TextBox</code>, <code>ComboBox</code>, and <code>DatePicker</code>. It first reads the legacy <code>Placeholder</code> tagged value for existing ViewModels, then binds the <code>_Placeholder</code> column when it exists. The binding is one-way: changes to the companion column update the displayed hint, but editing the input does not change the companion column.

<syntaxhighlight lang="csharp">
_wecpof = new WECPOFTabBased();

_wecpof.OnAddWindow += (s, e) =>
{
    e.Win.ViewModelUC.OnViewModelColumnPlacementDone += (s2, e2) =>
    {
        if (e2.Ctrl is System.Windows.Controls.TextBox ||
            e2.Ctrl is System.Windows.Controls.ComboBox ||
            e2.Ctrl is System.Windows.Controls.DatePicker)
        {
            // Legacy support for ViewModels that still use the deprecated tagged value.
            var val = e2.Vcol.TaggedValueLocalAndModelInfo("Placeholder");
            if (!string.IsNullOrEmpty(val))
                MaterialDesignThemes.Wpf.HintAssist.SetHint(e2.Ctrl, val);

            var dataForPlaceholder =
                e2.Vcol.ViewModelClass.ColumnFromName(
                    e2.Vcol.RuntimeName + "_Placeholder");

            if (dataForPlaceholder != null &&
                e2.Ctrl is FrameworkElement)
            {
                var b = new System.Windows.Data.Binding(
                    dataForPlaceholder.RuntimeName)
                {
                    Source = e2.Vcol.ViewModelClass.BindingSource,
                    Mode = System.Windows.Data.BindingMode.OneWay
                };

                (e2.Ctrl as FrameworkElement).SetBinding(
                    MaterialDesignThemes.Wpf.HintAssist.HintProperty, b);
            }
        }
    };
};
</syntaxhighlight>

The databound <code>_Placeholder</code> binding takes effect when the companion column exists. Retain the tagged-value portion only while you need compatibility with older ViewModels; remove it after migrating all placeholders to companion columns.

For information about the Material Design styling used in WPF applications, see [[Documentation:Wpf materialdesign|WPF materialdesign]].

If you use the excellent MaterialDesign ([http://materialdesigninxaml.net/ MaterialDesignThemes by James Willock)] package, this code will get the effect:

Here is example code showing how to implement this:
<pre>
      _wecpof = new WECPOFTabBased();
      ...
      _wecpof.OnAddWindow += (s, e) =>
      {
        e.Win.ViewModelUC.OnViewModelColumnPlacementDone += (s2, e2) =>
        {
          if (e2.Ctrl is System.Windows.Controls.TextBox || e2.Ctrl is System.Windows.Controls.ComboBox || e2.Ctrl is System.Windows.Controls.DatePicker)
          {
            var val = e2.Vcol.TaggedValueLocalAndModelInfo("Placeholder");
            if (!string.IsNullOrEmpty(val))
              MaterialDesignThemes.Wpf.HintAssist.SetHint(e2.Ctrl, val);
            var dataForPlaceholder = e2.Vcol.ViewModelClass.ColumnFromName(e2.Vcol.RuntimeName + "_Placeholder");
            if (dataForPlaceholder != null)
            {
              if (e2.Ctrl is FrameworkElement)
              {
                var b = new System.Windows.Data.Binding(dataForPlaceholder.RuntimeName) { Source = e2.Vcol.ViewModelClass.BindingSource, Mode = System.Windows.Data.BindingMode.OneWay /'', Converter = new Eco.Xaml.PassthroughDebugConverter() ''/ };
                (e2.Ctrl as FrameworkElement).SetBinding(MaterialDesignThemes.Wpf.HintAssist.HintProperty, b);
              }
            }
          }
        };
</pre>
== Placeholder versus a null choice ==
A placeholder is an instruction displayed in an empty input. It does not add a selectable value to a picklist.

If a <code>ComboBox</code> or dropdown must display or allow a null selection such as ''Choose a color'', configure the picklist's Null/NullRep options instead. See [[Documentation:How Null is represented in your picklist|How Null is represented in your picklist]].
== Related ViewModel naming conventions ==
MDriven uses companion ViewModel columns to provide presentation data for a primary column. For example, labels can be provided through the corresponding label naming convention described in [[Documentation:Databind labels in ViewModels|Databind labels in ViewModels]], and hyperlinks can use a <code>_LinkText</code> column as described in [[Documentation:Column.DataIsLink|Column.DataIsLink]].
== See also ==
* [[Documentation:Input Controls]]
* [[Documentation:Databind labels in ViewModels]]
* [[Documentation:How Null is represented in your picklist]]
* [[Documentation:Wpf materialdesign]]

[[Category:Intermediate-Friendly]]
[[Category:Priority 50]]
[[Category:ViewModel fundamentals]]
[[Category:ViewModels and UI Modeling]]