dev-journal-ryan.txt

== to do ==

=== 1.0a3 ===
* examples - geomap drawStyle option

=== 1.0a35 ===
* geomap - use profiling to improve pan performance
* geomap - remove this-style state properties
* geomap - remove "px" from .css calls
* geo - use Array.push instead of $.merge
* docs - upgrade to jQuery Mobile rc2
* docs - allow page refreshing
* geomap - [bug] changing services array (without changing all services) after initialization fails
* geomap - [bug] multiple maps do not work on the same page
* geomap - use _currentServices in all functions unless we actually need to update the public  options services object
* geomap - create _defaultState object, use for widget-local _widgetState property, reinit _widgetState on _createWidget
* geomap - don't redraw shapes after interactiveScale, they've already been drawn at new scale
* examples - geomap resize method
* examples - multiple maps example
* geomap - [bug] when a singled image hasn't loaded after pan and you double click on empty space, the zoomed bbox seems wrong
* remove BOM from release files
* add 3rd party license headers

=== future ===
* geomap - test jQuery widget call chaining when setting option values
* geomap - pan lags on first drag
* docs - geomap - more modes: measureDistance, measureArea
* docs - geomap - document the correct way to add a service after init
* docs - geo - detect geodetic coordinates and call $.geo.proj automatically, don't require devs to set $.geo.proj to null
* geo - detect geodetic coordinates and call $.geo.proj automatically, don't require devs to set $.geo.proj to null
* docs - geomap - append label argument
* geomap - port shape labels
* geomap - unbind keydown handler on destroy, it's on the document
* docs - $.geo.WKT object
* geo - $.geo.WKT object
* geomap - reenable graphics redraw on interactiveScale, if canvas...and scale canvas
* docs & examples - settle on the word "option" in all text (instead of property) to match widget function
* docs - make all map examples live
* docs - explain the 96px scale bar, why 96?
* docs - write a full page about GeoJSON and what each object type is to $.geo
* docs - geomap - allow name as service object property
** if a service has a name property, it will maintain a hidden input with the given name
* docs - geomap - service-level shapes
* docs - geomap - service-level shapeStyle
* docs - geo - support up to GeometryCollection in distance
* geo - support up to GeometryCollection in distance
* docs - geo - support up to GeometryCollection in contains
* geo - support up to GeometryCollection in contains
* docs - geo - support up to GeometryCollection in centroid
* geo - support up to GeometryCollection in centroid
* docs - geo - empty function
* geo - geometry - empty function
* geomap - show a drawPoint style while the mouse is down, hide if toolPan or dbltap scale
* geomap - android - [bug] cannot always pan map after appending shapes
* geomap - deep extend existing service objects when services property is set
* geomap - cache point bbox if $.geo.proj is not null?
* code - prefer $.data over $.fn.data
* docs - internal - explain what projection is and which one we use by default (3395) and maybe why we call it web mercator & why we can't get to +/- 90 lat
* docs - internal - document how geomap draws shapes, the geomapgraphics widget and the reason shapeStyle is a method
* geomap - label divs should have class="geo-label" & style="position: relative;"
* geomap - find should check labels first
* geo - geometry - implement JTS note: "The centroid is equal to the centroid of the set of component Geometries of highest dimension (since the lower-dimension geometries contribute zero "weight" to the centroid)"
* geo - Support WKT with $.geo.parseWKT & $.geo.textify
* geo - All bbox operations should be done in non-geodetic coordinates for accuracy
* geo - support bbox in distance ( fix geomap.find )
* docs - geomap - shapeLabel property
** template for labels for all shapes added via append
* docs - geomap - multiple labels
* geomap - multiple labels
* geomap - service-level shapes
* geomap - [bug] mouse wheel on bad or missing tile doesn't zoom out on first rotate
* docs/geomap - store WKT input for each service
* geographics - rename the generated style properties to something simple or get better control over closure compiler
* geographics - add a resize method, call from geomap.resize
* geomap - Document and implement find's callback syntax
* geomap - repeat horizontal tiles
* geomap - custering demo/support
* proj - take scale factor into account when calculating distance in web mercator
* geographics - Disable fill by setting style.fill to "" & stroke by style.stroke to ""
* graphics - See Modernizr for comment on BB Storm & canvas detection
* geographics - Document graphics widget
* geomap - [BUG] Android browser stops pan/zoom after 7 logos on logo demo
* geomap - store a copy of shapes as WKT in a hidden input
* geomap - only update WKT copy if shape is appended with refresh argument set to true
* geomap - find - [maybe] after flatten, check more cached bboxes for non-Point geometrie
* docs - geomap - SVG & other neat elements/media in labels
* docs - geo - $.geo.guessLocation function
* geo - $.geo.guessLocation function
* docs - services - document the plugin architecture
** create must return a jQuery collection where geomap can store state info
* docs - geomap - drawPush function
** in the drawing modes, this function starts drawing or adds a point into the already-started shape at the given coordinate
** immediately triggers the shape event if mode is drawPoint
* geomap - drawPush function
* docs - geomap - drawStop function
** in the drawing modes, this function ends drawing and triggers the shape event with whatever coordinates have already been added to the shape
* geomap - drawStop

==2011-11-07==
===gzip===
I added gzip to jquerygeo.com & all subdomains. jQuery Geo (minified & gzipped) is now 17k and falling!

===move===
I don't like that mouse move events seem laggy with this release. I need to find out what's different. I thought it was that I'm sending move events even while drawing that removing that hasn't helped.

===drawing===
Wow, geomap._refreshDRawing was terrible and geographics._drawLines needed a little tweaking.

===return false===
I didn't have any return falses at the end of my event handlers. I hope that plus the drawing fix makes panning better.

Oops, I went too crazy and added too many and wasn't letting the browser grab events it needed. Chrome's type=number input went crazy up or down if you didn't move the mouse away.

===chrome===
I've done what I can. The issue appears to be with Chrome or something I'm doing with Chrome. Drawing and panning speed is tremendous in IE9 and Firefox 7.

===geolocation===
Wow, after any timeout, Firefox stops checking for watchPosition? Is that part of the spec? Nope, not part of the spec. Oh, it *is* part of the spec if it fails due to timeout. It does sound like it's not supposed to trigger until the position changes despite what you put in maximumAge.

