1:   2:   3:   4:   5:   6:   7:   8:   9:  10:  11:  12:  13:  14:  15:  16:  17:  18:  19:  20:  21:  22:  23:  24:  25:  26:  27:  28:  29:  30:  31:  32:  33:  34:  35:  36:  37:  38:  39:  40:  41:  42:  43:  44:  45:  46:  47:  48:  49:  50:  51:  52:  53:  54:  55:  56:  57:  58:  59:  60:  61:  62:  63:  64:  65:  66:  67:  68:  69:  70:  71:  72:  73:  74:  75:  76:  77:  78:  79:  80:  81:  82:  83:  84:  85:  86:  87:  88:  89:  90:  91:  92:  93:  94:  95:  96:  97:  98:  99: 100: 101: 102: 103: 104: 105: 106: 107: 108: 109: 110: 111: 112: 113: 114: 115: 116: 117: 118: 119: 120: 121: 122: 123: 124: 125: 126: 127: 128: 129: 130: 131: 132: 133: 134: 135: 136: 137: 138: 139: 140: 141: 142: 143: 144: 145: 146: 147: 148: 149: 150: 151: 152: 153: 154: 155: 156: 157: 158: 159: 160: 161: 162: 163: 164: 165: 166: 167: 168: 169: 170: 171: 172: 173: 174: 175: 176: 177: 178: 179: 180: 181: 182: 183: 184: 185: 186: 187: 188: 189: 190: 191: 192: 193: 194: 195: 196: 197: 198: 199: 200: 201: 202: 203: 204: 205: 206: 207: 208: 209: 210: 211: 212: 213: 214: 215: 216: 217: 218: 219: 220: 221: 222: 223: 224: 225: 226: 227: 228: 229: 230: 231: 232: 233: 234: 235: 236: 237: 238: 239: 240: 241: 242: 243: 244: 245: 246: 247: 248: 249: 250: 251: 252: 253: 254: 255: 256: 257: 258: 259: 260: 261: 262: 263: 264: 265: 266: 

<?php

/**
 * MvcCore
 *
 * This source file is subject to the BSD 3 License
 * For the full copyright and license information, please view
 * the LICENSE.md file that are distributed with this source code.
 *
 * @copyright   Copyright (c) 2016 Tom Flidr (https://github.com/mvccore)
 * @license     https://mvccore.github.io/docs/mvccore/5.0.0/LICENCE.md
 */

namespace MvcCore\Ext\Forms\Fields;

/**
 * Responsibility: init, pre-dispatch and render `<select>` HTML element 
 *                 as roll-out menu for single option select or as options 
 *                 list for multiple selection with options as all existing 
 *                 world states or only filtered world states.
 *                 `CountrySelect` field has it's own validator to check if 
 *                 submitted value is presented in configured options by default.
 *                 
 */
class CountrySelect extends \MvcCore\Ext\Forms\Fields\Select {

    /**
     * Possible value: `country-select`, not used in HTML code for this field.
     * @var string
     */
    protected $type = 'country-select';
    
    /**
     * Translate English state names. Default value is `FALSE`.
     * @var bool
     */
    protected $translate = FALSE;
    
