Name Autocomplete Service¶

Overview¶

The Name Autocomplete service (name.autocomplete) provides autocomplete functionality for name field components. It retrieves matching suggestions based on user input and field configuration.

Service ID: name.autocomplete Class: Drupal\name\NameAutocomplete

Basic Usage¶

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

// Get autocomplete matches for a title
$matches = $autocomplete->getMatches($field_definition, 'title', 'Dr');
// Returns: ['Dr.' => 'Dr.', 'Dr' => 'Dr']

// Get autocomplete matches for a given name
$matches = $autocomplete->getMatches($field_definition, 'given', 'Joh');
// Returns matches from configured sources

// Get autocomplete matches for full name
$matches = $autocomplete->getMatches($field_definition, 'name', 'John S');
// Returns matches combining given, middle, and family names

Method Reference¶

getMatches()¶

Gets autocomplete matches for a name field component.

public function getMatches(
  FieldDefinitionInterface $field,
  $target,
  $string
);

Parameters:

$field (FieldDefinitionInterface) - The field definition with autocomplete settings
$target (string) - The component(s) to search:
'title' - Title field
'given' - Given name field
'middle' - Middle name field
'family' - Family name field
'credentials' - Credentials field
'generational' - Generational suffix field
'name' - Combined given, middle, and family
'name-all' - All components
'given-family' - Custom combination (separated by hyphens)
$string (string) - The search string

Returns: array - Array of matching values (key => label pairs)

Behavior:

Returns empty array if search string is empty
Limits results to 10 matches
Supports multi-word input with configurable separators
Searches configured autocomplete sources

Autocomplete Targets¶

Single Component¶

// Search titles
$matches = $autocomplete->getMatches($field, 'title', 'Dr');
// ['Dr.' => 'Dr.']

// Search generational suffixes
$matches = $autocomplete->getMatches($field, 'generational', 'J');
// ['Jr.' => 'Jr.', 'Jr' => 'Jr']

Combined Components¶

// Search given, middle, and family together
$matches = $autocomplete->getMatches($field, 'name', 'John Smith');

// Search all components
$matches = $autocomplete->getMatches($field, 'name-all', 'Dr John');

// Custom combination: given and family only
$matches = $autocomplete->getMatches($field, 'given-family', 'Jane Doe');

Autocomplete Sources¶

Autocomplete sources are configured per field and per component:

Available Sources¶

Title Options (title)
Predefined list of titles (Mr., Mrs., Dr., etc.)
Configured in field settings
Generational Options (generational)
Predefined suffixes (Jr., Sr., III, etc.)
Configured in field settings
Taxonomy Vocabularies
Can pull options from taxonomy terms
Format: [vocabulary:vocab_name]
Field Data (data)
Existing values from the field
Requires entity query access

Field Configuration¶

Autocomplete behavior is configured in field settings:

$field_settings = [
  'autocomplete_source' => [
    'title' => ['title'],  // Use title options
    'given' => ['data'],   // Use existing field data
    'family' => ['data'],  // Use existing field data
    'generational' => ['generational'],  // Use generational options
  ],
  'autocomplete_separator' => [
    'title' => ' ',
    'given' => ' ',
    'middle' => ' ',
    'family' => ' ',
    'credentials' => ' ',
    'generational' => ' ',
  ],
];

Controller Integration¶

The module provides an autocomplete controller at: /name/autocomplete/{field_name}/{entity_type}/{bundle}/{target}

Example route:

/name/autocomplete/field_full_name/node/person/given

This controller uses the autocomplete service:

// In NameAutocompleteController
$matches = $this->nameAutocomplete->getMatches(
  $field_definition,
  $target,
  $input
);

return new JsonResponse($matches);

The name widget automatically attaches autocomplete to enabled components:

// In NameWidget::formElement()
if ($autocomplete_enabled) {
  $element['given']['#autocomplete_route_name'] = 'name.autocomplete';
  $element['given']['#autocomplete_route_parameters'] = [
    'field_name' => $field_name,
    'entity_type' => $entity_type,
    'bundle' => $bundle,
    'target' => 'given',
  ];
}

Dependency Injection¶

namespace Drupal\my_module\Service;

use Drupal\name\NameAutocomplete;
use Drupal\Core\Field\FieldDefinitionInterface;

class MyCustomAutocomplete {

  protected $nameAutocomplete;

  public function __construct(NameAutocomplete $name_autocomplete) {
    $this->nameAutocomplete = $name_autocomplete;
  }

  public function getCustomMatches(
    FieldDefinitionInterface $field,
    string $component,
    string $search
  ) {
    $matches = $this->nameAutocomplete->getMatches(
      $field,
      $component,
      $search
    );

    // Filter or modify matches
    return array_slice($matches, 0, 5);
  }
}

Limiting Results¶

The service limits results to 10 matches by default. To get different limits, extend the service or filter the results:

$all_matches = $autocomplete->getMatches($field, 'title', 'M');
$limited = array_slice($all_matches, 0, 5);  // Limit to 5

Multi-word Support¶

The service handles multi-word input using configured separators:

// Input: "John Robert Smith"
// With space separator
// Matches against: "Smith" (last word)
// Returns: "John Robert [match]"