==2011-11-01==
===shapeStyle===
Time to redo the shapeStyle example in a much more awesome way.

Did I miss something? jQuery UI widget factory isn't complaining that shapeStyle isn't an option on the widget even though I haven't added it yet.

New demo is super-cool!

===refreshShapes===
I almost had this function clear the shapes geographics until I realized that it's recursive if there's a GeometryCollection. Can't do that.

==2011-11-01==
===refresh===
Cleaned up the wording for append, remove & empty. Also, going to have append allow style only, refresh only, or both.

===refreshShapes===
Due to performance, I'm going to disable the auto refresh after interactiveScale of shapes if the number of shapes is over a certain limit, say, 255.

==2011-10-31==
===tile paint===
Another app I want will be tilepaint.jquerygeo.com. It won't actually use jQuery Geo but will repaint tiles on the fly for you based in an input URL and color changes.

===fromGeodeticPos===
There's a bug trying to convert some positions of a town near Concord in the voting demo. I wonder what's different about that geometry.

The shape is a multipolygon which I am not handling properly. It can be a quadArray. I also removed all the $.each calls which should speed things up a bit.

All set now.

===ArcGIS Wrapper===
agw.jquerygeo.com will take an ArcGIS Server endpoint and spit out the jQueryGeo you need to initialize a map to that service. It should handle both cached and dynamic services.

==2011-10-30==
===voting===
I'm working with Calvin Metcalf at MassDOT attempting to push all the data into jQuery Geo. I might want an option to turn off scaling vector data because it's rather slow. Maybe only do it if they have WebGL.

Disabled it for now.

===refresh===
The refersh property must be made public, pushing large number of features isn't useful without out.

==2011-10-29==
===id/class===
I'm at WhereCamp Boston 2011 and going to try to finish Alpha 3 while I'm here starting with making id optional.

===initOptions===
Was getting undefined when a user passed nothing as in the simplest test.

===class===
So, I forgot that class is a reserved word. I'm not sure what to do about that. I can make id optional for now but I'll have to decide about class as a property name. I know as an object literal, I'm supposed to enclose the word in quotes but that's not going to look right for the user who wants to use this. I might have to call it cssClass or something. I'll find out what jQuery uses.

Google Closure won't even minify the build with the word class used as I'm using it. When I'm creating an element using jQuery's argument that takes an object for attributes, what do they use? They require quotes.

===id===
I'm still storing the service state by id. Since both id and class are optional, I think I need to store it as an array. That's not true, I can store an id on the service object via $.data. The id can be $.now. I wonder if $.now actually has different values if I'm creating more than on service at the same time? I will need to test and potentially use a different means to create the id.

===service create===
I'm going to assume that the service doesn't already exist during create. Not sure if that's a good idea though. Maybe for now, I won't and I can make the create code smaller later after I have time to test.

I completely forgot that I'm going to store the entire service state via $.data. That will make things a lot easier.

Seems to work ok.

===double click on unloaded===
When a singled image hasn't loaded after pan and you double click on empty space, the zoomed area seems wrong.

===fusion===
Andres from Google is showing radius query using fusion tables. Seems like something I can do with jQuery Geo.

===kml===
I might have to support kml.

===maps.jquerygeo.com===
I should support typing a url to a geojson file to append all of the json.

==2011-10-28==
===style===
Both shapeStyle and drawStyle get and set a plain JavaScript object and should be widget "option"s. While changing them does have side effects, they perform no action themsevles.

===centroid===
I'm leaving centroid in a3 but removing support for GeometryCollection for now (in the docs & code). That can come later.

===distance===
No sense having the two lines that support arrays, they'll never hit a valid switch case and it's not in the docs.

==2011-10-25==
===service state===
I finally moved it to a $.data store on the services container. It was getting messed up moving between pages in jQuery Mobile when one of the pages had a map.

==2011-10-21==
===resize===
Shingled maps don't resize properly. I think I have to have a resize method in there & call it from geomap. All set, I had to mark the current scaleContainer as not being for the given scale any longer and re-center it.

===visible===
I can't decide about this property of the service object. I need an API audit from Bocoup :(

Since I have opacity and visibility in shapeStyle, and I know I'm not going to change them, I think I do want to have the naming synergy because I do have opacity in service properties that I'm not going to change. Ugh, but the toggle method takes a true or false value. But so does jQuery's and that changes a CSS property from one text string to another.

===change service object===
Unlike the shape objects, I think it's fine if I change the service object's visibility property. It's sort of awful to see the check for undefined & I change it anyway when they use the toggle method. Why not just set it to "visible" when I create the service?

==2011-10-15==
===draw pan===
The current version didn't get the code ported over that disables inertia while drawing. I think I need to put that in because without it, the drawing does feel too fidgety.

I was calling _panEnd instead of _panFinalize for the draw modes.

===draw polygon===
Finally ported this code over. Seems ok.

==2011-10-14==
===maps===
I would like to make an app that lives at maps.jquerygeo.com and has some useful functionality similar to Google maps but uses all open data.

==2011-10-12==
===push it===
jQuery Geo is still functional in Chrome drawing all of the census tracts of MA. That's over 55,000 points and 3,000 features. Not too bad.

==2011-10-07==
===drawLineString===
I've ported some initial line code and actually made it much more elegant than our internal one.

===shingled===
The shingled demo needs some work.

==2011-10-06==
===bbox===
I pushed out a great new bbox example page. It links to a live jsFiddle even so people can play with the code.

===jQM buttons===
I did have to make the full screen map an external page. It worked ok after that and the back button still works.

===jQM===
jQM has virtual buttons to handle either touch or mouse input (some devices have both at the same time): vclick, vdown, vmove & vup. However, they don't handle multi-touch so I think I'm going to have to stick with what I have at the moment. I can't require jQM just to have jQG work on mobile.

===draw===
Porting our shape drawing code over finally. We're getting a new geographics widget to differentiate drawing from appended shapes.

===drawStyle===
I forgot to write about the drawStyle method. This one might actually be a true option as it will never be service-specific. It can only apply to the map widget.

