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:

The variable $city_selector returns 5 values in an array:

Output it as follows:

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.

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.

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