New Signature is proud to announce another contribution to the Drupal community: addressfield_tokens. This module was designed to enhance the addressfield module by adding useful tokens and field formatters for addresses. It also integrates into webforms to provide address blocks on configurable survey forms.
Challenges with addressfield
The addressfield module provides an extremely useful field for attaching one or more addresses to any content type, and is fully internationalized. However, once an address is entered, it can be difficult to render the address in a sensible format.
When displaying a node, it can be useful to render only part of the address, such as the city and state, but ignore the rest, such as street and house number. When configuring an address field, you can’t tell it which components of the address will be important and which should be ignored. Furthermore, a format that uses commas to separate components should not include commas after components that happen to be empty.
When creating a CSV export file through the views_export module, it can be useful to include an entire address in a single column. However, the default field formatter inserts lots of markup. This markup can be stripped out, but that also removes all the whitespace between components of the address, making it hard to read.
When assembling text based on user input, it would be useful to be able to include the address they entered. For instance, consider the case of auto-responder emails when users register, donate or purchase an item. However, the addressfield module does not include any support for tokens, and since addresses are not entities themselves, the entity module can’t help either.
In addition, suppose you wish to sync user accounts into an external system such as MailChimp. The mailchimp module expects to receive user information in the form of tokens, and the Mailchimp API expects to receive addresses in a particular form, with two spaces between each component. However, it is not possible to do this out of the box without writing some custom connector code.
Because the addressfield module is fully internationalized, some of the components of the address have names that are a bit hard for an average content editor to interpret. For example, same of the components are named “Thoroughfare”, “Locality” and “Administrative Area”. While technically accurate, these names don’t convey much to a site administrator from the U.S., for example, who would prefer to see them listed as “Street 1”, “City” and “State”.
The addressfield_tokens module was designed to assist in each of these cases. It automatically attaches tokens to every address in the system, as long as the address is attached to an entity that already has tokens. It creates tokens for each of the components of the address, and also provides a number of additional tokens for rendering a full address in a variety of handy formats. In addition, the names of each of the address component tokens can be customized, so site editors have an easier time figuring out what each token does.
Here is an example of all of the tokens provided by the addressfield_tokens module. The names in the first column have been customized for the US.
The addressfield_tokens module also provides some new address field formatters that correspond to some of the extra tokens:
- City, State: Displays the city and state separated by commas, with the country appended if not the default country.
- One Line: Displays the address on a single line, with each component separated by commas. This field formatter is very convenient in CSV export views.
- Country: Displays the full name of the country, without any other components.
- State: Displays the full name of the state, without any other components. Since the addressfield typically stores a 2-letter state abbreviation in the database rather than the full name, this can be a useful way to get the full name.
In addition, the addressfield_tokens module provides a webform component, that adds a set of form fields for capturing an address to a webform survey. This makes it convenient to create forms that ask users for their address without the need to create each field separately. It also allows the address fields in the webform to be internationalized based on the user’s country, which would not be possible if each field were separate.
Give it a try!
Go to http://drupal.org/project/addressfield_tokens to try it out!