Installation

Before installing the extension, you need to install Meta Box plugin first.

1. Go to Plugins → Add New and search for Meta Box
2. Click Install Now button to install the plugin
3. After installing, click Activate Plugin to activate the plugin

The extension is just a WordPress plugin, you can install it like a normal WordPress plugin.

1. Go to Plugins, click Add new, then click Upload plugin.
2. Choose the .zip file you downloaded and click Install now
3. After finishing upload, click Activate to finish.

Make sure you know how to create meta boxes and fields before continuing!

Enabling geolocation

To enable geolocation support for a meta box, add this line to your Meta Box (not field) settings:

'geo' => true

You can also add options to Geolocation. Which can contains these properties:

• An array of types specifies an explicit type or a type collection, as listed in the supported types below. If nothing is specified, all types are returned. In general, only a single type is allowed. The exception is that you can safely mix the geocode and establishment types, but note that this will have the same effect as specifying no types. The supported types are:
  • geocode instructs the Places service to return only geocoding results, rather than business results.
  • address instructs the Places service to return only geocoding results with a precise address.
  • establishment instructs the Places service to return only business results.
  • the (cities) type collection instructs the Places service to return results that match either locality or administrative_area3.
  • the (regions) type collection instructs the Places service to return any result matching the following types:
    • locality
    • sublocality
    • postal_code
    • country
    • administrative_area1
    • administrative_area2
• bounds is a google.maps.LatLngBounds object specifying the area in which to search for places. The results are biased towards, but not restricted to, places contained within these bounds.
• componentRestrictions can be used to restrict results to specific groups. Currently, you can use componentRestrictions to filter by country. The country must be passed as a two-character, ISO 3166-1 Alpha-2 compatible country code.

For more information, visit Google Autocomplete Options

To add options, just pass an array of options to geo key instead of default 'geo' => true. For instance:

// Restrict the result in Australia only
'geo' => array(
    'componentRestrictions' => array(
        'country' => 'au'
    )
)

// Return only business results
'geo' => array(
    'types' => array( 'establishment' )
),

// Return only cities and business results
'geo' => array(
    'types' => array( '(cities)', 'establishment' )
),

Adding autocomplete field

To add an auto complete field. Simply add a text field and set it id starts with address. Like address or address_something… The plugin will treat that field as auto complete address field.

You can add auto complete to textarea, it works but will generate warning messages.

Populating field data

Address Components

When you selected an address from Auto-Complete field. It returns an array of Address Component Types. Which you can use it to populate to other fields. The following types are supported by Google:

For more information about address components visit: Google Address Component Types

Auto Populate

To auto populate data to the field. Just set that field’s ID same as one of Address Component Type above. For example, you create a number field with ID postal_code. The postal code type will auto populate to that field if exists.

Long name and Short Name

Let’s say we have a country named ‘Australia’. The long name is ‘Australia’ and short name is ‘AU’. And so on, if we have a state named ‘Queensland’, so ‘Queensland’ is the long name and ‘QLD’ is the short name.

By default, Meta Box Geolocation will populate the long name of the field. But you can use the short name by adding _short at the end of field id. For example: administrative_area_level_1_short, country_short

Binding Template

The power of Meta Box Geolocation is you can bind anything into a field. Let’s say we have a field with id dummy_field, this field id is not in Address Component Types list so by default the plugin won’t auto populate data to it. Now we’ll bind administrative_area_level_1 to that field. Just add

'binding' => 'administrative_area_level_1'

Example Result: Queensland

You can tell that field to use short version by prepending short: keyword

'binding' => 'short:administrative_area_level_1'

Example Result: QLD

You can also merge two fields, add any character you want to bind to that field. Like so:

'binding' => 'short:administrative_area_level_1 + " " + country'

Example Result: QLD Australia

Google API Key

By default, Google Geocoding API has the usage limit. See here. The free Google Geocoding API works in almost case but sometimes, you need to add API Key, or want to add custom params to URL. Just add a filter to gmap_api_params like so:

add_filter( 'gmap_api_params', function( $params ) {
    $params['key'] = 'YOUR API KEY';
    return $params;
});

Example

The plugin already ships with an example. You can browse it in examples/example.php.

Result