extending_support.txt in Location 5

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.