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.13.0 - 21.04.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

Download the latest release zip file.
In your WordPress admin, go to Plugins -> Add New
Click Upload Plugin
Upload the zip file that you just downloaded.
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

Create a new field via ACF and select the City Selector type (listed in the Choice section).
Select if you want to show labels (default = yes)
Select if you want to use select2 (default = no) [ACF pro only]
Select if you want a default country (default = none)
(optional) Import new cities with help of the included Excel sheet.
(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.2
Advanced Custom Fields Pro 6.1.4
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.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.

Name		Name	Last commit message	Last commit date
Latest commit History 1,573 Commits
admin		admin
assets		assets
import		import
inc		inc
languages		languages
.gitignore		.gitignore
ACF_City_Selector.php		ACF_City_Selector.php
README.md		README.md
composer.json		composer.json
readme.txt		readme.txt
uninstall.php		uninstall.php

Beee4life/acf-city-selector

Folders and files

Latest commit

History

Repository files navigation