$Id$ ADDING SUPPORT FOR AN UNSUPPORTED COUNTRY ========================================= This file is a PHP programmer's description of what needs to be done in order to extend the location system to support locationes from a new country. Let's suppose we want to extend the location system to support locationes from Belgium. To this end, there are 2 tasks: TASK #1 --- We use the lower-case of the country's two-letter ISO 3166 code to create a file, "location.be.inc", that defines the necessary functions that will "hook" into the location system. This way, when a high-level function in the public location API receives a call that uses some Belgium specific function, the call will be delegated to the appropriately named function in "location.be.inc". TASK #2 --- You need postal code data for your country. This postal code data needs to be able to connect the base-length postal code (e.g., U.S. postal codes can be 9 digits, but we're only interested to the level of 5 digits and most people only know the 5-digit version) to a city, province/state, country (duh), and a latitude/longitude pair in degrees that represents the approximate center of the postal code's area. Ultimately, you will want to create a database dump that inserts these fields into specific columns: 'zip' (for postal codes), 'city' (for city names), 'province' for (the standard state/province/country abbreviation), 'country' (for the lower-case of the country's two letter ISO code), 'latitude' (for the latitude in degree value, as opposed to radian value) and 'longitude' (for the degree value of the longitude). In a lot of countries, this data costs money! You cannot simply create a dump and then publish it on drupal.org unless the data is free to redistribute. However, if you are interested in buying this data from some vendor and using it on your own site, you can do so but may have to acquire a new license for each seperate business or web site for which you wish to use postal code data if, in fact, you had to pay a fee or license for this data. This postalcode-to-lat/lon mapping is important if you want to enable location-based proximity searches of anykind for addresses in a particular country. The module will still work fine without it, but will not be able to support searches based on postal codes. WHAT WOULD GO INTO location.be.inc --------------------------------- This file will need to implement a handful of functions with the parameters and return values described below. It is possible to not implement all of these functions since the caller usually checks to see if the function exists before calling it, but it may limit the number of features the location system will be able to support for your country. For an example implementation of the functions described below, see "supported/location.us.inc". ------------------------------------------------------------------------------------------------- function theme_location_be($location, $hide); | ------------------------------------------------------------------------------------------------- @param $location An associative array $location where 'street' => the street portion of the location 'additional' => additional street portion of the location 'city' => the city of the location 'province' => the province, state, or territory 'country' => lower-cased two-letter ISO code (REQUIRED) 'postal_code' => the international postal code for this location (REQUIRED) @param $hide An linear array where the values are the location fields to suppress in the themed display. @return A string of the themed location. The entire location should be enclosed by '
'
tags. The different lines of the location should be enclosed by
tags. The idea is to allow country-specific files to change the display of an location from the default theming done in theme_location() defined in location.inc ------------------------------------------------------------------------------------------------- function location_province_list_be(); | ------------------------------------------------------------------------------------------------- Returns an associative array where -> the keys are the all-uppercase standard postal abbreviation for provinces, territories, and like subdivisions. -> the values are the fully spelled names of the abbreviated names. Preferrably, these will be sorted by the full name. ------------------------------------------------------------------------------------------------- function location_map_link_be($location); | ------------------------------------------------------------------------------------------------- Returns a deep-link to an online mapping service (e.g., "Yahoo! Maps", "MapQuest", or some other preferrably free service) given a full/partial location in the format described in public API document (location_API.txt). @param $location An associative array $location where 'street' => the street portion of the location 'additional' => additional street portion of the location 'city' => the city of the location 'province' => the province, state, or territory 'country' => lower-cased two-letter ISO code (REQUIRED) 'postal_code' => the international postal code for this location (REQUIRED) @return A URL with encoded HTTP GET variables to a free online-mapping service. (Note: URL, not HTML link). NULL if there is not even enough information to generate even a semi-useful link. "Useful" may depend entirely on the mapping service you choose to link to. You are advised to experiment: usually, a city/province combination is enough as is a postal code by itself, however, some services get confused when all fields are supplied. Some mapping services will be unable to map a city/province location while they can't do anything with a postal code while others map postal codes fine, but can't do anything useful with a city/province pair. -------------------------------------------------------------------------------------------------- function location_map_link_be_providers(); | -------------------------------------------------------------------------------------------------- Returns an array of mapping services to which the generation of deep-links is supported. "Supported" means that the function for that particular mapping service has been defined. For example, if the location.be.inc file for Belgium has functions for taking a location and generating a deep-link to Yahoo! Maps and google, this function will return that list in an array that give additional info. See location.us.inc for an example. @return An associative array where --> The keys are single words (no spaces) that identify a function in the same file for returning a deep link. For example, 'yahoo' means location_map_link_be_yahoo(). 'google' means location_map_link_be_google(). --> The values are themselves associative arrays with 3 expected keys: 'name' => The name of the mapping service. In the case of Yahoo, it would be 'Yahoo! Maps' 'url' => The full URL of the main page of the mapping service (i.e., the home page) 'tos' => The full URL of the Terms Of Service for the mapping service. -------------------------------------------------------------------------------------------------- function location_map_link_be_default_providers(); | -------------------------------------------------------------------------------------------------- Returns an array of 'default' mapping services. It may happen that the site administrator has not yet made it to the settings page for selecting mapping providers. In this case, we want to tell the location modules which one to use as defaults. To help the site admin avoid being in violation of each mapping services's Terms of Service, we return a linear array whose values are the appropriately selected keys in the array returned the location_map_link_xx_providers() function. @return A linear array with the one-word, no-spaced identifiers used to identify the mapping function. These should only be for the mapping services with relatively lenient and permissive Terms of Service. IMPORTANT: For more information on how to add support for deep-links, you are encouraged to see the examples in modules/location/supported/location.us.inc. If you need extra help, please feel free to submit a question on the issues queue for this project at: http://drupal.org/project/issues/location Replies will be prompt. -------------------------------------------------------------------------------------------------- function location_driving_directions_link_be($locationA, $locationB); | -------------------------------------------------------------------------------------------------- Returns a deep-link to an online mapping service (e.g., "Yahoo! Maps", "MapQuest", or some other preferrably free service) given full/partial locationes. Depending on whether or not the parameter locationes are complete enough for the chosen service, this function will return either a deep-link directly to the driving direction or will provide a deep-link to a partially pre-filled form for driving directions on the site you choose to link to. @param $locationA An associative array $location where 'street' => the street portion of the location 'additional' => additional street portion of the location 'city' => the city of the location 'province' => the province, state, or territory 'country' => lower-cased two-letter ISO code (REQUIRED) 'postal_code' => the international postal code for this location (REQUIRED) @param $locationB An associative array $location where 'street' => the street portion of the location 'additional' => additional street portion of the location 'city' => the city of the location 'province' => the province, state, or territory 'country' => lower-cased two-letter ISO code (REQUIRED) 'postal_code' => the international postal code for this location (REQUIRED) @return A URL (not HTML link) with HTTP GET variables tacked on to the end. This URL either points to a form for driving directions from $locationA to $locationB or a deep-link directly to the driving directions depending on how complete the locationes are. -------------------------------------------------------------------------------------------------- function location_get_postalcode_data_be($location = array()); | -------------------------------------------------------------------------------------------------- @param $location An associative array $location where 'street' => the street portion of the location 'additional' => additional street portion of the location 'city' => the city of the location 'province' => the province, state, or territory 'country' => lower-cased two-letter ISO code (REQUIRED) 'postal_code' => the international postal code for this location (REQUIRED) @return An associative array where 'lat' => A floating point for the latitude of the approximate center of the postal_code in the given $location 'lon' => A floating point for the longitude of the approximate center of the postal code in the given $location 'city' => The most appropriate city name for the given postal code in $location 'province' => The most appropriate province name for the given postal code in $location Returns NULL if the postal code doesn't make sense. Typically, this function will pull out the latitude/longitude of the approximate center of postal code in the given $location parameter as well as other data. The reason this can't be implemented at the non-country specific level in location.inc is that postal codes may be submitted in varying formats of varying precision while postal codes for this country in the database table may all be in a particular format. It is up to this country specific function to examine $location['postal_code'] and format it appropriately so that it matches with a postal code in the postal codes table. This 'hook' is meant to be a replacement for the location_get_latlon_rough_xx hook, described next. -------------------------------------------------------------------------------------------------- function location_latlon_rough_be($location = array()); | -------------------------------------------------------------------------------------------------- @param $location An associative array $location where 'street' => the street portion of the location 'additional' => additional street portion of the location 'city' => the city of the location 'province' => the province, state, or territory 'country' => lower-cased two-letter ISO code (REQUIRED) 'postal_code' => the international postal code for this location (REQUIRED) @return An associative array where 'lat' => A floating point for the latitude of the approximate center of the postal_code in the given $location 'lon' => A floating point for the longitude of the approximate center of the postal code in the given $location Returns NULL if the postal code doesn't make sense. Typically, this function will pull out the latitude/longitude of the approximate center of postal code in the given $location parameter. -------------------------------------------------------------------------------------------------- function location_latlon_exact_be($location = array()); | -------------------------------------------------------------------------------------------------- @param $location An associative array $location where 'street' => the street portion of the location 'additional' => additional street portion of the location 'city' => the city of the location 'province' => the province, state, or territory 'country' => lower-cased two-letter ISO code (REQUIRED) 'postal_code' => the international postal code for this location (REQUIRED) @return An associative array where 'lat' => A floating point for the latitude of the approximate center of the postal_code in the given $location 'lon' => A floating point for the longitude of the approximate center of the postal code in the given $location Returns NULL if the postal code doesn't make sense. Typically, this function will be implemented on top of a web-service for retrieving exact lat/lon information for a full location. This function is not a necessity, but a sample implementation would be helpful for future users. If not, it can always be added on a supply and demand basis.