Problem/Motivation
Enum vales do not have (translatable) labels.
We need human-readable equivalents, and those equivalents must be translatable (using Drupal's interface translation mechanism).
Precedent:
- Core: #3471494: Add an icon management API
- The https://www.drupal.org/project/ui_patterns contrib module:
\Drupal\ui_patterns\EnumTrait::getEnumOptions()
Steps to reproduce
The core/modules/system/tests/modules/sdc_test/components/my-banner/my-banner.component.yml
SDC contains:
ctaTarget:
title: CTA Target
type: string
enum:
- ''
- _blank
👆 Clearly the supported ''
enum value is impossible to generate a sensible human-readable label for.
Proposed resolution
Change that example to:
ctaTarget:
title: CTA Target
type: string
enum:
- ''
- _blank
meta:enum:
'': 'Same window'
_blank: 'Open in new window'
… and which if accessed through some TBD API should be passed through Drupal's UI translation mechanism, like so:
\Drupal\Core\StringTranslation\StringTranslationTrait::t(
string: 'Same window,
options: ['context' => 'sdc_test:my_banner, ctaTarget prop'],
)
Which would then result in Hetzelfde venster
in Dutch (nl
) or Même fenêtre
in French (fr
).
Remaining tasks
- INFRA: Update
\Drupal\Core\Theme\Component\ComponentMetadata::parseSchemaInfo()
to trigger a deprecation error when anenum
is encountered without a correspondingmeta:enum
- INFRA: Update
\Drupal\Core\Theme\Component\ComponentMetadata::parseSchemaInfo()
to trigger a\LogicException
when ameta:enum
is encountered whose keys do not match (i.e. are a subset or superset) the values listed in the correspondingenum
. - Compliance: Update
sdc_test:my-banner
like the above. Update all other core SDCs to provide ameta:enum
. (The first 2 tasks will guarantee this.) - INFRA: add a
getEnumOptions(string $prop): array<string, TranslatableMarkup>
method to\Drupal\Core\Theme\Component\ComponentMetadata
inspired byui_patterns
'\Drupal\ui_patterns\EnumTrait::getEnumOptions()
. (The thing thatui_patterns
does not yet do is pass it through Drupal'st()
.) - TEST: kernel test asserting that 2 identical
type: string, enum: […]
props can have different translations for the same enum values. For example: a''
enum value results inSame window
for thetarget
prop and inNone
for arel
prop.
→ verifies it works end-to-end, and supports translation contexts - TEST: expand the previous point's test to test at least one language other than English.
- TEST: kernel test asserting that a
meta:enum
not matching theenum
triggers a\LogicException
User interface changes
None.
Introduced terminology
None.
API changes
- Every
enum
SDC prop now supports ameta: enum
, will be required in Drupal 12. - Every
enum
SDC prop that has ameta: enum
requires them to be in sync, otherwise an exception is thrown.
Data model changes
None.
Release notes snippet
Single-Directory Components with props that have a restricted set of allowed values (using enum
) now can specify human-readable labels for each of those allowed values. Those labels are also translatable using Drupal's user interface translation subsystem, and they have an SDC prop-specific context (<provider>:<sdc_name>, <prop name> prop
).