Name Options Provider Service¶

Overview¶

The Name Options Provider service (name.options_provider) manages option lists for name field components like titles and generational suffixes. It handles loading options from field settings and taxonomy vocabularies.

Service ID: name.options_provider Class: Drupal\name\NameOptionsProvider

Basic Usage¶

$options_provider = \Drupal::service('name.options_provider');
$field_definition = $entity->getFieldDefinition('field_name');

// Get title options
$titles = $options_provider->getOptions($field_definition, 'title');
// Returns: ['Mr.' => 'Mr.', 'Mrs.' => 'Mrs.', 'Dr.' => 'Dr.', ...]

// Get generational suffix options
$suffixes = $options_provider->getOptions($field_definition, 'generational');
// Returns: ['Jr.' => 'Jr.', 'Sr.' => 'Sr.', 'III' => 'III', ...]

Method Reference¶

getOptions()¶

Gets available options for a name component.

public function getOptions(
  FieldDefinitionInterface $field,
  $component
);

Parameters:

$field (FieldDefinitionInterface) - The field definition containing settings
$component (string) - The component name:
'title' - Title/honorific options
'generational' - Generational suffix options

Returns: array - Associative array of options (value => label)

Processing:

Loads options from field settings ({component}_options)
Expands taxonomy vocabulary references
Filters by maximum length constraints
Removes duplicates
Optionally sorts options (if sort_options is enabled)
Processes default option markers

Option Sources¶

Direct Options¶

Options can be defined directly in field settings:

$field_settings = [
  'title_options' => [
    'Mr.',
    'Mrs.',
    'Ms.',
    'Dr.',
    'Prof.',
  ],
  'generational_options' => [
    'Jr.',
    'Sr.',
    'II',
    'III',
    'IV',
  ],
];

Taxonomy Vocabulary Options¶

Options can come from taxonomy terms using special syntax:

$field_settings = [
  'title_options' => [
    '[vocabulary:name_titles]',  // Load from vocabulary
    'Mr.',  // Mix with direct options
    'Mrs.',
  ],
];

Vocabulary Format: [vocabulary:vocabulary_machine_name]

When a vocabulary reference is found:

The vocabulary is loaded
All terms are retrieved from the vocabulary tree
Term names are added to the options list
Terms longer than max_length are filtered out

Default Option Marker¶

Options prefixed with -- are treated as default options:

$options = [
  'Mr.',
  '--Mrs.',  // Default option
  'Ms.',
  'Dr.',
];

// After processing:
// Returns: ['Mr.' => 'Mr.', 'Ms.' => 'Ms.', 'Dr.' => 'Dr.']
// With 'Mrs.' as the default value (stored separately)

Field Settings¶

Configuration Structure¶

$field_settings = [
  // Option lists
  'title_options' => [...],
  'generational_options' => [...],

  // Maximum length constraints
  'max_length' => [
    'title' => 31,
    'given' => 63,
    'middle' => 127,
    'family' => 63,
    'generational' => 15,
    'credentials' => 255,
  ],

  // Sort options alphabetically
  'sort_options' => [
    'title' => TRUE,
    'generational' => FALSE,
  ],
];

Option Processing¶

Length Filtering¶

Options that exceed the component's maximum length are automatically removed:

// Field setting: max_length['title'] = 5
// Input options: ['Mr.', 'Mrs.', 'Professor']
// Output: ['Mr.' => 'Mr.', 'Mrs.' => 'Mrs.']
// 'Professor' removed (8 chars > 5)

Duplicate Removal¶

Duplicate options from multiple sources are filtered:

// Input from multiple sources:
// Direct: ['Mr.', 'Dr.']
// Taxonomy: ['Dr.', 'Prof.']
// Output: ['Mr.' => 'Mr.', 'Dr.' => 'Dr.', 'Prof.' => 'Prof.']

Sorting¶

When sort_options is enabled for a component:

$options_provider->getOptions($field, 'title');
// Without sorting: ['Mr.', 'Dr.', 'Mrs.', 'Ms.']
// With sorting: ['Dr.', 'Mr.', 'Mrs.', 'Ms.']  (natural case-insensitive sort)

Use Cases¶

Populating Select Lists¶

$options_provider = \Drupal::service('name.options_provider');
$field_definition = $this->fieldDefinition;

$form['title'] = [
  '#type' => 'select',
  '#title' => t('Title'),
  '#options' => $options_provider->getOptions($field_definition, 'title'),
  '#empty_option' => t('- None -'),
];

Validation¶

$options_provider = \Drupal::service('name.options_provider');
$valid_titles = $options_provider->getOptions($field_definition, 'title');

if (!isset($valid_titles[$submitted_title])) {
  $form_state->setError($element, t('Invalid title selected.'));
}

Autocomplete Integration¶

The Options Provider is used by the Autocomplete Service:

// In NameAutocomplete::getMatches()
$options = $this->optionsProvider->getOptions($field, 'title');
foreach ($options as $key => $option) {
  if (strpos(mb_strtolower($option), $test_string) === 0) {
    $matches[$key] = $key;
  }
}

Taxonomy Integration¶

Setting Up Taxonomy Source¶

Create a vocabulary (e.g., "Professional Titles")
Add terms to the vocabulary
In field settings, add [vocabulary:professional_titles]

Example:

// Vocabulary: professional_titles
// Terms: Associate Professor, Assistant Professor, Professor Emeritus

$field_settings = [
  'title_options' => [
    'Dr.',
    'Mr.',
    '[vocabulary:professional_titles]',  // Expands to all terms
  ],
];

// Results in:
// 'Dr.', 'Mr.', 'Associate Professor', 'Assistant Professor', 'Professor Emeritus'

Dependency Injection¶

namespace Drupal\my_module\Form;

use Drupal\Core\Form\FormBase;
use Drupal\name\NameOptionsProvider;
use Symfony\Component\DependencyInjection\ContainerInterface;

class MyCustomForm extends FormBase {

  protected $nameOptionsProvider;

  public function __construct(NameOptionsProvider $name_options_provider) {
    $this->nameOptionsProvider = $name_options_provider;
  }

  public static function create(ContainerInterface $container) {
    return new static(
      $container->get('name.options_provider')
    );
  }

  public function buildForm(array $form, FormStateInterface $form_state) {
    $field = FieldConfig::loadByName('node', 'person', 'field_name');

    $form['title'] = [
      '#type' => 'select',
      '#title' => $this->t('Title'),
      '#options' => $this->nameOptionsProvider->getOptions($field, 'title'),
    ];

    return $form;
  }
}