Permalink
Browse files

Update the README

  • Loading branch information...
jlecour committed Oct 16, 2010
1 parent 48b3ed3 commit 372d2325b78026ec4bd5743b76680f22c2a2d12d
Showing with 23 additions and 24 deletions.
  1. +23 −24 README.markdown
View
@@ -1,6 +1,6 @@
## INSTALLATION
-
-Geokit consists of a Gem ([geokit-gem](http://github.com/andre/geokit-gem/tree/master)) and a Rails plugin ([geokit-rails3](http://github.com/andre/geokit-rails3/tree/master)).
+
+Geokit for Rails consists of a gengeric Gem ([geokit-gem](http://github.com/andre/geokit-gem)) and a Rails plugin ([geokit-rails3](http://github.com/andre/geokit-rails3)).
Make sure you use a version >= 3.0 of Rails.
@@ -11,8 +11,8 @@ You just have to add the 'geokit-rails3' gem to your Gemfile
Then tell bundler to update the gems :
$ bundle install
-
-If you want to use geokit-rails3 in a Rails 2 application, just use the good old plugin.
+
+If you want to use geokit-rails in a Rails 2 application, just use the good old plugin ([geokit-rails](http://github.com/andre/geokit-rails)).
## FEATURE SUMMARY
@@ -38,8 +38,8 @@ package.
## A NOTE ON TERMINOLOGY
-Throughout the code and API, latitude and longitude are referred to as lat
-and lng. We've found over the long term the abbreviation saves lots of typing time.
+Throughout the code and API, _latitude_ and _longitude_ are referred to as _lat_
+and _lng_. We've found over the long term the abbreviation saves lots of typing time.
## LOCATION QUERIES
@@ -93,32 +93,31 @@ specified for `lng_column_name` and `lat_column_name`:
Often you will need to find within a certain distance. The prefered syntax is:
- Location.origin(@somewhere).within(5)
+ Location.within(5, :origin => @somewhere)
. . . however these syntaxes will also work:
- find.origin(@somewhere).where("distance < 5")
-
+ find.geo_scope(:origin => @somewhere).where("distance < 5")
+
Note however that the second form should be avoided. With the first,
Geokit automatically adds a bounding box to speed up the radial query in the database.
With the second form, it does not.
If you need to combine distance conditions with other conditions, you should do
so like this:
- Location.origin(@somewhere).within(5).where(:state => state)
-
-If the _within_ scope is called without an _origin_ scope, it is simply ignored.
+ Location.within(5, :origin => @somewhere).where(:state => state)
Other convenience scopes work intuitively and are as follows:
- Location.origin(@somewhere).beyond(5)
- Location.closest(@somewhere)
- Location.farthest(@somewhere)
-
-The `closest` and `farthest` scopes just add a `limit(1)` in the scopes chain.
+ Location.beyond(5, :origin => @somewhere)
+ Location.in_range((5..10), :origin => @somewhere)
+ Location.closest(:origin => @somewhere)
+ Location.farthest(:origin => @somewhere)
+
+The `closest` and `farthest` methods just order by distance and add a `limit(1)` in the scopes chain.
-Lastly, if all that is desired is the raw SQL for distance
+Lastly, if all that is desired is the raw SQL for distance
calculations, you can use the following:
Location.distance_sql(origin, units=default_units, formula=default_formula)
@@ -131,22 +130,22 @@ the finders. So for instance:
You can then chain these scope with any other or use a "calling" method like `first`, `all`, `count`, …
- Location.origin(@somewhere).within(5).all
- Location.origin([37.792,-122.393]).first
+ Location.within(5, :origin => @somewhere).all
+ Location.geo_scope(:origin => [37.792,-122.393]).first
## FINDING WITHIN A BOUNDING BOX
-
+
If you are displaying points on a map, you probably need to query for whatever falls within the rectangular bounds of the map:
- Store.bounds([sw_point,ne_point]).all
+ Store.in_bounds([sw_point,ne_point]).all
The input to `bounds` can be array with the two points or a Bounds object. However you provide them, the order should always be the southwest corner, northeast corner of the rectangle. Typically, you will be getting the sw\_point and ne\_point from a map that is displayed on a web page.
If you need to calculate the bounding box from a point and radius, you can do that:
bounds=Bounds.from_point_and_radius(home,5)
- Store.bounds(bounds).all
-
+ Store.in_bounds(bounds).all
+
<!-- End of the first batch of "updates" -->
## USING INCLUDES

0 comments on commit 372d232

Please sign in to comment.