Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wintercms/wn-location-plugin
Location plugin for Winter CMS
https://github.com/wintercms/wn-location-plugin
hacktoberfest
Last synced: 3 months ago
JSON representation
Location plugin for Winter CMS
- Host: GitHub
- URL: https://github.com/wintercms/wn-location-plugin
- Owner: wintercms
- License: mit
- Created: 2021-03-06T05:28:17.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-04-08T17:36:57.000Z (7 months ago)
- Last Synced: 2024-05-23T09:21:41.223Z (5 months ago)
- Topics: hacktoberfest
- Language: PHP
- Homepage:
- Size: 154 KB
- Stars: 5
- Watchers: 5
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-wintercms - Winter.Location - Provides location data (Countries & States) for use by other plugins. (Uncategorized / Uncategorized)
README
# Location plugin
This plugin adds location based features to [Winter CMS](https://wintercms.com).
* Easily add Country and State to any model
* Form widget for address lookups (Google API)
### Google API key requirement
As of June 22, 2016 the Google Maps service requires an API key. You may generate a key from the following link:
- [Get a Google API key](https://developers.google.com/maps/documentation/javascript/get-api-key)
Copy the key and enter it in the **Settings > Location settings** area. If you find the address finder is not working, you may need to enable the [Places API](https://console.developers.google.com/apis/api/places_backend/overview?project=_) and the [Maps JavaScript API](https://console.developers.google.com/apis/api/maps_backend/overview?project=_).
### Add Country and State to any model
This plugin provides an easy way to add location fields, country and state, to any model. Simply add these columns to the database table:
```php
$table->integer('country_id')->unsigned()->nullable()->index();
$table->integer('state_id')->unsigned()->nullable()->index();
```
Then implement the **Winter.Location.Behaviors.LocationModel** behavior in the model class:
```php
public $implement = ['Winter.Location.Behaviors.LocationModel'];
```
This will automatically create two "belongs to" relationships:
1. **state** - relation for Winter\Location\Models\State
1. **country** - relation for Winter\Location\Models\Country
### Back-end usage
#### Forms
You are free to add the following form field definitions:
```yaml
country:
label: winter.location::lang.country.label
type: dropdown
span: left
placeholder: winter.location::lang.country.select
state:
label: winter.location::lang.state.label
type: dropdown
span: right
dependsOn: country
placeholder: winter.location::lang.state.select
```
#### Lists
For the list column definitions, you can use the following snippet:
```yaml
country:
label: winter.location::lang.country.label
searchable: true
relation: country
select: name
sortable: false
state:
label: winter.location::lang.state.label
searchable: true
relation: state
select: name
sortable: false
```
### Front-end usage
The front-end can also use the relationships by creating a partial called **country-state** with the content:
```twig
{% set countryId = countryId|default(form_value('country_id')) %}
{% set stateId = stateId|default(form_value('state_id')) %}
Country
{{ form_select_country('country_id', countryId, {
id: 'accountCountry',
class: 'form-control',
emptyOption: '',
'data-request': 'onInit',
'data-request-update': {
'country-state': '#partialCountryState'
}
}) }}
State
{{ form_select_state('state_id', countryId, stateId, {
id: 'accountState',
class: 'form-control',
emptyOption: ''
}) }}
```
This partial can be rendered in a form with the following:
```twig
{% partial 'country-state' countryId=user.country_id stateId=user.state_id %}
```
### Short code accessors
The behavior will also add a special short code accessor and setter to the model that converts `country_code` and `state_code` to their respective identifiers.
```php
// Softly looks up and sets the country_id and state_id
// for these Country and State relations.
$model->country_code = "US";
$model->state_code = "FL";
$model->save();
```
### ISO 3166-1 accessors
The behavior will also add the ISO-3166-1 values as accessors to the model (data sourced from the [league/iso3166](https://github.com/thephpleague/iso3166) package).
Availables accessors are `iso_name` (country name), `iso_alpha3` (three-letter code), `iso_numeric` (three-digit code), `iso_currencies` (three-digit currencies code) and `iso` (array of all iso attributes).
```php
$usCountry = \Winter\Location\Models\Country::whereCode('US')->first();
$usCountry->iso_name;
// (string) "United States of America"
$usCountry->iso_alpha3;
// (string) "USA"
$usCountry->iso_numeric;
// (string) "840"
$usCountry->iso_currencies;
// (array) [ 0 => "USD" ]
$usCountry->iso;
// (array) [
// "name" => "United States of America"
// "alpha2" => "US"
// "alpha3" => "USA"
// "numeric" => "840"
// "currency" => [
// 0 => "USD"
// ]
// ]
```
### Address Finder Form Widget
This plugin introduces an address lookup form field called `addressfinder`. The form widget renders a Google Maps autocomplete address field that automatically populates mapped fields based on the value entered and selected in the address.
Available mappings:
- street
- city
- zip
- state
- country
- country-long
- latitude
- longitude
- vicinity
Available options:
You can restrict the address lookup to certain countries by defining the `countryRestriction` option. The option accepts a comma separated list of ISO 3166-1 ALPHA-2 compatible country codes (see: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
Usage:
```yaml
# ===================================
# Form Field Definitions
# ===================================
fields:
address:
label: Address
type: addressfinder
countryRestriction: 'us,ch'
fieldMap:
latitude: latitude
longitude: longitude
city: city
zip: zip
country: country_code
state: state_code
vicinity: vicinity
city:
label: City
zip:
label: Zip
country_code:
label: Country
state_code:
label: State
latitude:
label: Latitude
longitude:
label: Longitude
vicinity:
label: Vicinity
```