Documentation:Databound Placeholder text

Databound Placeholder text

This page was created by Hans.karlsen on 2022-10-14. Last edited by Wikiadmin on 2026-07-29.

You can show context-specific hint text in an empty input by adding a companion _Placeholder column to the 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 helper text when guidance must remain visible below the control.

Add a databound placeholder

Create a second ViewModel column whose name is the input column name followed by _Placeholder. The value produced by that companion column is used as the placeholder text.

For an input column named SearchText, create:

ViewModel column	Purpose	Example value
`SearchText`	The input value edited by the user.	`bike`
`SearchText_Placeholder`	The hint shown while `SearchText` is empty.	`Enter a search string...`

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

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

This naming pattern is available in Turnkey from early 2022. Input Controls documents the corresponding Turnkey input behavior and related conventions such as _HelperText, Texttype, and input icons.

Do not use the legacy tagged value

The earlier approach was to set the Placeholder tagged value directly on the input ViewModel column. That approach is deprecated.

For new ViewModels, use <InputColumn>_Placeholder. 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 HintAssist.HintProperty to the companion column during control placement.

The following example handles TextBox, ComboBox, and DatePicker. It first reads the legacy Placeholder tagged value for existing ViewModels, then binds the _Placeholder 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.

_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);
            }
        }
    };
};

The databound _Placeholder 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 WPF materialdesign.

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 ComboBox or dropdown must display or allow a null selection such as Choose a color, configure the picklist's Null/NullRep options instead. See 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 Databind labels in ViewModels, and hyperlinks can use a _LinkText column as described in Column.DataIsLink.

Contents