This tutorial will detail how to set up a search feature that can sort cloned pages based on physical distance. The most common use of this is as a Store Locator: a visitor searches with their own Postal Code (PC) and a listing is generated with the closest locations. The example code that follows makes use of the 5-digit US ZIP Code and miles unit of length. With minor modifications it can accommodate any other Postal Code format and unit of length.
Central to making all of this work is acquiring a database with the required fields: postal code, latitude, and longitude. I have attached a US ZIP Code table which was originally sourced from GeoNames. This organization has PC tables for many countries: http://download.geonames.org/export/zip/
Instructions:
1. Import your PC data into a new table in the same MySQL database as your Couch installation. When you do this, select CSV as the file format. If you are using a txt file directly from GeoNames you will need to change the column delimiter to a tab character: \t
From there you may choose to drop any of the unused columns and change their names. See the screenshot below for how my table is structured.
2. Download the attached PostalCode PHP Class and Couch example template. For this example I have set up the Search template as the clonable template as well. In a real-world implementation of this however, you will want to use a different template for the cloned pages.
Also hosted on GitHub at https://github.com/cheesypoof/CouchCMS-Postal-Code-Search.
3. Install the template as you would normally and add a few example pages like I have done to test the functionality:
4. Open postalcode.php and set the top variables according to your configuration. Test everything out.
Notes:
This requires at minimum Couch v1.3.5 to be installed because the cms:query tag is utilized.
Generally speaking, as the range increases, so too does the completion time of the Postal Code query. For example, in a test I used 2500miles and experienced a page load time of 1400ms, whereas for 250miles I saw only 460ms. You will need to test this on your server to determine what maximum load times are acceptable.
Distance calculations should be considered approximations; I can't vouch for the accuracy of the GeoNames location data.
Internationalization:
In the example, we displayed the distance in miles as follows: <cms:number_format distance decimal_precision='0'/>
We can display this in kilometers as follows: <cms:number_format "<cms:mul distance '1.60934'/>" decimal_precision='0'/>
To accommodate differently formatted Postal Codes you will need to modify the editable region validator regex.
Links:
PHP ZipCode Class (GNU General Public License v3) - https://github.com/Quixotix/PHP-ZipCode-Class
GeoNames (Creative Commons Attribution 3.0 License) - http://www.geonames.org/
Central to making all of this work is acquiring a database with the required fields: postal code, latitude, and longitude. I have attached a US ZIP Code table which was originally sourced from GeoNames. This organization has PC tables for many countries: http://download.geonames.org/export/zip/
Instructions:
1. Import your PC data into a new table in the same MySQL database as your Couch installation. When you do this, select CSV as the file format. If you are using a txt file directly from GeoNames you will need to change the column delimiter to a tab character: \t
From there you may choose to drop any of the unused columns and change their names. See the screenshot below for how my table is structured.
2. Download the attached PostalCode PHP Class and Couch example template. For this example I have set up the Search template as the clonable template as well. In a real-world implementation of this however, you will want to use a different template for the cloned pages.
Also hosted on GitHub at https://github.com/cheesypoof/CouchCMS-Postal-Code-Search.
3. Install the template as you would normally and add a few example pages like I have done to test the functionality:
Beverly Hills, California - 90210
Los Angeles, California - 90035
Las Vegas, Nevada - 89104
Seattle, Washington - 98101
Dallas, Texas - 75201
Chicago, Illinois - 60606
Miami, Florida - 33139
4. Open postalcode.php and set the top variables according to your configuration. Test everything out.
Notes:
This requires at minimum Couch v1.3.5 to be installed because the cms:query tag is utilized.
Generally speaking, as the range increases, so too does the completion time of the Postal Code query. For example, in a test I used 2500miles and experienced a page load time of 1400ms, whereas for 250miles I saw only 460ms. You will need to test this on your server to determine what maximum load times are acceptable.
Distance calculations should be considered approximations; I can't vouch for the accuracy of the GeoNames location data.
Internationalization:
In the example, we displayed the distance in miles as follows: <cms:number_format distance decimal_precision='0'/>
We can display this in kilometers as follows: <cms:number_format "<cms:mul distance '1.60934'/>" decimal_precision='0'/>
To accommodate differently formatted Postal Codes you will need to modify the editable region validator regex.
Links:
PHP ZipCode Class (GNU General Public License v3) - https://github.com/Quixotix/PHP-ZipCode-Class
GeoNames (Creative Commons Attribution 3.0 License) - http://www.geonames.org/