search

Beee4life / acf-city-selector

An ACF extension to create a new field type, where you can select a city based on country and provence/state.
38 stars 15 forks source link

readme

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

1.14.0 - 09.08.24

Description

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

Screenshot ACF City Selector

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

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:

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

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.14.0

1.13.0

1.12.0

1.11.0

1.10.1

1.10.0

1.9.1

1.9.0

1.8.0

1.7.0

1.6.0

1.5.0

1.4.0

1.3.2

1.3.1

1.3.0

1.2.0

1.1.0

1.0.0 - first release in WP repo

0.35.0

0.34.0

0.33.0

0.32.0

0.31.1

0.31.0

0.30.0

0.29.0

0.28.0

0.28.0-beta1

See older changelogs on the website.