ui5 UI5 Smart Controls Best Practices
Apply these guidelines whenever generating, reviewing, or troubleshooting UI5 smart control code in freestyle applications using OData V2 services.
UI5 version baseline: SAPUI5 1.136+ LTS. All features mentioned are available from this version unless noted.
When to load each reference
| Trigger | Load |
|---|---|
Working on or planning a sap.ui.comp.smartfield.SmartField |
references/smart-field.md |
Working on or planning a sap.ui.comp.smartform.SmartForm |
references/smart-form.md |
Working on or planning a sap.ui.comp.smartfilterbar.SmartFilterBar |
references/smart-filter-bar.md |
Working on or planning a sap.ui.comp.smartchart.SmartChart |
references/smart-chart.md |
Working on or planning a sap.ui.comp.navpopover.SmartLink |
references/smart-link.md |
Working on or planning a sap.ui.comp.smartmultiinput.SmartMultiInput |
references/smart-multi-input.md |
Working on or planning a sap.ui.comp.filterbar.FilterBar |
references/filter-bar.md |
Working on or planning a sap.ui.comp.valuehelpdialog.ValueHelpDialog |
references/value-help-dialog.md |
Load before producing any output. Do not work from memory.
Core Rules
Mandatory
- Always specify
entitySeton Smart controls or ensure the control inherits a binding context that resolves the entity type. - Use
ControlConfigurationin XML for SmartFilterBar field overrides (control type, filter type, index). Onlyvisible,label, andvisibleInAdvancedAreacan be changed at runtime. - Use the correct hierarchy:
SmartForm > Group > GroupElement > SmartField. Never place SmartFields directly in a SmartForm. - Wait for the
initialiseevent before programmatically accessing inner controls (e.g.,getInnerControl(),getChart()). - Use
sap.ui.model.odata.type.*types in bindings alongside OData V2 models. Never usesap.ui.model.type.*with OData V2. - Set
ariaLabelledByon SmartFilterBar and SmartChart referencing a visible title for accessibility. - Use
check()on SmartForm for client-side mandatory field validation before submitting data. - Use
get_api_referenceMCP tool to verify control APIs. Userun_ui5_linterto validate code.
Prohibitions
- Do not use Smart controls with OData V4 services. Use MDC controls (
sap.ui.mdc) instead. - Do not set custom formatters on SmartField
valueproperty. SmartField manages its own rendering based on metadata. Use annotations to influence behavior. - Do not use composite binding syntax (
parts: [...]) on SmartField. It manages its own composite bindings for unit/currency fields. - Do not call
getChart()synchronously during initialization. Use theinitialiseevent orgetChartAsync(). - Do not directly modify inner controls of SmartChart or SmartTable (e.g., the inner
sap.chart.Chart). Use the smart control's public API. - Do not hardcode field labels. Use
sap:labelor@Common.Labelannotations in OData metadata. - Do not use inline styles or scripts in HTML (CSP compliance).
- Do not use global access (
sap.ui.comp.smartfield.SmartField). Usesap.ui.defineor ES6 imports.
Selection Matrix
| Control | Use when | Do not use when |
|---|---|---|
SmartField |
OData V2, single property display/edit, auto-rendering by Edm type and annotations | OData V4, JSON models, custom rendering required, composite/multi-property fields |
SmartForm |
OData V2, entity editing with multiple SmartFields, auto-labels from annotations | OData V4, complex custom layouts, non-OData data |
SmartFilterBar |
OData V2, annotation-driven filter UI, integration with SmartTable/SmartChart | OData V4 (use MDC FilterBar), JSON-only, purely custom filter logic |
SmartChart |
OData V2, annotation-driven chart visualization, drill-down, variant management | OData V4 (use MDC Chart), non-analytical data, custom chart JS |
SmartLink |
OData V2, semantic object navigation, cross-app navigation via FLP | OData V4 (use MDC Link), simple static links, no FLP available |
SmartMultiInput |
OData V2, multi-value entry with tokens, value help with ranges | OData V4, simple single-value input, JSON-only |
FilterBar |
Manual filter UI without OData annotations, inside ValueHelpDialog, custom filters | OData V2 with annotations (use SmartFilterBar), OData V4 (use MDC FilterBar) |
ValueHelpDialog |
Complex value selection with table + conditions tabs, token-based multi-select | Simple dropdowns, single-value selection, OData V4 (use MDC ValueHelp) |
Common Errors
| Symptom | Cause | Fix |
|---|---|---|
| SmartField renders as plain text in edit mode | Missing binding context or wrong entitySet |
Verify value="{PropertyName}" and entity context resolution. |
| SmartField shows Input instead of DatePicker | Missing sap:display-format="Date" on property |
Add annotation or use controlType in ControlConfiguration. |
| SmartForm labels missing | sap:label annotation not set in OData metadata |
Add sap:label to property or set label on GroupElement. |
| SmartFilterBar type-ahead not working | Missing ValueList annotation with correct target path |
Verify target: {Namespace}.{EntityName}/{FieldName}. |
| SmartFilterBar default values ignored | Setting ControlConfiguration dynamically after initialise |
Set values statically in XML or use setFilterData() API. |
| SmartChart height is 0 / not visible | Container does not provide explicit height | Set height on parent container (e.g., height="50vh"). |
| SmartChart missing dimensions/measures | Wrong or missing UI.Chart annotation |
Verify MeasureAttributes and DimensionAttributes in annotation. |
| SmartLink popover shows "No content available" | No navigation targets for semantic object in FLP | Verify FLP configuration and user authorizations. |
| SmartLink rendered as text (not clickable) | No SemanticObject annotation on property |
Add @Common.SemanticObject annotation to OData property. |
| SmartMultiInput tokens not persisting | Missing ValueList or incorrect binding | Verify ValueList annotation and navigation property binding. |
Performance & Accessibility
Anti-patterns to avoid
- Requesting all value lists eagerly (use lazy loading; value lists load on-demand by default).
- Using
liveMode="true"on SmartFilterBar with expensive backend queries (causes rapid re-fetching). - Deep nesting of SmartForm groups (keep hierarchy flat: Form > Group > GroupElement).
- Bypassing SmartChart API to modify inner chart directly (breaks personalization and variant management).
- Not setting
ignoredChartTypeswhen certain chart types are irrelevant (unnecessary UI options).
Accessibility checklist
- Set
ariaLabelledByon SmartFilterBar referencing a visible title. - Set
ariaLabelledByon SmartChart referencing a visible title. - SmartForm automatically propagates labels to SmartFields via annotations.
- Verify keyboard navigation works for SmartFilterBar "Adapt Filters" dialog.
- Test SmartLink popover with screen reader (navigation targets must be announced).