===draw functions===
I need to rename some things. I've been using a few old names from our internal code but they don't quite make sense with some of the newer names of public properties. Mostly, shape should mean anything added via append and draw is the actual in-process drawing.

Two internal method names should be: _refreshShapes (instead of _drawGraphics) & _refreshDrawing (instead of _redrawShape)

===drawPoint dblclick===
As the docs say, a double tap will zoom in just like in pan mode and not trigger the shape event.

===geographics===
Oops, my underlying geographics widget is sharing the same canvas context. Flicker city! Ah, much better.

===drawPoint===
Because I'm delaying before I trigger the shape event, it feels slugish. Maybe I can drop the delay down to 100ms. Too fast, I'm getting the shape event.

==2011-10-04==
===jqcon===
I gave a presentation to jQuery Conference Boston 2011. I didn't have much time because I was sharing a block with another speaker. So, my presentation was rushed but I still think a few people interested. I will have to get better at conveying that this is not a wrapper for Google Maps or OpenLayers. We do not host any 3rd party controls.

===jQM buttons===
With a jQuery Mobile controlgroup or navbar on the same page as a full screen map, I get huge performance issues on Android. iOS seems ok with it. Desktop browsers are fine. The map doesn't pan while sliding your finger but it does show up in the new location when you let go.

Removing the navbar completely didn't help. I think that unless it's a small in-page map, I'm going to have to make the page external.

===bbox===
To test these new bbox functions, I'm going to redo the bbox example page.

==2011-09-30==
===json===
I can store a tiling scheme in JSON but just realized that I can't store a service definition in JSON because of the getUrl function property.

==2011-09-29==
===zoom===
Documenting and adding the zoom method.

===bbox===
Made bbox public. It's also now storing projected coordinates. $.geo.proj can also accept bbox arguments now.

==2011-09-28==
===disable auto-proj===
Peter suggested (for actual GIS users) a way to disable $.geo.proj but keep the object where it is. The situation is: "I know I'm working in a projection, and I want $.geo.proj to match that projection, but I don't want it to attempt to auto-project coordinates I pass to $.geo functions or geomap because I'm going to send it projected coordinates, but I do want the object around for when I might want to un-project some coordinates to geodetic."

That's wordy but it does make sense.

However, instead of adding a boolean on $.geo called autoproject and telling people that they can shut it off, I'm going to test diving into arguments to determine if they are geodetic and auto-projecting myself. There will be a performance hit but I need to test if it's too much or worth the simplicity. I think I'm going to find that it's worth the simplicity. I can then remove A LOT of words from the docs about if $.geo.proj is null, blah, blah.

That's fine for input values, but what about auto-unprojecting output values? Maybe I do need that boolean property on $.geo? Or I can store the last way center, bbox, or bboxMax were set and return values in the same format. I would rather it not be that tricky though. If I do add a property, it would only need to be for geomap. The $.geo functions are stateless.

===wkt===
Working on WKT.stringify/parse. There will be a $.geo.WKT object.

Moving along, made the frame of a nice test page too.

===destroy memory===
A destroyed geomap remembers what was in _graphicShapes. This means that any other private property initialized with _prop: default, is remembered. There could be other issues...until I replace all indivdual properties with a single state objects. For now, I'm going to reset _graphicShapes to [] in createWidget.

==2011-09-27==
===destroy===
Somethings wrong with destroy, can't create after. One thing missing is that resize is called (by jQuery Mobile?) after the call to destroy which causes a script error. I have to make sure I unbind resize. Huh, I've never had to unbind a handler before. Heh, destroy erases any content you had inside the widget before you created a geomap.

==2011-09-26==
===refactor===
Found bugs in serviceType.destroy and graphics due to code refactor. The CDN, while wonderful, takes too long to update. I suppose it's not the best idea to put the test branch on the CDN. Done. I'll still occasionally copy test to the CDN but mostly I'm going to update the non-CDN'd version until I know things are ok.

Alpha 3 docs online & tweeted about!

==2011-09-24==
===resize===
My code refactoring broke auto-resize. I wonder what else I broke :)

==2011-09-23==
===filename===
I renamed the compiled JS files to match what code.jquery.com has for jQuery itself and jQM. jQUI isn't on there, which is odd.

===widget factory syntax hack===
Testing if the syntax I want is possible with the jQuery UI widget factory pattern. I only want the one widget, but I want to be able to call some functions on other child elements. I already hit a snag. Calling .geomap("toggle") on an element that has not been initialized as a geomap widget doesn't trigger _createWidget, _create or toggle.

===serviceTyep files===
I'm going to split out the service type objects into their own files. That'll help me make sense of the geomap.js file.

To do that, I had to move _serviceTypes from being an option of geomap to a propery on $.geo itself. This will help third-party service type plugins down the road.

===widget vars===
I think I have to move all the widget vars back into the object passed to $.widget so that they don't conflict with each other, e.g., multiple geomap widgets. As they are now, I think they're all plugin-level widgets.

===sub-widgets===
This is awesome. It looks like I can get the syntax I want. Now to figure out the best way to call the method in the parent geomap widget from a service widget.

It seems like the vars created in the closure supplied to $.widget are still used by all widgets on the page. Do I really have to store state in a data object on the element?

Yes, they are shared. Yes, I will have to figure something out.

I just had to plaster my code with this's. I don't like it but it now supports the toggle/opacity syntax I want and *I think* also supports multiple maps on the same page (I think). That's going to increase my minified size quite a bit. I'm going to have to go back and see what I can do to clean it up but I'm choosing proper functionality over code size for the moment.

==2011-09-21==
===docs===
I'm trying to clean up the docs and change notational $.geo to jQuery Geo, but not mess up anywhere I mean to reference $.geo the namespace.

===class===
I have a better plan for service id. I'm going to keep my plan for having the presense of a name property create a hidden input but I'm going to allow the service object to have a class. The class will be applied directly to the built-in service divs. I will still apply data-service-type="tiled" or data-service-type="shingled" to the divs. To apply certain methods to specific services, you will now target the service class under the map element:

$("#map .osm").geomap("toggle", false); // this will hide OSM.

