Documentation

Introduction

Welcome to the City Selector plugin/extension for Advanced Custom Fields. This plugin extends the functionality of ACF. Just install it and discover a new field choice. See it in action here.

Installation

  • Download the plugin here.
  • Upload it through FTP to wp-content/plugins or use the upload function and upload the downloaded zip file.
  • Activate the plugin through the plugins page.

Configuration

  • Open or create an ACF field group.
  • Click 'Add Field'.
  • Choose any name you want.
  • Choose any key you want.
  • Add the 'City Selector' field option (see example below).
  • Select whether to show labels above the input fields (default = yes).
  • Save/publish the Field Group.

A new field option

Usage

To retrieve a stored value use the following code:

  1. $city_selector = get_field('field_name');

The variable $city_selector returns 5 values in an array:

  1. array(5) {
  2.   ["countryCode"]=>
  3.   string(2) "NL"
  4.   ["stateCode"]=>
  5.   string(5) "NH"
  6.   ["cityName"]=>
  7.   string(9) "Amsterdam"
  8.   ["stateName"]=>
  9.   string(13) "Noord-Holland"
  10.   ["countryName"]=>
  11.   string(11) "Netherlands"
  12. }

Output it as follows:

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

This outputs:

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

Actions

As of v0.4 there will be 2 functions available, for an easy retrieval of data. Both make use of a transient.

acfcs_get_countries()

This function returns transient `acfcs_get_countries` containing all countries, with a value and a label for each.

  1. array(
  2.     'value' => 'NL', 
  3.     'label' => 'Netherlands' 
  4. )

acfcs_get_cities( $country_code )

This function returns transient `acfcs_get_cities_{country_code}` with all cities, from a specific country, containing a value, a label and a merged abbreviation of country + state.

array {
  'label' => string 'Amsterdam',
  'value' => string 'Amsterdam',
  'state' => string 'NL-NH'
}

Hooks

Since v0.3 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

Countries

If you install the plugin you get 3 countries included;

  • Belgium
  • Luxembourg
  • Netherlands

You can delete them from the settings page (if you want). And re-import them separately (if you would only need 1 or 2).

You can also insert your own cities (in CSV format) if you need any cities from non-included countries.

Get more countries

If you would like to get more countries for your form, you can create a csv formatted file/data set and import them manually. Please find more info about this in the contextual help menus.

We will be offering 'pre-made country packages' which are ready to be imported. More info about this soon...

Support

If you need support, please turn to GitHub (for now).