Skip to content
This repository was archived by the owner on Jan 4, 2021. It is now read-only.

Home

Jump to bottom
bennylope edited this page Jun 18, 2012 · 1 revision

Simple locations management.

Overview

The locations app handles the requirement for product/vendor search. It consists of a backend that stores the names, location types, and location (in the form of an address and geospatial point) and various query methods.

The administrative interface supports simple in-place editing as well as mass update by CSV upload.

The app exposes several views on the front end, using both HTML and JSON responses. These include:

  • List of all locations
  • Sorted list of locations * By name * By type
  • Filtered list of locations * By name (search) * By type * By location (zip code, lat-long box)

The locations app provides a Google Maps ready JSON feed with documentation for using on the front page.

List and search view

The search view returns a list of locations, and it accepts various search parameters as query parameters in the URL. There is no POST functionality. AJAX requests (those made with XMLHttpRequest) will receive results back in JSON format.

The URL name for the search view is location_index, and the path will look like:

/<location_root>/

An alternate search view is available for use with a different template. The URL name is location_list. This is the same view as used for the locations index, but its declared with a different template and pagination criteria.

Context variables

The primary context variable is the locations queryset. Each location object in this list has the following accessible attributes:

  • id
  • name
  • street_address
  • city
  • postal_code
  • latitude
  • longitude
  • url
  • description
  • category

Latitude and longitude are returned as decimal numbers (floats). The url and description fields are not being used at this time.

The category field is a many to many relationship. To access the category data, use the manager method:

{% for category in location.category.all %}
    {{ category.name }}
{% endfor %}

WARNING: this should ONLY be used in detail pages, as the M2M query will result in one query for the search being broken into X queries, where X is the number of matching locations. This slows the page load a lot.

The JSON response includes the same information, minus the url and description fields, and adding a link field, which is available as the resolved URL for the detail view. The categories are inclued as a list of objects each with an id, a name, and a slug (the categories are included in the JSON because the server result is still quite fast).

Search parameters

Each parameter is listed with a description and whether it can be used in multiple instances. All are optional and independent of each other.

  • geo_query: either a zip code or a geo-coordinates pair in the form of latitude, longitude, e.g. geo_query=34.12,-89.87. One instance
  • city: name of a city. This will filter on exact names. One instance
  • state: name of a state. This will filter on exact names. Multiple instances
  • postcode: a postal code, used to filter the list. Multiple instances
  • category: the category ID, used to filter the list. Multiple instances
  • search: a phrase on which to search. Searches against the location names and their city names. One instance
  • direction: direction for sorting, either blank or a dash, "-". One instance
  • sort: the field name on which to sort the results. Defaults to "name". If a geographic search is performed an no sort parameter is used, it defaults to "distance". The "distance" sort is unavailable unless a geographic search is performed using the geo_query parameter One instance
  • limit: an integer limiting the number of results. This is available, but probably not of much use due to the pagination capability. One instance
  • paginate_by: an integer identifying how many items to show per pag. Items will be paged in loading via HTML. JSON responses are never paged. The default is 50 items per page.

Detail view

A detail view is available. This view has one primary context variable, location which refers to the specific location. The view is access by location ID, with the named url location_detail.

{% url location_detail location.id %}

The URLs will take the form /<location_root>/<id>/.

Templates

The templates available are:

templates/locations/location_base.html
templates/locations/location_detail.html
templates/locations/location_list.html
templates/locations/location_index.html

The "index" and "list" (or "search") views use the same class, the LocationListViewClass but each uses a different template, and a different starting page item count. The view at the root URL uses the location_index.html template, and the view at the /search/ URL uses the location_list.html template. The context variables are exactly the same between these two "distinct views".

Postal codes

This is a utility application for the locations app. It includes one model, PostalCode, which stores:

  • the post code (string)
  • latitude (float)
  • longitude (float)
  • city (string, optional)
  • state (string, optional)

If time permits it will be refactored to include a 'country' field. This will make it compatible with the eventual public release.

The application has initial values for a PostgreSQL database which includes all US postal codes with their respective geographic coordinates. No city or state data is included.

Clone this wiki locally