===service create===
I'm going to require that the service type's create function return a jQuery collection of one item that is addressable for that service. It doesn't really HAVE to have anything in it but I'm going to store service state on it using $.data($el, "geoServiceState", {}) or something.

===jqm===
Upgraded to jQuery Mobile b3 & added some color to the headers of various doc pages.

===service id===
After talking to Peter, I'm going to allow class and id with a note that if you use id, you'll have to be careful of adding more than one map on the page. I like this plan. Also, if you do it by id, you can target it directly:

$("#mass-gis").geomap("toggle");

===widget tricks===
I'm not sure I can do the selector tricks I want with the widget factory. I may have to change my docs & design if I can't do it elegantly :(

==2011-09-20==
===cache===
I may be caching too aggressively. I think I should remove caching from $.geo.bbox and instead cache inside of append and clear the bbox cache in remove. I really only need it in the find method.

===jquerygeo.com===
It's time this project got its own nice site. Also, (mt) is faster than my previous host from places farther away than MA.

==2011-09-18==
===shape===
Working on the event docs.

===name===
I was originally going to rename id in the service objects to name so I could use it as an input name on a hidden input. However, I'm now going to require id but allow name as an optional property. If present, it will create the hidden input. This is now a future task and will not be in alpha.

===append===
While adding the refresh argument to append, I started thinking again how I want to implement service-level graphics. It would be very nice if I could have the map>service syntax to jQuery and call append, remove and empty on that. I think I defined the syntax a while ago...yeah, see "On shape functions" from 2011-06-02.

The issue I have is that a page can have two maps. The default service has id=OSM. So, if I allowed $("#map #OSM") syntax, it would cause the page to have two elements with the same id, #OSM. However, $("#map [data-geo-service='OSM']") is way to wordy. I'll have to discuss this with others later as this is not an alpha feature either.

==2011-09-16==
===foss4g===
FOSS4G is an inspiring conference. I gave my talk and people seemed interested. There was a question about Google. I answered that it's illegal to use them and Chris Schmidt mentioned on Twitter that it's not illegal, it's just hard. We're talking different things. jQuery Geo would use Google tiles directly, which is against license. We will never host a third party widget inside the jQuery Geo div as part of the core functionality. OpenLayers wraps the official Google widget to get around the license restriction (since it's the official Google widget, there's nothing wrong with it) & keeps it up to date (or slides it around) when the user interacts with the OL map. I might do something similar as a blog post when I open up the service types plugin system but until then, but it won't be part of jQuery Geo..."here's how to do it if you want", type of thing. The developer would have to pull in the Google maps API themselves.

===centroid===
I'll have to see if JTS uses Point or Coordinate as a return value & match it.

Centroid needs to use $.geo.proj for accuracy. The centroid should be calculated in web mercator & projected back to geodetic.

===proj===
The way we do projection is different than how GIS does it. Usually, when you define a projection, you work in non-geodetic coordinates because the coords have been projected to a flat plane. With jQuery Geo, you work in projected coordinates (I call them non-geodetic) when you set $.geo.proj to null. This can be a little confusing but I think it works.

The first thing we would have to do internally is set $.geo.proj to null because we use pro

===bbox proj===
bbox might be an issue. a bbox in geodetic coordinates (lon/lat) that is a rectangle, will not be a rectangle in web mercator. That's not a problem with setting the bbox property on geomap but could prove interesting for the bbox of geometry objects. For example, the bbox of a square polygon will not be a parallelagram in geodetic coordinates.

SUGGESTION: Calculate & cache bbox in projected coordinates
SUGGESTION: Document that lon/lat bboxes will not appear to be correct?

===bbox cache===
Peter and I got into a talk about caching bboxes. He's worried that we will have too many floating references to objects that cannot be collected. That is a valid point. For example: a user creates a polygon as an object literal, they then call $.geo.bbox on it, then the function ends. We will have a cache of the bbox, but most importantly the cache will reference the original polygon so the browser cannot remove it from memory. I agree that this isn't a great situation. However, the performance benefit gained by the find method is hard to ignore. Also, this only becomes a problem when the developer calls bbox directly. Even though we call it during the find method (building up cache), they are all removed when the dev removes shapes from the map with the remove method. I also know I need to research more about how $.data works with objects. I may be wrong about the reference/memory leaks.

===point bbox cache===
Now that I know I should cache bbox as non-geodetic, I think I should revisit my jsperf regarding caching a point. Since there's going to be much more calculation involved in $.geo.bbox, I might want to cache points. However, I think I should only cache them if $.geo.proj is not null. When it's null, non-cached points will still be faster as per my original jsperf test.

===events===
The new shape event will need a new event type. Position event won't cover it but it's similar. I'm not 100% sure if I should merge them. The new event type will be a shape event.

==2011-08-24==
===utah===
While zooming in, Chrome skips zoom level 12. I wonder if that's a bug in the control. It is. It's a rounding error in _getTiledZoom. Using floor and * instead...fixed.

==2011-08-19==
===contains===
Contains is spatial ref agnostic and is called by distance.

== 2011-08-07 ==
=== bbox ===
I think I'm missing something from my bbox description.

=== append ===
I would like to say that devs can call append again on a shape and it will replace the existing one and clear the bbox cache. That might be a good compromise for bbox cache clearing because I don't want a method specifically for that. Maybe, I'm not sold on the word append replacing something that's already there. Does jQuery have a replace function?

SUGGESTION: geomap - append should allow re-append of existing shapes, replacing the old one and clearing the bbox cache

=== bbox ex ===
I'm writing an odd example and I already forget if fromGeodetic can take a single position. It can, according to my docs :)

=== from/to pos ===
I keep going back and forth about coordinate vs. position in terms of words. I almost thought of changing fromGeodeticPos to fromGeodeticCoord but they /are/ called positions in the spec so I'm going to leave it. Again, it's spoken words (of which I suppose I am now including API function names) and code, which is GeoJSON object properties and arguments. Still confusing, this will never be settled so I'm dropping it.

=== bbox cache ===
Oops, I wasn't namespacing my data. I thing it has to be geoBbox because the namespaced data attribute would be data-geo-bbox.

== 2011-08-06 ==
=== alpha 2.5 ===
I released a new version last week and it seems to work well. I'm happy with it. On to documenting the features of alpha3!

=== label ===
I'm going to add labels and I think I want a label argument to append, however I want both style and label to be optional. In other words, you can pass a shape and a label. The label argument will be a string of html or a jQuery collection of elements to append to a label div. The outer label div is controlled by geomap. It will have a class on it, geo-label, if devs find they need or want to control it that way, i.e., add plain text and control the label style using the class.

=== jQuery a plain ===
Is a jQuery collection a plain object? Not according to this fiddle: http://jsfiddle.net/ryanttb/4rHK5/

So, I will have two optional args: style and label. Style has to be a plain object. Label can be a string or jQuery object. I'll say style comes first but they can be in any order.

=== shape props ===
Even though I have args on append, I will eventually allow both style and label properties on the GeoJSON object. They're not standard but not illegal according to the spec.

=== stored label ===
For speed, I will have to build the label HTML during the call to append, whether or not I use the shapeLabel property on the map or the label supplied during append.

=== override ===
The label supplied to append will completely override the map's shapeLabel property.

=== centroid ===
While I would like a LineString's centroid to be a point along the line so I can using it for labeling, that's not the accepted definition of a centroid of a line. According to JTS, it's calculated like a polygon, except when there is a polygon as part of a GeometryCollection. In which case lines and points are ignored when calculating centroid.

=== line label ===
Checking to see if JTS has an official point-along-line function that I can add w/o creating my own name. It doesn't seem to. I just decided to not label on the centroid for lines but on the "center point" of the line. As you add more points, the label will move further along the line.

=== envelope & bbox ===
So, OGC simple features doesn't seem to define an Envelope class. The Envelope function is defined to return a Polygon, eww!

=== ogc text align ===
They do define text alignment options called HorizontalAlignment: start, center and end. Might be useful later for text label options.

=== $.geo & proj ===
Internally, I need to call the geometry ops in $.geo and I will already have a projected bbox or geometry object. I need a way to tell methods such as $.geo.expandBy to not call $.geo.proj.fromGeodetic even if $.geo.proj is not null. I think for now I will have an internal (and undocumented save for here) argument at the end called ignoreProj. If truthy, it will not call fromGeodetic. A false value or undefined will call fromGeodetic if $.geo.proj is not null.

The documentation will always say fromGeodetic is called if $.geo.proj is not null.

SUGGESTION: Add an internal ignoreProj argument to $.geo geometry functions.

=== scaleBy ===
I haven't used it yet buy my original port of the scaleBy function was wrong. I was calling expandBy which would make scaleBy(bbox, 1) actually increase the size of the bbox, however, scaleBy(bbox, 1) shouldn't change the size at all. Also, expandBy was wrong basing itself on center instead of just modifying the min/max values directly.

=== geodetic bbox ===
I forgot that from/toGeodetic don't currently support bboxes. What am I doing already in geomap? Ah, right. I only needed it once (the bbox property) so I'm converting to two positions by hand. I think I should make a conveniance method in $.geo.proj. fromGeodeticBbox or something. I'm not going to make it public. Devs shouldn't have to call it, they can work in whichever projection/non-projected state they set $.geo up as and the public functions can handle it.

SUGGESTION: add private _from/_toGeodeticBbox methods

I did remove the, "if $.geo.proj is not null X first calls fromGeodetic..." shpeal that I had in all the bbox methods because it's not accurate. I won't call from/toGeodetic, I'll call a private method.

Actually, I should be able to detect a bbox vs any other geometry in the *Geodetic methods. It will be an array of 4 numbers, so .length == 4 and $.isArray(value[0]) == false. Maybe I'll put bbox conversion into them after all.

== 2011-07-30 ==
=== alpha 2.5 ===
It's been too long since I had a chance to work on this and I want to get an alpha 2.5 release out.

I need to push this back in an change my current branch name. I think it's alpha3 at the moment.

=== jsperf ===
I wrote a perf for point & linestring bbox cache testing. The test makes me think jQuery.data doesn't do what I think it's doing. When I cache the bbox in a local var, it's very fast but when I cache with data, it's not.

* Here's the point test: http://jsperf.com/point-vs-bbox
* Here's the line test: http://jsperf.com/line-vs-bbox

It's always faster to test points by themselves, i.e., don't worry about checking for a cached the bbox.

=== branch ===
I was on master, so I pushed, then created & switched to alpha2-5.

=== opacity ===
When developing the heat map example, I remember running into an issue where I couldn't get the opaicty to look right between the border and center. Maybe I fixed it somewhere else because I can't seem to reproduce that.

I can still get it on the latest fiddle of the heat map. It's when the opacity is 1 and the strokeOpacity is 0, the stroke still shows up but it should be hidden.

I still can't recreate this on the shapeStyle test page :( Ah, but the twitter heat example has the issue.

Turns out I was or'ing the stroke/fillOpacity with regular opacity in _getGraphicStyle. That's not the right place to do anything with them, and never or.

=== service opacity ===
I'm going to pull in the service opacity method from AppGeo.Web as "opacity" on each service object, like refresh.

That's done. I haven't documented/implemented what happens if you don't pass a service id. It's required. I'm not sure what I want that to do yet.

=== visible ===
When starting to think about geomap.toggle, I realize I have a naming conflict so to speak. The service object has a boolean visible property while the shape style has a string visibility property. I think I want to change the service to match the shape style. I don't think there are any attributes in HTML that pertains to visibility so I'm going to match CSS even in the service object which is more internal and less graphical. That said, I don't want to start renaming things in alpha 2.5 so that'll wait until 3.

SUGGESTION: Rename service.visible to visibility having either "visible" or "hidden" values

=== service props ===
So, I noticed that when a service is created, I don't modify the service objects to fill all the supported properties. So, when toggle is called, there's potentially not an initial visible property set.

I think for now, alpha 2.5, I will have the toggle function assume that there could be an undefined service.visible. The refresh method does the same. Later, though I think I might want to set defaults during _createServices.

=== proj ===
New projection code seems to work and is awesomely 150 lines shorter!

=== resize ===
I'm going to hook into the window resize event automatically but I will still need a resize method later in case the dev changes the div size/css.

SUGGESTION: Add a resize method to let geomap know the div has changed size programatically

I'm not sure of the correct way to kill & remake graphics now that it's a jQuery UI widget. It appears that I can call distroy & re-create it.

Resize, is working though when getting smaller, there is a space for the scroll bars. I don't remember having that issue with the internal AppGeo.Web control. That is an issue to tackle after alpha 2.5.

=== dbl tap ===
What is a thumb? On touch devices, and other soft-dblclick devices I don't take into account that the second click/tap might be too far from the first to count as a tap. There is no move event to cancel. I'm now calculating distance between the two based on _anchor (previous) and _current ( current :). This will need testing. I'm setting it at 10px for now, line 1480 of geomap.js as of this writing.

== 2011-07-19 ==
=== wkt ===
Wrote up some to-WKT code for our internal control today. WKT will also be supported by parseWKT and textify methods in $.geo.

SUGGESTION: Support WKT with $.geo.parseWKT (like JSON.parse or $.parseJSON) and $.geo.textify (like JSON.stringify).

=== centroid ===
Wrote up some centroid code for all but GeometryCollection as well for our internal control. Code similar to this will end up in $.geo.centroid.

== 2011-07-15 ==
=== presentation ===
My first real talk about $.geo went well, I think. Next up is FOSS4G in September and, possibly, jQuery Conference Boston in October & Harvard WWW in December.

=== alpha 2.5 ===
I think I want to push out a bug-fix release of the alpha 2 tech. I'll tag it as alpha 2.5 in github but overwrite the alpha2 js file on host. Well, rename the old one as alpha2.0 in case people find a bug in the new one.

I need to write down exactly what to do for alpha 2.5.

=== shape images ===
People really want images on shapes, particularly points. I'm removing this feature from my TO DO list:
* geomap - Document and implement passing a function to shapeStyle and append that returns a geomap style object based on feature or geometry properties
because I have a much better plan that involves the label div. It will be a normal div and have a class. Each will have relative position and designers can manipulate it however they want.

== 2011-07-12 ==
=== fiddles ===
Some fiddles for my demo on Wednesday:

# show a map:
#* http://jsfiddle.net/ryanttb/A6avG/
# show a map & zoom to boston
#* http://jsfiddle.net/ryanttb/2qBgw/
# show a map & zoom to geolocation
#* http://jsfiddle.net/ryanttb/Pre4k/
# add a location search
#* http://jsfiddle.net/ryanttb/3LpqG/
# add a twitter search: rpp=100
#* http://jsfiddle.net/ryanttb/79zTk/
# use map center as geocode, radius=(pixelSize * width/2 ) / 1000
#* http://jsfiddle.net/ryanttb/2PCUu/
# change style to heat map (16x16 size 8 border-radius)
#* http://jsfiddle.net/ryanttb/PUeRc/
# update on bboxchange
#* http://jsfiddle.net/ryanttb/8LQLW/
# show tweets in popup
#* http://jsfiddle.net/ryanttb/y2gTh/

== 2011-07-07 ==
=== bbox ===
I added bbox caching! I even check to see if the GeoJSON object has a bbox property, which is legal. There's no way to update the bbox but that'll come later.

=== distance ===
I almost tried to have distance support taking in a Feature but that opens a whole can of worms. I'm going to fix find to only send base geometry types to distance.

DOCUMENT: geometry methods will only take base geometry types (Point, LineString, Polygon & Multi*) or coordinate arrays

I had some weird comment on this method, it should be documented to only take base types, as I just said.

=== form input ===
I was talking to Chris last night about what geomap does that others don't and he reminded my about the idea I had of keeping a hidden input of the shapes as WKT. This would mean that I had to have a property on geomap for the map's name and also definitely change the service object to use name instead of id for when I add service-level shapes. WKT becomes a problem though when they've added features. I suppose I would dig into the features and only pull the geometry.

=== json ===
It's been a while since alpha 2. I'm working on a demo that draws the US state boundaries as graphics.

== 2011-06-30 ==
=== min ===
Srsly? I wasn't using minified jQuery in my examples? Wow.

== 2011-06-29 ==
=== alpha2 ===
Released alpha 2. I don't think anyone's really using it yet though.

== 2011-06-28 ==
=== on services ===
I think it would be nice to deep extend service objects that come in via the services property if a service with the given id already exists in _currentServices. This way, you could set the initial opacity of OSM by simply sending {services: [{id: "OSM", opacity: .8}]} during init.

SUGGESTION: deep extend existing service objects when services property is set

=== on opacity ===
I was beginning to try to throw the opacity & toggle methods into alpha2 but setting the services property is too flickery. I want to do it more like the old widget but that will require adding opacity and toggle methods into the services types. That will have to wait. It will be much faster to call the opacity/toggle methods on geomap than to set the services property each time. I will have to document that.

SUGGESTION: require opacity and toggle functions in the service type objects

== 2011-06-27 ==
=== on events ===
I almost forgot that I don't want bboxchange to fire when the developer changes a property in code. Unlike jQuery UI, my events trigger only when the user does something.

=== on alpha 2 ===
I'm trying to put this together.

== 2011-06-24 ==

=== on shape methods ===
I'm almost done. I need to finish empty and then I have what I wanted for an alpha 2 release!

=== on Point vs. coordinate ===
I think I'm going to settle on using Point objects everywhere except the projection functions. Which means I need to change find to accept a Point instead of an array. This should work out because the position events already send GeoJSON objects instead of position arrays.

=== on geometry ===
contains doesn't care about projections. Lon/lat values do not need to be projected.

I got done some of the geometry functions in $.geo but I'm leaving them private for now until I have a chance to document them and fully implement them.

=== on proj ===
Finished changing the $.geo.proj docs to explain that it will convert any GeoJSON coordinates array. I think I will also change the requirements to implement other projections by having the developer only have to override single position conversion functions (instead of worrying about the dimentionality of the passed array). Done.

=== on find ===
Now that proj is more powerful, I think I can handle find.

== 2011-06-18 ==
Accidentally coded append differently than how I documented. Will fix the code. Documentation FTW!

I can't decide if the geometry functions in $.geo should only accept the base geometry types or not. Initially they will not. I don't want to even think about getting into $.geo.distance(multiPoint, geometryCollection).

$.proj should go up to a three dimensional array to handle the coordinates in a Polygon. Go big or go home, I'm going to support four dimensional arrays so that I can get MultiPolygons as well. That will handle all of the GeoJSON types that have the coordinates property. If you have a GeometryCollection (geometries property), a Feature (geometry property) or a FeatureCollection (features property), then you're on your own.

I may change every mention of "web mercator" to "spherical mercator" to be more specific.

== 2011-06-17 ==
Attempting to change drawPoint from ovals to rounded rectangles. Shortcutting to drawArc if the width/height/borderRadius are the same.

Since I plan to make geographics public at some point, I thought I might make the drawPoint/Line/Polygon functions take actual GeoJSON shapes but I think that might conflict with some functionality internal to the geomap during digitization...I'll have to revisit this.

I seriously need to settle on the word "position" in my code when referring to an array containing an x/y. I use coordinate a bunch because that's what I used in the old project. Oh, but the property name of the GeoJSON object is coordinates. Heh, this is so confusing :) Ok, as I have been doing: coordinates in code, position in documentation.

I'm using cowboy's safeParse but can't tell what it's guarding against. I thought it would always give me a number but that's not the case. Guard against NaN or undefined?

Should drawing a bbox ignore borderRadius? I haven't decided.

You can fill and then stroke the same path, just sayin'.

Point graphics now draw as rounded rectangles. There's weirdness if your sizes are a little off though. I should probably start clamping values to each other like width & height to borderRadius. Yeah, if either is smaller than borderRadius the drawing gets weird. Maybe I should clamp borderRadius instead. Probably. Yeah, have to clamp borderRadius to min(width, height)/2.

I don't think you can disable fill by setting style.fill to "", but you should be allowed. It shouldn't be required to set fillOpacity to 0.

I just dropped a couple loops out of my graphic drawing in geographics. Should help a bit :)