    /**
     * All existing country codes and English state names.
     * Keys are country codes in upper case, values are English state names.
     * this array is automatically used to render all select options. If there 
     * is configured any filtering to filter displayed countries, only selected
     * states are rendered. Use method `$field->FilterOptions();` or constructor
     * `$cfg` array with record `filter` as array with upper case country codes 
     * array to render only.
     * @var array
     */
    protected static $allOptions = [
        'AF' => 'Afghanistan',          'AX' => 'Åland Islands',       'AL' => 'Albania',
        'DZ' => 'Algeria',              'AS' => 'American Samoa',       'AD' => 'Andorra',
        'AO' => 'Angola',               'AI' => 'Anguilla',             'AQ' => 'Antarctica',
        'AG' => 'Antigua and Barbuda',  'AR' => 'Argentina',            'AM' => 'Armenia',
        'AW' => 'Aruba',                'AU' => 'Australia',            'AT' => 'Austria',
        'AZ' => 'Azerbaijan',           'BS' => 'Bahamas',              'BH' => 'Bahrain',
        'BD' => 'Bangladesh',           'BB' => 'Barbados',             'BY' => 'Belarus',
        'BE' => 'Belgium',              'BZ' => 'Belize',               'BJ' => 'Benin',
        'BM' => 'Bermuda',              'BT' => 'Bhutan',               'BO' => 'Bolivia, Plurinational State of',
        'BQ' => 'Bonaire, Sint Eustatius and Saba','BA' => 'Bosnia and Herzegovina','BW' => 'Botswana',
        'BV' => 'Bouvet Island',        'BR' => 'Brazil',               'IO' => 'British Indian Ocean Territory',
        'BN' => 'Brunei Darussalam',    'BG' => 'Bulgaria',             'BF' => 'Burkina Faso',
        'BI' => 'Burundi',              'KH' => 'Cambodia',             'CM' => 'Cameroon',
        'CA' => 'Canada',               'CV' => 'Cape Verde',           'KY' => 'Cayman Islands',
        'CF' => 'Central African Republic', 'TD' => 'Chad',             'CL' => 'Chile',
        'CN' => 'China',                'CX' => 'Christmas Island',     'CC' => 'Cocos (Keeling) Islands',
        'CO' => 'Colombia',             'KM' => 'Comoros',              'CG' => 'Congo',
        'CD' => 'Congo, the Democratic Republic of the','CK' => 'Cook Islands','CR' => 'Costa Rica',
        'CI' => 'Côte d\'Ivoire',      'HR' => 'Croatia',              'CU' => 'Cuba',
        'CW' => 'Curaçao',             'CY' => 'Cyprus',               'CZ' => 'Czech Republic',
        'DK' => 'Denmark',              'DJ' => 'Djibouti',             'DM' => 'Dominica',
        'DO' => 'Dominican Republic',   'EC' => 'Ecuador',              'EG' => 'Egypt',
        'SV' => 'El Salvador',          'GQ' => 'Equatorial Guinea',    'ER' => 'Eritrea',
        'EE' => 'Estonia',              'ET' => 'Ethiopia',             'FK' => 'Falkland Islands (Malvinas)',
        'FO' => 'Faroe Islands',        'FJ' => 'Fiji',                 'FI' => 'Finland',
        'FR' => 'France',               'GF' => 'French Guiana',        'PF' => 'French Polynesia',
        'TF' => 'French Southern Territories',  'GA' => 'Gabon',        'GM' => 'Gambia',
        'GE' => 'Georgia',              'DE' => 'Germany',              'GH' => 'Ghana',
        'GI' => 'Gibraltar',            'GR' => 'Greece',               'GL' => 'Greenland',
        'GD' => 'Grenada',              'GP' => 'Guadeloupe',           'GU' => 'Guam',
        'GT' => 'Guatemala',            'GG' => 'Guernsey',             'GN' => 'Guinea',
        'GW' => 'Guinea-Bissau',        'GY' => 'Guyana',               'HT' => 'Haiti',
        'HM' => 'Heard Island and McDonald Islands','VA' => 'Holy See (Vatican City State)','HN' => 'Honduras',
        'HK' => 'Hong Kong',            'HU' => 'Hungary',              'IS' => 'Iceland',
        'IN' => 'India',                'ID' => 'Indonesia',            'IR' => 'Iran, Islamic Republic of',
        'IQ' => 'Iraq',                 'IE' => 'Ireland',              'IM' => 'Isle of Man',
        'IL' => 'Israel',               'IT' => 'Italy',                'JM' => 'Jamaica',
        'JP' => 'Japan',                'JE' => 'Jersey',               'JO' => 'Jordan',
        'KZ' => 'Kazakhstan',           'KE' => 'Kenya',                'KI' => 'Kiribati',
        'KP' => 'Korea, Democratic People\'s Republic of','KR' => 'Korea, Republic of','KW' => 'Kuwait',
        'KG' => 'Kyrgyzstan',           'LA' => 'Lao People\'s Democratic Republic','LV' => 'Latvia',
        'LB' => 'Lebanon',              'LS' => 'Lesotho',              'LR' => 'Liberia',
        'LY' => 'Libya',                'LI' => 'Liechtenstein',        'LT' => 'Lithuania',
        'LU' => 'Luxembourg',           'MO' => 'Macao',                'MK' => 'Macedonia, the former Yugoslav Republic of',
        'MG' => 'Madagascar',           'MW' => 'Malawi',               'MY' => 'Malaysia',
        'MV' => 'Maldives',             'ML' => 'Mali',                 'MT' => 'Malta',
        'MH' => 'Marshall Islands',     'MQ' => 'Martinique',           'MR' => 'Mauritania',
        'MU' => 'Mauritius',            'YT' => 'Mayotte',              'MX' => 'Mexico',
        'FM' => 'Micronesia, Federated States of','MD' => 'Moldova, Republic of','MC' => 'Monaco',
        'MN' => 'Mongolia',             'ME' => 'Montenegro',           'MS' => 'Montserrat',
        'MA' => 'Morocco',              'MZ' => 'Mozambique',           'MM' => 'Myanmar',
        'NA' => 'Namibia',              'NR' => 'Nauru',                'NP' => 'Nepal',
        'NL' => 'Netherlands',          'NC' => 'New Caledonia',        'NZ' => 'New Zealand',
        'NI' => 'Nicaragua',            'NE' => 'Niger',                'NG' => 'Nigeria',
        'NU' => 'Niue',                 'NF' => 'Norfolk Island',       'MP' => 'Northern Mariana Islands',
        'NO' => 'Norway',               'OM' => 'Oman',                 'PK' => 'Pakistan',
        'PW' => 'Palau',                'PS' => 'Palestinian Territory, Occupied','PA' => 'Panama',
        'PG' => 'Papua New Guinea',     'PY' => 'Paraguay',             'PE' => 'Peru',
        'PH' => 'Philippines',          'PN' => 'Pitcairn',             'PL' => 'Poland',
        'PT' => 'Portugal',             'PR' => 'Puerto Rico',          'QA' => 'Qatar',
        'RE' => 'Réunion',             'RO' => 'Romania',              'RU' => 'Russian Federation',
        'RW' => 'Rwanda',               'BL' => 'Saint Barthélemy',        'SH' => 'Saint Helena, Ascension and Tristan da Cunha',
        'KN' => 'Saint Kitts and Nevis','LC' => 'Saint Lucia',          'MF' => 'Saint Martin (French part)',
        'PM' => 'Saint Pierre and Miquelon','VC' => 'Saint Vincent and the Grenadines','WS' => 'Samoa',
        'SM' => 'San Marino',           'ST' => 'Sao Tome and Principe','SA' => 'Saudi Arabia',
        'SN' => 'Senegal',              'RS' => 'Serbia',               'SC' => 'Seychelles',
        'SL' => 'Sierra Leone',         'SG' => 'Singapore',            'SX' => 'Sint Maarten (Dutch part)',
        'SK' => 'Slovakia',             'SI' => 'Slovenia',             'SB' => 'Solomon Islands',
        'SO' => 'Somalia',              'ZA' => 'South Africa',         'GS' => 'South Georgia and the South Sandwich Islands',
        'SS' => 'South Sudan',          'ES' => 'Spain',                'LK' => 'Sri Lanka',
        'SD' => 'Sudan',                'SR' => 'Suriname',             'SJ' => 'Svalbard and Jan Mayen',
        'SZ' => 'Swaziland',            'SE' => 'Sweden',               'CH' => 'Switzerland',
        'SY' => 'Syrian Arab Republic', 'TW' => 'Taiwan, Province of China','TJ' => 'Tajikistan',
        'TZ' => 'Tanzania, United Republic of','TH' => 'Thailand',      'TL' => 'Timor-Leste',
        'TG' => 'Togo',                 'TK' => 'Tokelau',              'TO' => 'Tonga',
        'TT' => 'Trinidad and Tobago',  'TN' => 'Tunisia',              'TR' => 'Turkey',
        'TM' => 'Turkmenistan',         'TC' => 'Turks and Caicos Islands','TV' => 'Tuvalu',
        'UG' => 'Uganda',               'UA' => 'Ukraine',              'AE' => 'United Arab Emirates',
        'GB' => 'United Kingdom',       'US' => 'United States',        'UM' => 'United States Minor Outlying Islands',
        'UY' => 'Uruguay',              'UZ' => 'Uzbekistan',           'VU' => 'Vanuatu',
        'VE' => 'Venezuela, Bolivarian Republic of','VN' => 'Viet Nam', 'VG' => 'Virgin Islands, British',
        'VI' => 'Virgin Islands, U.S.', 'WF' => 'Wallis and Futuna',    'EH' => 'Western Sahara',
        'YE' => 'Yemen',                'ZM' => 'Zambia',               'ZW' => 'Zimbabwe',
    ];

