Advanced Country Field

Provides an advanced country selection field with SVG flags, filtering, search, multi-language support, and full accessibility. Supports multiple widget types with customizable options.

Key Features

Multiple Widget Types

• Dropdown (select)
• Multi-select dropdown
• Radio buttons
• Checkboxes
• Automatic widget selection based on field cardinality

SVG Flag Support

• Display country flags with customizable positioning (before, after, or flag-only)
• Support for popular flag libraries including country-flag-icons (recommended)
• Customizable flag sizes with CSS units support (px, rem, %, vw, vh, etc.)
• Supports both 3x2 and 1x1 aspect ratio flags

Country Filtering & Management

• Administrators can restrict which countries appear in dropdowns globally and per field.
• Custom country entries support for non-standard regions
• Real-time search functionality for quick country lookup
• Alphabetical listing with client-side filtering

Multi-Language Support

• Use site language for country names
• Native country names option (e.g., "Deutschland" for Germany, "España" for Spain)
• Fallback to English if translation unavailable
• Comprehensive database of native country names

Accessibility

• 100% WCAG 2.1 compliant
• Full keyboard navigation support
• Screen reader compatibility with ARIA labels
• High contrast mode support
• Semantic HTML and proper form labels

Value Storage Options

• Store country code only (recommended)
• Store country name only
• Store both code and name

Requirements

• Drupal 10.x or 11.x
• PHP 8.1 or higher
• (Optional) SVG flag library for displaying country flags:

Installation

Basic Installation

# Install the module
composer require drupal/advanced_country_field

# Enable the module
drush en advanced_country_field -y

Installing Flag Library (Optional but Recommended)

This module supports the country-flag-icons npm package for displaying country flags. You have two options for installation:

Option 1: Quick Installation (if your project is already configured)

composer require npm-asset/country-flag-icons:^1.5

Option 2: First-time Setup for npm Packages via Composer

If the above command fails, you need to configure your project to support npm packages through Asset Packagist:

Step 1: Add Asset Packagist repository to your composer.json in the repositories section:

"repositories": [
    {
        "type": "composer",
        "url": "https://packages.drupal.org/8"
    },
    {
        "type": "composer",
        "url": "https://asset-packagist.org"
    }
]

Step 2: Add the installer extender package to require section:

"require": {
    "oomphinc/composer-installers-extender": "^2.0"
}

Step 3: Configure installer types and paths in the extra section:

"extra": {
    "installer-types": ["npm-asset", "bower-asset"],
    "installer-paths": {
        "web/libraries/{$name}": [
            "type:drupal-library",
            "type:npm-asset",
            "type:bower-asset"
        ]
    }
}

Step 4: Allow the plugin in the config section:

"config": {
    "allow-plugins": {
        "oomphinc/composer-installers-extender": true
    }
}

Step 5: Update composer and install the package:

composer update
composer require npm-asset/country-flag-icons:^1.5

Option 3: Manual Installation

1. Download country-flag-icons from npmjs.com
2. Extract it to web/libraries/country-flag-icons/

Flag Library Configuration

After installing the flag library, configure the path at /admin/config/regional/advanced-country-field:

• For 3x2 aspect ratio flags: /libraries/country-flag-icons/3x2/
• For 1x1 aspect ratio flags: /libraries/country-flag-icons/1x1/
• Or if installed via npm-asset: /libraries/country-flag-icons/3x2/ (composer-installers-extender places it here)

Note: The library will be automatically installed to web/libraries/country-flag-icons/ when using the composer method with proper configuration.

Flag Library Configuration:

After installing the flag library, configure the path at /admin/config/regional/advanced-country-field:

• For 3x2 aspect ratio flags: /libraries/country-flag-icons/3x2/
• For 1x1 aspect ratio flags: /libraries/country-flag-icons/1x1/
• Or if installed via npm-asset: /vendor/npm-asset/country-flag-icons/3x2/ (may require symlink)

Usage

1. Add an "Advanced Country" field to any entity (Content Types, User profiles, etc.)
2. Configure widget settings (type, flags, search, placeholder)
3. Configure formatter settings for display output
4. Set up country filtering at /admin/config/regional/advanced-country-field/countries

Integration

• Works seamlessly with Drupal Views
• Supports all entity types
• Compatible with custom modules via hooks and service API

Documentation

Comprehensive documentation including installation guides, API references, configuration examples, and developer guides available in the module directory and at README.md