== 2011-06-12 ==
I'm finally pushing the renaming changes to the main project.

=== On examples ===
I talked to Boaz at Bocoup the other day. He suggested cleaning up the examples. I already had this in mind but I should probably do it sooner rather than later. Especially the simplest example. It will look nicer if I cut the div down to 256x256 to match the initial tile I think (done, it already feels better). I do need to keep the examples specific and don't want to add any HTML or JavaScript to them that does not directly relate to the feature I'm testing in the example.

He also suggested unit tests and an API audit, both of which are great ideas and much needed by $.geo.

=== On ovals ===
Peter and I discussed how points are drawn and what width and height mean in geomap styles. We both agree that ovals are not very useful or used constructs in GIS and it would be better to have rounded rectangles. Therefore, I am dropping ovals and intead supporting a borderRadius property. Circles are still possible as long as your width, height and border radius are all the same, you will have a circle. This will be the default.

=== On double-click zoom ===
Peter and I both agree that double-click zoom should operate similar to mouse-wheel zoom in that the bbox should scale according to the placement of the mouse cursor during double-click instead of completely re-centering. You will notice that mouse-wheel feels right and double-click can be confusing.

SUGGESTION: Double-click zoom should scale according to cursor location instead of re-centering

=== On position events ===
I cannot decide if I should officially make the geo argument passed to the position events (move, click, dblclick) a true GeoJSON Point object. The only difference would be the presense of a type property set to "Point". However, the extra pixels property that I have on the geo argument is not part of GeoJSON and will remain in memory. Also, if a developer pushes the new object to a database they are storing extra information that they don't need and will be useless later.