    /**
     * Return country code in upper case.
     * @return string
     */
    public function GetValue () {
        return $this->value;
    }

    /**
     * Set country code value. Given country code will be automatically converted to upper case.
     * @param string $countryCode 
     * @return \MvcCore\Ext\Forms\Fields\CountrySelect
     */
    public function SetValue ($countryCode) {
        /** @var $this \MvcCore\Ext\Forms\Field */
        $this->value = strtoupper($countryCode);
        return $this;
    }

    /**
     * Get all existing country codes as array with keys as upper cased 
     * country codes and values as not translated English state names.
     * @return array
     */
    public static function & GetAllOptions () {
        return static::$allOptions;
    }

    /**
     * Set all existing country codes as array with keys as upper cased 
     * country codes and values as not translated English state names.
     * Given value will be automatically used as select options, if there 
     * will not be configured any filtering to filter displayed countries.
     * @param array $allOptions 
     */
    public static function SetAllOptions ($allOptions = []) {
        static::$allOptions = $allOptions;
    }

    /**
     * Filter displayed countries to not show every time all existing 
     * countries in the world. Given country codes will be automatically
     * converted to upper case.
     * @param \string[] $countryCodes Array of country codes strings to rendered only, not to render all existing states.
     * @return \MvcCore\Ext\Forms\Fields\CountrySelect
     */
    public function FilterOptions ($countryCodes = []) {
        /** @var $this \MvcCore\Ext\Forms\Field */
        $options = [];
        foreach ($countryCodes as $countryCode) {
            $countryCode = strtoupper($countryCode);
            if (isset(static::$allOptions[$countryCode])) {
                $options[$countryCode] = static::$allOptions[$countryCode];
            } else {
                $options[$countryCode] = $countryCode;
            }
        }
        $this->options = & $options;
        return $this;
    }
    
