ACF City Selector

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 (active) for it to run.

• Version
• Description
• Impact
• Installation
• Setup
• Usage
• Cities
• Actions
• Filters
• Functions
• Compatibility
• Tested on
• Support
• Website
• Disclaimer
• Credit
• Changelog

Version

1.15.1 - 26.10.24

Description

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

It creates a new field type for you to choose when you're creating an ACF Field Group.

Impact

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

Installation

1. Download the latest release zip file.
2. In your WordPress admin, go to Plugins -> Add New
3. Click Upload Plugin
4. Upload the zip file that you just downloaded.
5. Activate the ACF City Selector plugin via the plugins page.

If you use a composer file to add any plugins/libraries. Add the following to your composer.json:

  "repositories": [
    {
      "type": "composer",
      "url": "https://wpackagist.org"
    }
  ]

Then run composer require "wpackagist-plugin/acf-city-selector"

Setup

1. Create a new field via ACF and select the City Selector type (listed in the Choice section).
2. Select if you want to show labels (default = yes)
3. Select if you want to use select2 (default = no) [ACF pro only]
4. Select if you want a default country (default = none)
5. (optional) Import new cities with help of the included Excel sheet.
6. (optional) Import new cities by csv (available on the website).

Usage

When the field is used by a single field, 3 values are stored in an array:

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

When the field is used in a repeater field, the values are stored in a multidimensional array:

array(2) {
  [0]=>
  array(3) {
    ["countryCode"]=>
    string(2) "BE"
    ["stateCode"]=>
    string(5) "BE-BR"
    ["cityName"]=>
    string(10) "Anderlecht"
  }
  [1]=>
  array(3) {
    ["countryCode"]=>
    string(2) "NL"
    ["stateCode"]=>
    string(5) "NL-FL"
    ["cityName"]=>
    string(6) "Almere"
  }
}

The reason why the state is prefixed (with the country code) in the database is because there can be states/provinces which use the same abbreviation as in another country. You won't notice this, since this value is formatted on return.

The return value gets overridden, so you get 'more return info' and a 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)".

Cities

The plugin comes with all cities in Belgium and the Netherlands 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.

There are a few country packages (csv files) available. These packages can be imported as is. These are available through the ACFCS website.

Actions

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

Find all actions here.

Filters

Find all filters here.

Functions

A few custom functions are available for you to easily retrieve data.

Find all functions and their info here.

Compatibility

This ACF field type is compatible/tested with ACF 5 (Pro). It's slightly tested with the free version (v4), but we won't be putting any (more) time in it. Just buy the Pro version. It's worth every cent !

Tested with

• WordPress 6.6.2
• Advanced Custom Fields Pro 6.3.9
• Advanced Custom Fields 4.4.12

Support

If you need support, please turn to Github. It's faster than the Wordpress support.

Website

acf-city-selector.com

Disclaimer

The plugin works in the following situations:

• in a single field
• in a repeater field
• in a group
• in a flexible content block
• in an accordion field
• as a cloned field
• on taxonomy terms
• on settings pages

The plugin does NOT work properly yet in the following situations:

• when multiple instances of the field are used in 1 group/on 1 post

It might have some twitches with taxonomies, but need some more testing.

Sometimes the loading of states/cities, takes a few seconds... Don't know why yet... This seems to be very random and unpredictable.

Credit

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

Jarah de Jong helped me out with some JS at the start and John McDonald did some of the German translations.

Changelog

1.16.0

• add nonces for forms

1.15.1

• use wp_filesystem for csv files
• sanitize/escape more

1.15.0

• set menu slug for (hidden) admin pages to prevent empty admin page title
• fix vulnerability in file upload
• improved i18n strings
• sanitized/escaped more input/output

1.14.0

• update database queries for searching citites in admin
• update database queries for deleting countries in admin
• removed transients because it conflicted with translation

1.13.0

• remove typo in function call

1.12.0

• fix clearing of transients

1.11.0

• fix incorrect index for store as single meta

1.10.1

• new language files

1.10.0

• add option to store location as single meta values
• fix ordering for states (which caused some issues)

1.9.1

• fixed incorrect version

1.9.0

• fixed case in states transient
• added wpdb->prepare (where needed)
• reverted version by function due to some people reporting errors

1.8.0

• fixed preview
• fixed city names with an '
• fixed city names with special characters

1.7.0

• fixed raw import

1.6.0

• removed import of free countries on plugin activate
• removed country transient due to incorrect names being stored when using multiple languages

1.5.0

• added new options to v4 version (which were already available for v5)
• improve adding of ajax url
• add filter to change user cap to access settings
• sprintf a lot of values
• prefix input names to prevent any errors
• clean up files
• make more functions to prevent 'spaghetti code'

1.4.0

• fix broken image in readme
• change incorrect filter to action
• simplified some IF statements
• sprintf more output
• translated some strings

1.3.2

• escape attributes in dropdowns (via @hardweb-it)

1.3.1

• fix styling which was overriding the styling of other messages
• remove function from uninstall.php which prevented deleting of plugin

1.3.0

• fix non-showing errors on verify csv file
• show all errors, instead of just first encountered
• fix dismiss error button

1.2.0

• don't pre-load cities on country change
• fix help tab which overrides other plugins' help tabs
• stripslash searched value (admin)
• update default csv (fixed some typos with 's and 't)

1.1.0

• fix typos + capitalization

1.0.0 - first release in WP repo

• prefix javascript function names

0.35.0

• escape js value

0.34.0

• escape user inputs

0.33.0

• code refactoring according to (most) Wordpress standards

0.32.0

• add acfcs_upload_folder filter
• improve code by making more 'smaller' functions
• import preset countries from csv instead of php
• remove some unnecessary hooks

0.31.1

• fix version number

0.31.0

• change default delimiter from , tot ;.
• change import sheet from , tot ;.
• fixed non-working max lines setting on import
• added Japan and South Korea country files
• extended Spain country file

0.30.0

• messed up release with version numbers

0.29.0

• added a fix for select2 in repeaters/flexible content blocks
• added a fix for incorrect escaping which caused incorrect ordering in names starting with a '.
• added new function as fallback for acfcs_get_country_name()
• added China, New Zealand, Aruba and Curaçao country files
• removed flag assets from plugin
• changed URLs to new website domain

0.28.0

• added select2 option
• changed hide labels filter as fallback for select2
• added new country packages on the website

0.28.0-beta1

• added a new option: "state/province + city" (for when a default country is set)
• added a transient for cities per state
• added 3 new filters to override field labels
• added a new filter to override showing of field labels
• (re-)added a check for database version to prevent unnecessary table updates

See older changelogs on the website.