Skip to content

API Overview

Architecture

The Name Field module follows Drupal's plugin-based architecture and provides a comprehensive API for working with structured name data.

Core Concepts

Name Components

The module defines six name components that can be used to build a complete name:

Component Key Description Example
Title title Honorific prefix Dr., Mr., Mrs.
Given given First name Jane
Middle middle Middle name(s) Marie
Family family Last name Smith
Generational generational Generational suffix Jr., Sr., III
Credentials credentials Professional credentials PhD, MD, Esq.

Each component can be: - Enabled or disabled per field instance - Configured with custom labels - Set as required or optional - Given minimum and maximum length constraints

Name Formats

Name formats define how components are assembled for display. Formats use a token-based system with component placeholders:

  • t - Title
  • g - Given name
  • m - Middle name
  • f - Family name
  • c - Credentials
  • s - Generational suffix

Example format: t g m f s c produces "Dr. Jane Marie Smith Jr. PhD"

Formats support: - Conditional separators (only appear if both adjacent components have values) - Modifiers for preferred/alternative names - List formatting with customizable separators

Field API Integration

The module integrates with Drupal's Field API through:

  • NameItem (Drupal\name\Plugin\Field\FieldType\NameItem) - The field type plugin
  • NameWidget (Drupal\name\Plugin\Field\FieldWidget\NameWidget) - The default field widget
  • NameFormatter (Drupal\name\Plugin\Field\FieldFormatter\NameFormatter) - The field formatter plugin

Form Element

The module provides a custom form element type (name) that can be used in any Drupal form:

$form['person_name'] = [
  '#type' => 'name',
  '#title' => t('Full Name'),
  '#components' => [
    'title' => 'title',
    'given' => 'given',
    'family' => 'family',
  ],
];

Namespace Organization

All classes are organized under the Drupal\name namespace:

Drupal\name\
├── Controller/          # Controllers (autocomplete)
├── Element/            # Form element (Name)
├── Entity/             # Config entities (NameFormat, NameListFormat)
├── Feeds/              # Feeds integration
├── Form/               # Admin forms
├── Plugin/
│   ├── diff/          # Diff module integration
│   ├── Field/
│   │   ├── FieldFormatter/  # Field formatter plugin
│   │   ├── FieldType/       # Field type plugin
│   │   └── FieldWidget/     # Field widget plugin
│   ├── migrate/       # Migrate API integration
│   └── views/         # Views integration
├── Render/            # Render elements
├── Traits/            # Reusable traits
└── [Services]         # Service classes

Service Container

The module registers the following services in the service container:

Service ID Class Purpose
name.formatter NameFormatter Format name data for display
name.format_parser NameFormatParser Parse name format strings
name.generator NameGenerator Generate sample names
name.autocomplete NameAutocomplete Autocomplete functionality
name.options_provider NameOptionsProvider Manage component options

Configuration Entities

The module defines two configuration entity types:

NameFormat

Stores custom name format definitions. Each format includes: - Machine name (ID) - Label - Pattern (format string)

NameListFormat

Stores list formatting configurations for displaying multiple names: - Delimiter (comma, semicolon, etc.) - Conjunction (and, or, ampersand) - el_al_min/max settings for "et al." functionality

Database Schema

Name field data is stored in the field's data table with the following columns:

  • {field_name}_title - Title component
  • {field_name}_given - Given name
  • {field_name}_middle - Middle name
  • {field_name}_family - Family name
  • {field_name}_generational - Generational suffix
  • {field_name}_credentials - Credentials

Hooks

The module provides one hook for extending functionality:

  • hook_name_widget_layouts() - Add custom widget layout options

See the Hooks documentation for details.

Helper Functions

The module provides several helper functions in name.module:

  • name_widget_layouts() - Get available widget layouts
  • _name_translations() - Get component labels
  • _name_component_keys() - Get component machine names
  • _name_component_layout() - Get component layout info

See the Functions documentation for details.

Integration with Other Modules

The Name module integrates with:

  • Token - Provides tokens for name components and formats
  • Diff - Shows differences in name field values
  • Feeds - Import name data
  • Migrate - Migrate name data from Drupal 7
  • Views - Filter and display name data

Next Steps