    /**
     * Create new form country `<select>` control instance.
     * If there is record under `filter` key in `$cfg` array argument,
     * it's used for method $field->FilterOptions();` method.
     * @param array $cfg Config array with protected properties and it's 
     *                   values which you want to configure, presented 
     *                   in camel case properties names syntax.
     * @throws \InvalidArgumentException
     * @return void
     */
    public function __construct(array $cfg = []) {
        parent::__construct($cfg);
        if (isset($cfg['filter'])) 
            $this->FilterOptions($cfg['filter']);
    }

    /**
     * This INTERNAL method is called from `\MvcCore\Ext\Form` after field
     * is added into form instance by `$form->AddField();` method. Do not 
     * use this method even if you don't develop any form field.
     * - Check if field has any name, which is required.
     * - Set up form and field id attribute by form id and field name.
     * - Set up required.
     * - Set up translate boolean property.
     * - Check if there are any select options in `$this->options`.
     * - Set up select minimum/maximum options to select if necessary.
     * @param \MvcCore\Ext\Form $form
     * @throws \InvalidArgumentException
     * @return \MvcCore\Ext\Forms\Fields\CountrySelect
     */
    public function SetForm (\MvcCore\Ext\IForm $form) {
        /** @var $this \MvcCore\Ext\Forms\Field */
        if (!$this->options) 
            $this->options = static::$allOptions;
        return parent::SetForm($form);
    }

    /**
     * This INTERNAL method is called from `\MvcCore\Ext\Forms\Field\Rendering` 
     * in rendering process. Do not use this method even if you don't develop any form field.
     * 
     * Render inner select control `<option>` tags or `<optgroup>` 
     * tags if there are options configured for.
     * @return string
     */
    public function RenderControlOptions () {
        $result = '';
        $valueTypeIsArray = is_array($this->value);
        if ($this->nullOptionText !== NULL && strlen((string) $this->nullOptionText) > 0) {
            // advanced configuration with key, text, CSS class, and any other attributes for single option tag
            $result .= $this->renderControlOptionsAdvanced(
                '', [
                    'value' => '',
                    'text'  => htmlspecialchars_decode(htmlspecialchars($this->nullOptionText, ENT_QUOTES), ENT_QUOTES),
                    'class' => 'country-none',
                    'attrs' => ['disabled' => 'disabled']
                ], $valueTypeIsArray
            );
        }
        foreach ($this->options as $key => & $value) {
            // advanced configuration with key, text, CSS class, and any other attributes for single option tag
            $result .= $this->renderControlOptionsAdvanced($key, [
                'class' => 'country-' . strtolower($key),
                'text'  => htmlspecialchars_decode(htmlspecialchars($value, ENT_QUOTES), ENT_QUOTES),
                'value' => htmlspecialchars_decode(htmlspecialchars($key, ENT_QUOTES), ENT_QUOTES),
            ], $valueTypeIsArray);
        }
        return $result;
    }
}