ACF City Selector Field

Welcome to the City Selector plugin, which is an extension for Advanced Custom Fields. This is not a stand-alone plugin, you'll need ACF for it.

Index

Version
Description
Installation
Usage
Impact
Cities
Shortcode
Hooks
Compatibility
Tested on
Support
Remove donation notice
Website
Disclaimer
Credit
TO DO
Changelog

Version

0.8

Description

This plugin allows you to select a city, based on country and province/state in an ACF Field Group.

It creates a new field type for you to choose when you're creating an ACF Field Group. If you click '+ add field' in a Field Group, you will find a new option (category: "Choice") to choose called City Selector.

Add the field.
Choose any name you want.
Choose any key you want.
Select whether to show labels above the input fields (default = yes)
Save/publish the Field Group.

Installation

Copy the acf-city-selector folder into your wp-content/plugins folder.
Activate the ACF City Selector plugin via the plugins admin page.
Create a new field via ACF and select the City Selector type (listed in the Choice section).
(optional) Import new cities with help of the included excel sheet.
Please refer to the description for more info regarding the field type settings.

Usage

3 values are stored in an array:

array(3) {
  ["countryCode"]=>
  string(2) "NL"
  ["stateCode"]=>
  string(5) "NL-NH"
  ["cityName"]=>
  string(9) "Amsterdam"
}

The reason why the country is prefixed in the storage is because there can be states/provinces which use the same abbreviation. You won't notice this, since we format this value on return.

We override the return value so you get more return info and properly formatted (stateCode). 5 values are returned:

array(5) {
  ["countryCode"]=>
  string(2) "NL"
  ["stateCode"]=>
  string(5) "NH"
  ["cityName"]=>
  string(9) "Amsterdam"
  ["stateName"]=>
  string(13) "Noord-Holland"
  ["countryName"]=>
  string(11) "Netherlands"
}

Echo it as follows:

$city_selector = get_field('field_name');
echo 'I live in ' . $city_selector['cityName'];
echo 'which is in ' . city_selector['stateName'] . ' (' . city_selector['stateCode'] . ')'; 
echo ' which lies in the country: ' . $city_selector['country'] . ' (' . $city_selector['countryCode'] . ')';

This outputs:

"I live in Amsterdam which is in the state Noord-Holland (NH) which lies in the country Netherlands (NL)".

display data with shortcode

To display the city/ state field, add this code below to function.php file

function location_getter ($atts){ //$field_name, $data_type
  $default = array(
      'data_type' => 'city',
      'field_name' => '', //put the default name of the field name in ACF here
      );
    $a = shortcode_atts($default, $atts);
  $city_selector = get_field($a['field_name']);
  // instead of creating two functions two type of data can exists, the one to extract city name or state name
  if ($a['data_type']=="city"){
    return $city_selector['cityName'];
  }
  else{
    return $city_selector['stateName'];
  }
}


/**
YOu can now use the shortcode [get_locale data_type = "city"], [get locale data type = "state"]
or otherwise in your wordpress text editors.


*/

Impact

The plugin adds a database table named {$wpdb->prefix}cities upon plugin activation and imports cities from 3 different countries.

Cities

The plugin comes with all cities in the Benelux (Belgium, Netherlands, Luxembourg) pre-installed.

You can also add more countries yourself, through SQL or CSV import. There's a simple excel sheet included in the plugin and can be found in the import folder. With this sheet, you can easily create an SQL insert statement or a CSV data set.

The explanation on how to do this, can be found on the first tab/sheet of the excel file.

We have created several country packages (csv files) especially for this plugin. These files are ready to go and can be imported without right away. These will be made available for a small fee soon, through the ACFCS website.

Hooks

There are a few hooks available to add your own custom actions.

acfcs_after_success_verify - hooks after successful csv verification
acfcs_after_success_import - hooks after successful csv import
acfcs_after_success_import_raw - hooks after successful raw csv import
acfcs_after_success_import_be - hooks after importing preset country Belgium
acfcs_after_success_import_lu - hooks after importing preset country Luxembourg
acfcs_after_success_import_nl - hooks after importing preset country Netherlands
acfcs_after_success_nuke - hooks after truncating the table

Compatibility

This ACF field type is compatible/tested with ACF 4 (Free) as well as ACF 5 (Pro).

Tested on

Wordpress 5.2.2
Advanced Custom Fields 4.4.12
Advanced Custom Fields Pro 5.8.2

Support

If you need support, please turn to Github.

Remove donation notice

If you want to remove the donation box in ACF, add the following line to functions.php: add_filter('remove_acfcs_donate_nag', '__return_true');

Website

http://acfcs.berryplasman.com (not for support)

Disclaimer

This plugin is not 100% finished yet. It most likely won't break anything but use caution, just in case.

This plugin doesn't work yet in the following field types, when adding more than 1 instance:

repeater
group
flexible content

Credit

I got the idea for this plugin through Fabrizio Sabato who used it a bit differently, which can ben seen here.

Since I couldn't fix the Javascript for this plugin, Jarah de Jong took care of it.

To Do

Changelog

0.8

Fix incorrect version

0.7

Change indentation from spaces to tabs

0.6

Translate more strings
Fix import errors for Luxembourg
DRY import code

0.5

Fix unescaped characters on import

0.4

Internationalised all cities/states/countries

0.3

Added hooks for import/delete actions

0.2

Added database collation

emlycool / acf-city-selector