Skip to content

Name Field - Developer Documentation

Overview

The Name Field module provides a multi-component name field type for Drupal. This documentation is designed for developers who want to programmatically use or extend the Name module.

The Name module allows you to store structured name data with the following components:

  • Title (e.g., Mr., Mrs., Dr.)
  • Given name (first name)
  • Middle name(s)
  • Family name (last name)
  • Generational suffix (e.g., Jr., Sr., III)
  • Credentials (e.g., PhD, MD)

Quick Start

Using the Name Formatter Service

// Get the name formatter service
$formatter = \Drupal::service('name.formatter');

// Format a name array
$name_data = [
  'title' => 'Dr.',
  'given' => 'Jane',
  'middle' => 'Marie',
  'family' => 'Smith',
  'credentials' => 'PhD',
];

// Format using a specific format
$formatted = $formatter->format($name_data, 'full');
// Returns: "Dr. Jane Marie Smith PhD"

Adding a Name Field Programmatically

use Drupal\field\Entity\FieldStorageConfig;
use Drupal\field\Entity\FieldConfig;

// Create field storage
FieldStorageConfig::create([
  'field_name' => 'field_person_name',
  'entity_type' => 'node',
  'type' => 'name',
])->save();

// Create field instance
FieldConfig::create([
  'field_name' => 'field_person_name',
  'entity_type' => 'node',
  'bundle' => 'person',
  'label' => 'Full Name',
])->save();

Architecture

The Name module is built around several key concepts:

Components

Name components are the individual parts of a name (title, given, middle, family, generational, credentials). Each component can be enabled/disabled and configured independently.

Formats

Name formats define how name components are assembled for display. The module includes several predefined formats (full, formal, family, given, short_full) and supports custom formats.

Services

The module provides several services for working with names:

  • name.formatter - Format name data for display
  • name.format_parser - Parse name format strings
  • name.generator - Generate sample names for testing
  • name.autocomplete - Provide autocomplete functionality
  • name.options_provider - Manage component options (titles, generational suffixes)

Documentation Sections

API Overview

Learn about the module's architecture, core concepts, and namespace organization.

Services

Hooks

Learn about available hooks like hook_name_widget_layouts() for extending the module.

Helper Functions

Documentation for helper functions like _name_translations(), _name_component_keys(), and more.

Classes and Interfaces

Reference documentation for classes like NameElement, NameItem, NameWidget, and their interfaces.

Code Examples

Practical examples showing how to use the module programmatically.

Extending the Module

Guides for creating custom widget layouts, name formats, and formatters.

Requirements

  • Drupal 10.3+ or Drupal 11+
  • Field module (core)

Resources

Site Builder Documentation

For site builder documentation (installation, configuration, usage through the UI), see the README.md file.