Is the pixels property even that useful? The dev can call geomap.toPixels if they need it. I added the pixels property just because I had the pixels lying around in the internal handling of the event. I think I might just not pass them. It would be more useful to a developer I think to have a true GeoJSON Point object that they can send to geomap.append or a database without worrying about having extra useless data stored with it.

SUGGESTION: Remove the pixels property from position events and add the type property to make the event argument a true GeoJSON Point

I just updated the docs and changed the implementation. I already like this a lot better and am now thinking that the bbox event type could actually send a true GeoJSON Polygon with the bbox property set. That would be totally within the GeoJSON spec and might be useful. That's a bit of extra code on the widget's side though so for now I'm going to leave it as is. I can add that feature later since the current implementation (an object with just a bbox property) is already partially in a true Polygon's spec.

FUTURE SUGGESTION: Send a true GeoJSON Polygon object as the geo argument of bbox events

=== On returning jQuery collections ===
I need to better design the return values of the shape methods other than find & shapeStyle. Should append, remove and emtpy return the jQuery object of the map elements that the call originated from? Probably.

I just tested and yes, as long as you don't issue a return statement inside a jQuery UI widget method, jQuery UI will return the original jQuery collection for you.

== 2011-06-10 ==

=== On geographics ===
I am going to leave drawArc in the graphics widget. The drawPoint method will draw our default point shape (rounded rectangle) but, in the future, when custom drawing is in, a developer can use the drawArc if they want.

