newism/craft3-fields

Address, telephone and email fields for CraftCMS 3.x

A collection of custom Fields CraftCMS

Installation

Open a command console, enter your project directory and execute the following command to download the latest stable version of this plugin:, _(*1)

$ composer require newism/craft-fields && ./craft plugin/install nsm-fields

Configuration

• If you're using Address Autocomplete you'll need an api key.
• If you're embedding Instagram you'll need an api key.
• If you're embedding Facebook you'll need an api key.

Add the api keys to your environment and set in the plugin settings. See: https://craftcms.com/docs/3.x/config/#environmental-configuration, _(*2)

Alternatively…, _(*3)

Copy src/config.php to CRAFT_CONFIG_PATH and rename the file to nsm-fields.php., _(*4)

Fields

Address

Address field powered by Google's dataset (commerceguys/addressing)., _(*5)

Features:, _(*6)

• Auto-complete powered by Google Place API
• Map powered by Google Maps Javascript API and Google Maps Geocoding API
• Address form formatting based on country powered by commerceguys/addressing
• Validation / Geo-coding on submission (TODO)

Template Tags:, _(*7)

The normalizeValue method always returns an AddressModel. All public properties are available:, _(*8)

Given entry.address is your field…, _(*9)

See: https://github.com/commerceguys/addressing/blob/master/src/AddressInterface.php
{{ entry.address.countryCode }}
{{ entry.address.administrativeArea }}
{{ entry.address.locality }}
{{ entry.address.dependentLocality }}
{{ entry.address.postalCode }}
{{ entry.address.sortingCode }}
{{ entry.address.addressLine1 }}
{{ entry.address.addressLine2 }}
{{ entry.address.organization }}
{{ entry.address.recipient }}
{{ entry.address.locale }}

See: https://github.com/commerceguys/addressing/blob/master/src/Country/Country.php
{{ entry.address.country.countryCode }}
{{ entry.address.country.name }}
{{ entry.address.country.threeLetterCode }}
{{ entry.address.country.numericCode }}
{{ entry.address.country.currencyCode }}
{{ entry.address.country.locale }}

{{ entry.address.placeData }}
{{ entry.address.latitude }}
{{ entry.address.longitude }}
{{ entry.address.mapUrl }}

, _(*10)

Telephone

Telephone field powered by Googles phone number library implemented via giggsey/libphonenumber-for-php, _(*11)

Features:, _(*12)

• Validate phone number based on country code
• Format phone number as E164, international, national or RFC3966
• Stores Telephone model and raw user input

Template Tags:, _(*13)

Given entry.telephone is your field…, _(*14)

{{ entry.telephone }} outputs the phone number in international format., _(*15)

You can also choose a specific format:, _(*16)

{{ entry.telephone.format('E164') }}
{{ entry.telephone.format('international') }}
{{ entry.telephone.format('national') }}
{{ entry.telephone.format('RFC3966') }}

The raw input from the user is also available:, _(*17)

{{ entry.telephone.rawInput }}, _(*18)

, _(*19)

Email

Features:, _(*20)

• Email validation using Yii validation

, _(*21)

Embed

Features:, _(*22)

• Embed social media posts / media directly from a URL
• Live preview

Template Tags:, _(*23)

Given entry.embedField is your field…, _(*24)

• {{ entry.embedField.embedData }} outputs the returned embed object.
• {{ entry.embedField.embedData.code | raw }} outputs the returned embed javascript code.

Additional data:, _(*25)

{{ entry.embedField.embedData.authorName }} // The resource author
{{ entry.embedField.embedData.authorUrl }} // The author url
{{ entry.embedField.embedData.cms }} // The cms used
{{ entry.embedField.embedData.code.html }} // The code to embed the image, video, etc
{{ entry.embedField.embedData.code.width }} // The exact width of the embed code (if exists)
{{ entry.embedField.embedData.code.height }} // The exact height of the embed code (if exists)
{{ entry.embedField.embedData.code.aspectRatio }} // The aspect ratio (width/height)
{{ entry.embedField.embedData.description }} //The page description
{{ entry.embedField.embedData.favicon }} // The favicon of the site (an .ico file or a png with up to 32x32px)
{{ entry.embedField.embedData.feeds }} // The RSS/Atom feeds
{{ entry.embedField.embedData.icon }} // The big icon of the site
{{ entry.embedField.embedData.image }} // The thumbnail or main image
{{ entry.embedField.embedData.keywords }} // The page keywords
{{ entry.embedField.embedData.language }} // The language of the page
{{ entry.embedField.embedData.languages }} // The alternative languages
{{ entry.embedField.embedData.license }} // The license url of the resource
{{ entry.embedField.embedData.providerName }} // The provider name of the page (Youtube, Twitter, Instagram, etc)
{{ entry.embedField.embedData.providerUrl }} // The provider url
{{ entry.embedField.embedData.publishedTime }} // The published time of the resource
{{ entry.embedField.embedData.redirect }}
{{ entry.embedField.embedData.title }} //The page title
{{ entry.embedField.embedData.url }} //The canonical url
{{ entry.embedField.embedData.ombed }} // oembed data 
{{ entry.embedField.embedData.linkedData }} // json-LD data

Note: embed data saved with v1 saved the html to {{entry.embedField.embedData.code}}. In v2 {{ entry.embedField.embedData.code }} changed to an array. Your templates will need to account for both versions… something like:, _(*26)

{{ (entry.embedField.embedData.code.html|default ?: entry.embedField.embedData.code|default) | raw }}

, _(*27)

Person Name

Person name field with:, _(*28)

• Honorific Prefix
• Given Names
• Additional Names
• Family Names
• Honorific Suffix

, _(*29)

Gender

Non-binary gender field with:, _(*30)

• Sex
• Identity

, _(*31)

Road Map

Some things to do, and ideas for potential features:, _(*32)

• Split out each field into it's own plugin. Keep this plugin as a single composer file which pulls all fields in
• Address validation / Geo-coding on submission
• Display address as text in field with option to "Edit" to reduce size of field in UI
• Update commerceguys/addressing when next stable version is released

Credits

Brought to you by Newism, _(*33)

, _(*34)