US States is your ticket to quickly getting an US based directory up and running in ExpressionEngine. It comes bundled with all US States, the biggest cities in each state and information about them (population, zip codes, latitude, maps, etc.) - and of course the tags needed to retrieve all of this information and implement a states/cities directory based website. US States & Cities consists of a module with tags, an extension and a fieldtype. The add-on can be used for any country/region, but it does comes bundled with US states and cities so those would have to be deleted and new states/regions/cities would have to be added manually. To have a look at a demo demo click here. Please note; the dataset is not 100% complete and does not include all minor cities in the United States (and all zip codes). We're working on getting a demo up and running of this addon so you can browse the dataset for yourself.
The addon comes with an administration panel which initially will display the list of states:
Clicking a state will take you to a list of cities in that state, where you can delete or add cities.
Clicking on a city will bring you to a page where you can edit city information (name, slug, population) - in addition to adding/removing zip codes from the city (with latitude and longitude information). Note that you can add a zip code, leaving longitude/latitude empty - in which case the Google Maps API will be contacted to retrieve the correct latitude/longitude information.
The settings panel is pretty basic for now:
US States & Cities comes with a field type which can be used either to select a state or a city. The city selection is a basic dropdown of cities:
The city selection custom field saves the city_id - in addition to this you can specify a field to save the city slug to and a field to save the state slug to. This is recommended if the URL structure of your website require you to fetch channel entries by state / city slug (which would normally be the case).
These fields need to be created beforehand, and need to be of type text. You can hide these fields from the publish form using EE's publish layout functionality if you do not want to display them to the end user.
Also notice that "Is list of cities?" checkbox there. If this is left unticked the fieldtype will display a list of states instead of cities. This can be used for state selection - state_slug is what is saved for this fieldtype, as this is what most often will be used. The dropdown will look like this:
This tag is used to list all the states in the database, and it has these variables:
Example template code:
<h1>List of states</h1>
<ul>
{exp:states:state_list}
<li><a href='{path=us_states/{state_slug}}'>{state_name}</a> ({state_short_name})</li>
{/exp:states:state_list}
</ul>
Retrieve a list of cities in a specific state. Remember to give it the state_slug parameter, which you can get from one of the segment variables for instance.
Available variables:
Example template code:
<h1>List of cities in {exp:states:state_name slug='{segment_2}'}</h1>
<ul>
{exp:states:cities state_slug='{segment_2}'}
<li><a href='{path=us_states/{segment_2}/{city_slug}}'>{city_name}</a></li>
{/exp:states:cities}
</ul>
This tag is used to retrieve information about a specific city.
Parameters:
Available variables:
Note the Google Maps Static Images have lots of configurable options, which you can append to {city_map_image} - read up on that here.
Example template:
{exp:states:city_info slug='{segment_3}' state_slug='{segment_2}' map_width="600" map_height="300"}
<h1>Welcome to {city_name}, <a href='{path=us_states/{state_slug}}'>{state_name}</a></h1>
<p>This city has a population of <strong>{city_population_human}</strong> people!</p>
<p>
<table>
<tr>
<td>
<p>Default map:</p>
<p>
<img src='{city_map_image}' width="{city_map_width}" height="{city_map_height}"/>
</p>
</td>
<td>
<p>.. or we can add arguments to the image url like this (more info <a href="http://code.google.com/apis/maps/documentation/staticmaps/">here</a>):</p>
<p>
<img src='{city_map_image}&maptype=satellite' width="{city_map_width}" height="{city_map_height}"/>
</p>
</td>
</tr>
</table>
</p>
<p>
<h2>Variables</h2>
<ul>
<li>city_id: {city_id}</li>
<li>city_name: {city_name}</li>
<li>city_slug: {city_slug}</li>
<li>city_zip: {city_zip}</li>
<li>state_name: {state_name}</li>
<li>state_short_name: {state_short_name}</li>
<li>state_slug: {state_slug}</li>
<li>city_population: {city_population}</li>
<li>city_population_human: {city_population_human}</li>
<li>city_longitude: {city_longitude}</li>
<li>city_latitude: {city_latitude}</li>
<li>city_map_image: {city_map_image}</li>
<li>city_map_width: {city_map_width}</li>
<li>city_map_height: {city_map_height}</li>
</ul>
</p>
{/exp:states:city_info}
Use this to redirect to a specific state/city page based on a zip. This can for instance be useful in cases where you have a zip input field, or a dropdown and want to redirect users to a state/city listing based on the zip code they enter/select.
Parameters needed are zip (the zip code) and redirect which is the template group / url you want to redirect to. The redirect variable will basically be postfixed with /state_slug/city_slug/ and the user will be sent there.
Example template code:
{exp:states:redirect_by_zip zip="{segment_2}" redirect="available_houses"}
The code above will take the zip from the url segment, and redirect the users to a template group called "available_houses", so for instance http://www.myhouselistings.com/redirect_by_zip/94101 would redirect to http://www.myhouselistings.com/available_houses/california/san_francisco/
Use this to retrieve the city name by city/state slug.
For example: {exp:states:city_name slug='birmingham' state_slug='alabama'} will return "Birmingham".
Use this to retrieve the city database id by city/state slug.
For example: {exp:states:city_id slug='birmingham' state_slug='alabama'} might return 42.
Use this to retrieve the state name by its slug.