=== On proj ===
Peter has updated web mercator <=> geodetic code for me to drop into $.geo.proj.

== 2011-06-06 ==

=== On renaming shape functions ===
Renamed the shape functions. That was annoying but I'm glad I only had addShape implemented.

=== On jQuery UI widgets ===
The widget factory does hide methods that start _ from being called. So much for renaming drawArc to _drawArc and still calling it from geomap.

DEPRECATED SUGGESTION: Turn geographics into a NON-jQuery UI plugin

Did I totally get the scoping wrong for the jQuery UI widget? I have local vars in my initial plugin closure. Will they conflict if there are more than one map?

SUGGESTION: Verify that vars local to initial closure do not conflict when multiple maps are placed

== 2011-06-04 ==

=== drawArc ===
I just realized that by dropping geographics.drawArc in favor of drawPoint I am losing the ability to draw the circles I need for digitization modes. I wonder if, before I turn DrawPoint into a box-like function, that I should copy it to _drawArc. Will jQueryUI.widget let me call it from geomap?

=== shapes ===
Chris and I were talking about merging append (previously addshape) and find into one call: shapes. If you pass a GeoJSON object or array of, it will add them. Otherwise, it will find them. Thinking about this today, I don't quite think that's the way to go. I mostly feel that calling geomap functions to manipulate shapes is closer to adding elements to a jQuery collection. In other words, to call the geomap functions you must have already wrapped an element with jQuery, $("#map").geomap("funcName"). When you wrap elements with jQuery normally, you have to call append, find, etc. Geomap will work the same with. Of course, I do still want the syntactic sugar later: $("#map").append(geoJsonObj);

