FINAL suepr merge step : added all modules to this super repos
This commit is contained in:
Bachir Soussi Chiadmi
@@ -0,0 +1,10 @@
|
||||
<p> Location 3.0 and later provide a location_api_variant() function to aid in allowing add-on modules to support
|
||||
multiple releases, even if there are incompatible changes.</p>
|
||||
|
||||
<h3>API variant 1</h3>
|
||||
<p>Start of API tracking. Based on Location 3.0.</p>
|
||||
|
||||
<h3>API variant 2</h3>
|
||||
<p>location_diff() renamed to location_calc_difference() because diff.module was trying to invoke it as a hook.</p>
|
||||
<p>Before: Call location_diff().</p>
|
||||
<p>Now: Call location_calc_difference().</p>
|
||||
264
sites/all/modules/contrib/fields/location/help/extending.html
Normal file
264
sites/all/modules/contrib/fields/location/help/extending.html
Normal file
@@ -0,0 +1,264 @@
|
||||
|
||||
<p><em>Note:</em> This file describes the original country API. While the API itself hasn't
|
||||
changed, some things have moved in directions not forseen by this documentation.
|
||||
For example, there is less emphasis today on postal data and more emphasis on
|
||||
geocoding webservices. Please take this documentation with a grain of salt until
|
||||
it is fully cleaned up and brought up to date.</p>
|
||||
|
||||
<h3>location.xx.inc: Adding support for an unsupported country</h3>
|
||||
<hr />
|
||||
|
||||
<p>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.</p>
|
||||
|
||||
<p>Let's suppose we want to extend the location system to support locationes from Belgium. To this end,
|
||||
there are 2 tasks:</p>
|
||||
|
||||
TASK #1
|
||||
<p>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".</p>
|
||||
|
||||
TASK #2
|
||||
<p>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).</p>
|
||||
|
||||
<p>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.</p>
|
||||
|
||||
<p>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.</p>
|
||||
|
||||
<h3>Contents of location.be.inc</h3>
|
||||
<hr />
|
||||
<p>This file will need to implement a handful of functions with the parameters and return values described below.</p>
|
||||
|
||||
<p>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.</p>
|
||||
|
||||
<p>For an example implementation of the functions described below, see "supported/location.us.inc".</p>
|
||||
|
||||
<pre>
|
||||
-------------------------------------------------------------------------------------------------
|
||||
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 <dl class="location"> </dl> tags.
|
||||
The different lines of the location should be enclosed by <dl> </dl> 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
|
||||
</pre>
|
||||
|
||||
<pre>
|
||||
-------------------------------------------------------------------------------------------------
|
||||
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.
|
||||
</pre>
|
||||
|
||||
<pre>
|
||||
-------------------------------------------------------------------------------------------------
|
||||
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.
|
||||
</pre>
|
||||
|
||||
<pre>
|
||||
--------------------------------------------------------------------------------------------------
|
||||
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.
|
||||
</pre>
|
||||
|
||||
<pre>
|
||||
--------------------------------------------------------------------------------------------------
|
||||
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.
|
||||
</pre>
|
||||
|
||||
<pre>
|
||||
--------------------------------------------------------------------------------------------------
|
||||
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.
|
||||
</pre>
|
||||
|
||||
<pre>
|
||||
--------------------------------------------------------------------------------------------------
|
||||
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.
|
||||
</pre>
|
||||
|
||||
<pre>
|
||||
--------------------------------------------------------------------------------------------------
|
||||
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.
|
||||
</pre>
|
||||
|
||||
<pre>
|
||||
--------------------------------------------------------------------------------------------------
|
||||
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.
|
||||
</pre>
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
[testing]
|
||||
title = "Testing Procedure"
|
||||
file = test_procedure
|
||||
|
||||
[extending]
|
||||
title = "Country API"
|
||||
file = extending
|
||||
|
||||
[api_changelog]
|
||||
title = "API variant reference (changelog)"
|
||||
file = api_changelog
|
||||
@@ -0,0 +1,62 @@
|
||||
<h3>GMap 1.x / Location 3.x Tester Checklist</h3>
|
||||
<hr />
|
||||
|
||||
Setup from scratch:
|
||||
|
||||
<ul>
|
||||
<li>Enable modules</li>
|
||||
<li>Visit <a href="base_url:admin/settings/gmap">admin/settings/gmap</a> and configure API key.</li>
|
||||
<li>Visit <a href="base_url:admin/settings/filters">admin/settings/filters</a> and set up a GMap filter.</li>
|
||||
<li>Visit <a href="base_url:admin/content/types">admin/content/types</a> and (create if desired and) location-enable a content type.</li>
|
||||
<li>Visit <a href="base_url:admin/settings/location/geocoding">admin/settings/location/geocoding</a> and configure geocoding for a country.</li>
|
||||
<li>Visit <a href="base_url:admin/user/settings">admin/user/settings</a> and configure the Location Fields section.</li>
|
||||
<li>Visit <a href="base_url:admin/build/block">admin/build/block</a> and enable the Author Map and Location Map blocks.</li>
|
||||
<li>Visit <a href="base_url:admin/build/block/configure/gmap_location/1">admin/build/block/configure/gmap_location/1</a> and enable the Author block for the content type you location-enabled.</li>
|
||||
</ul>
|
||||
|
||||
Tests 1 (GMap macros):
|
||||
|
||||
<ul>
|
||||
<li>Visit <a href="base_url:map/macro">map/macro</a>, play with the controls and ensure map responds, play with map and ensure controls respond.</li>
|
||||
<li>Doodle on the map, make sure drawing controls work as expected.</li>
|
||||
<li>Copy macro, open another window/tab.</li>
|
||||
<li>Create a node, set filter to GMap filter and paste macro.</li>
|
||||
<li>Save node, compare display of map to macro in other window/tab.</li>
|
||||
</ul>
|
||||
|
||||
Tests 2 (Location user):
|
||||
|
||||
<ul>
|
||||
<li>Edit your user account. Add your location.</li>
|
||||
<li>Ensure geocoding works.</li>
|
||||
<li>Ensure the data is not lost when going back to edit.</li>
|
||||
</ul>
|
||||
|
||||
Tests 3 (Location nodes):
|
||||
|
||||
<ul>
|
||||
<li>Create a node with locative information.</li>
|
||||
<li>Ensure Author Map and Location Map display as expected.</li>
|
||||
</ul>
|
||||
|
||||
<h3>Advanced section - Stuff involving special setup or advanced knowledge</h3>
|
||||
<hr />
|
||||
|
||||
ADVANCED: Upgrade path:
|
||||
|
||||
<ul>
|
||||
<li>Create test site on Location 2.7.</li>
|
||||
<li>Perform tasks from "Setup from scratch" section.</li>
|
||||
<li>Create or import test data.</li>
|
||||
<li>Install Location 3.</li>
|
||||
<li>Attempt to perform updates.</li>
|
||||
<li>Ensure in database that data was properly split off into {location_instance}.</li>
|
||||
<li>Ensure site settings are in a sane state (You should not get any misconfiguration-related warnings/errors.)</li>
|
||||
<li>Visually inspect some locations on site.</li>
|
||||
</ul>
|
||||
|
||||
ADVANCED: Nonstandard usage:
|
||||
|
||||
<ul>
|
||||
<li>Disable gmap and create locative nodes. Ensure form continues to work in the absence of gmap.</li>
|
||||
</ul>
|
||||
Reference in New Issue
Block a user