---
title: Bind and render a drop-down list
summary: Support enum-sourced binding and a read-only rendering mode for the drop-down.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-08-17
library: SAIF.Presentation.Web.Controls.V2
reference_type: package
operation_id: OP-V2-005
trigger: Host page calls `DataBind`, or the ASP.NET page lifecycle invokes `Render`.
---

# Bind and render a drop-down list

Support enum-sourced binding and a read-only rendering mode for the drop-down. Host page calls `DataBind`, or the ASP.NET page lifecycle invokes `Render`.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-V2-005 |
| **Trigger** | Host page calls `DataBind`, or the ASP.NET page lifecycle invokes `Render`. |
| **Inputs** | `EnumDatasource`, `MapUnderscore`, `ReadOnly`, `ValueText`, control width/style. |
| **Outputs** | Populated list items on bind; interactive drop-down or read-only textbox markup on render. |
| **Primary components** | `SAIFDropDownList` |
| **Entry point** | `SAIF.Presentation.Web.Controls.V2/SAIFDropDownList.vb` |

## Steps

1. On `DataBind`, if `EnumDatasource` is set, read the enum member names via `System.Enum.GetNames`. ([BR-V2-027](../business-rules.md#br-v2-027-drop-down-can-bind-directly-to-an-enum))
2. If `MapUnderscore` is true, replace `_` with a space in every name before assigning them as the base `DataSource`. ([BR-V2-028](../business-rules.md#br-v2-028-underscore-to-space-mapping-for-enum-names))
3. Call the base `DataBind`. ([BR-V2-029](../business-rules.md#br-v2-029-enum-binding-supplements-normal-binding))
4. On `Render`, when `ReadOnly` is true, create a read-only `TextBox` with CSS class `disabledbackcolor`, width reduced by 5 pixels when the control width is 5 or greater, and text taken from the selected item — or from `ValueText` when the selected value is blank. ([BR-V2-030](../business-rules.md#br-v2-030-read-only-drop-down-renders-as-a-styled-textbox), [BR-V2-031](../business-rules.md#br-v2-031-read-only-textbox-is-narrower-than-the-drop-down), [BR-V2-032](../business-rules.md#br-v2-032-valuetext-fallback-when-selection-is-blank), [BR-V2-033](../business-rules.md#br-v2-033-inline-styles-copied-to-the-substitute-textbox))
5. When not read-only and `Visible`, call the base `Render`. ([BR-V2-034](../business-rules.md#br-v2-034-invisible-drop-down-renders-nothing), [BR-V2-035](../business-rules.md#br-v2-035-base-render-failure-triggers-one-retry-with-selection-cleared))
   - On failure: clear the selection and re-render once.
6. `SelectedItemAsEnum` converts between selected item text and enum value, reversing the underscore mapping. ([BR-V2-036](../business-rules.md#br-v2-036-selecteditemasenum-maps-text-and-enum-bidirectionally))

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([DataBind]) --> E{EnumDatasource set?}
	E -->|Yes| Names[GetNames + optional underscore mapping]
	Names --> Base[MyBase.DataBind]
	E -->|No| Base
	Base --> RenderStart([Render]) 
	RenderStart --> RO{ReadOnly?}
	RO -->|Yes| Text[Substitute read-only TextBox]
	RO -->|No| Vis{Visible?}
	Vis -->|Yes| BR[MyBase.Render]
	BR -->|Throws| Retry[Clear selection, retry once]
	Vis -->|No| NoOut([No output])
```

## Failure and edge-case behavior

- On failure: clear the selection and re-render once.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

## Sources
- `SAIF.Presentation.Web.Controls.V2/SAIFDropDownList.vb`