== 2011-06-02 ==
Who needs a blog. I feel like the best place to keep a developer journal is in the project itself so here we go.

=== On addShape's style argument ===
I showed Peter the shapeStyle demo. He expected that the shape-specific style applied via addShape would only override properties set during addShape. Further manipulation of the base shapeStyle would cascade to the shapes for any properties not explictily set. You know, like CSS. This is obviously the correct way to go and I already forget what made me code it the other way last night. Likely that I was coding at 2am and thought that if a user was passing a style to addShape they would want ALL style properties set in stone for that shape. That is not the right idea. If they want all properties set in stone, they can override all properties in the style object sent to addShape.

I changed the implementation before leaving work.

=== On storing & modifying style ===
My initial implementation drawing shapes in $.geo is very similar to how I did it with our internal control. I also showed Chris the shapeStyle demo and explained how you can add a style that's different from the base style on the map. He suggested that there be a way to change the style of an already added shape. I figured that I could make addShape update existing geometries instead of adding a new one but the syntax felt wrong. An updateShape method would work and could pass right through to addShape internally.

He also suggested allowing access to the internal GeoJSON->style map (as a return value for addShape) so they can maybe change the existing styles that way. However, something doesn't feel correctly designed about that.

We discussed attaching the style to the GeoJSON object. I already had supporting that in mind. If the user happens to have put a style property on the GeoJSON object before passing it to addShape, I would use that when drawing. A style passed to addShape would override that. The cascade would be: base style => GeoJSON object style => addShape style. A developer can keep the style property on the object even when it's stored, such as in GeoCouch, something that Guido wants a lot.

That said, I know I'm going about this wrong. As I said, my initial implementation feels too much like the old one and I want to do something much slicker in the jQuery world. On my walk home, I realized that since I am only storing a reference to the GeoJSON object and the user supplied style I can probably connect the style object to the GeoJSON object using jQuery's data method.

I wasn't sure if targeting a plain object is allowed in jQuery. I know it's possible but that doesn't mean I should. I remember IRC talk about it but forget the outcome. Info on ticket 8108 (http://bugs.jquery.com/ticket/8108) reveals that the DataLink plugin does this so I'm going to assume it's ok.

This little fiddle shows that the data properties don't show up with stringify http://jsfiddle.net/ryanttb/PetpJ/ but I'm going to do more research to see if it changes the object in a way devs will notice.

The data method doesn't natively support namespacing. I could do it myself using a period but I would like to follow what jQuery Mobile is doing with their data attribute stuff. They use data-jm-role which I believe equates to the call .data("jmRole") but I need to check up on that as well. So if I were to do data-geo-style, that would be .data("geoStyle"). I can live with that.

SUGGESTION: Store $.geo styles via $(geoJsonObj).data("geoStyle", style)

=== On shape functions ===
Again, the shape functions feel very old and were grabbed from my internal control. Tonight I was thinking about a new way to do this and it involves being able to wrap GeoJSON objects with jQuery collections and intercept $.fn calls such as .css. Also, non-jQuery UI functions can be added to the geomap widget's div to replace the old addShape method.

For example: $("#map").geomap("addShape", geoJson) could be $("#map").append(geoJson).

How would I add shapes to specific services in the future? $("#map [data-geo-service='OSM']").append(geoJson) maybe.

This might be going too far. Perhaps the old way is fine but use newer names (without the Shape suffix): $("#map").geomap("append", geoJsonObj), $("#map").geomap("append", "OSM", geoJsonObj), $("#map").geomap("remove", geoJsonObj) and $("#map").geomap("empty").

SUGGESTION: Rename the shape manipulation methods

The methods also need to take arrays of GeoJSON objects as returned by databases and jQuery collections of GeoJSON objects as possibly returned by the find method.

SUGGESTION: Shape manipulation methods should handle arrays

Looking back at the above code, I feel like maybe if I really can get the selector-based way to work, e.g., intercept the append call on the geomap widget, I could target the services using a class. They are divs inside the map, I should be able to trap them:

$("#map .OSM").append(geoJsonObj);

That does look really nice.

SUGGESTION: (future) Trap existing jQuery calls: append, remove and emtpy, on both the widget element and the service elements as syntactic sugar, forward them to geomap calls

However, using the class selector feels wrong. Especially if I'm telling them to use the id property when creating the service objects. I could switch it to name when creating the service objects, then:

$("#map [name='OSM']").append(geoJsonObj);

I need to find out if any of this is possible as soon as possible. It's still shorter than calling geomap. I would have to warn users to make sure the space is there, this needs to be a descendant selector.

SUGGESTION: Use name instead of id in the service objects.

=== On finding shapes ===
So you can append and remove shapes. Fine. But I also want a better way to search for shapes. Chris and I mulled over a selector-based way. I think I still want the simplicity of $("#map").geomap("find", position, pixelTol). That will cover a lot of use cases, users click maps a lot.

However, there should be other ways to get at your shapes in a UI widget way:
$("#map").geomap("find", [-67, 43], 8); // find all shapes within 8px of the map position (special case)
$("#map").geomap("find", "[type='Point']"); // Finds all points
$("#map").geomap("find", "[name='OSM'] *"); // all shapes in the OSM service (future)
$("#map").geomap("find", ":intersects(wkt(POINT(-67 43)))"); // Advanced spatial filter, OGC selector names (way future)

Here's how they would look with the future jQuery syntactic sugar:
$("#map").find([-67, 43], 8); // find all shapes within 8px of the map position (special case)
$("#map").find("[type='Point']"); // Finds all points
$("#map [name='OSM']").find(); // all shapes in the OSM service (future)
$("#map").find(":intersects(wkt(POINT(-67 43)))"); // Advanced spatial filter, OGC selector names (way future)