Permalink
Browse files

Renamed the shape methods to align better with jQuery naming conventi…

…ons. Added a logo demo and shapeStyle example. Started a developer journal.
  • Loading branch information...
1 parent 6973325 commit 659fbd3ec89f70fb0231d52603e4932a712a29ff Ryan committed Jun 12, 2011
View
28 README
@@ -6,31 +6,23 @@ After years of internal development, we are pleased to bring our JavaScript map
Documentation is hosted at http://host.appgeo.com/libs/geo/test/
-== TO DO ==
-
-* geomap - Document and implement the refresh method
-* docs/internal - Document how geomap draws shapes
-* geomap - Auto-handle window resize events
-* geomap - [BUG] Mouse wheel on bad or missing tile doesn't zoom out on first rotate
-* geomap - Document and implement service-level shapes
-* geomap - Document and implement passing a function to shapeStyle and addShape that returns a geomap style object based on feature or geometry properties
-* geomap - Document and implement findShape's callback syntax
-* graphics - See Modernizr for comment on BB Storm & canvas detection
-* geographics - Document graphics widget
-
== CHANGELOG ==
=== Version alpha2 ===
* geomap - Support dynamic map services
* geomap - [BUG] geomap causes a script error if jQuery UI is already included
-* geomap - Document shape methods
-* geomap - [BUG] Soft double-click does not work
+* docs - Document shape methods
+* geomap - [BUG] Port of soft double-click does not work
* geomap - [BUG] Cannot see dev-supplied inner content if not set to rel/abs position
* geomap - Add mobile test page
* geographics - Port graphic code from internal control
* geomap - Implement non-service addShape method
* graphics - drawArc should use style's width and height and only take center as an argument
-
-=== Version alpha1 ===
-* Create interactive map widget
-* Support tiled map services
+* graphics - Allow ovals for points
+* geomap - Document and implement the public refresh method
+* docs - Rename findShape to find, addShape to append, removeShape to remove and clearShapes to empty
+
+=== Version alpha1 (2011-05-09) ===
+* docs - Document a new interface to our internal map control
+* geomap - Port interactive map widget base to jQuery UI widget factory
+* geomap - Support tiled map services
View
@@ -0,0 +1,122 @@
+== TO DO ==
+
+* geomap - Port initial find functionality (position + pixel buffer)
+* geomap - Allow append to take an array of geometry objects, each one should be a new shape
+* geographics - Forgo ovals for borderRadius support and rectangles, rename drawArc to drawPoint
+* geo.proj - Update bundled projection code
+* docs/internal - Document how geomap draws shapes
+* docs/geomap - Use name instead of id for service objects
+* widgets - Verify that vars local to initial closure do not conflict when multiple maps are placed
+* geomap - Auto-handle window resize events
+* geomap - [BUG] Mouse wheel on bad or missing tile doesn't zoom out on first rotate
+* geomap - Document and implement service-level shapes
+* geomap - Document and implement passing a function to shapeStyle and append that returns a geomap style object based on feature or geometry properties
+* geomap - Document and implement find's callback syntax
+* 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
+
+== 2011-06-12 ==
+I'm finally pushing the renaming changes to the main project.
+
+== 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)
+
View
@@ -74,6 +74,7 @@ h1, h2, h3, h4, h5, h6 { font-weight: bold; }
Author: Ryan Westphal
*/
+h1 img { width: 24px; height: 24px; margin-right: 4px; vertical-align: middle; }
div>h2 { font-size: 1.1em; margin: .5em 0; }
p { margin: .5em 0; }
th { text-align: right; padding: .5em 1em .5em 0; }
@@ -85,8 +86,6 @@ h4 { font-style: italic; font-weight: normal; }
.objectProperties td { padding: .25em .5em; }
.objectProperties tr:nth-child(2n+1) { background: #bbb; }
-
-
.ir { display: block; text-indent: -999em; overflow: hidden; background-repeat: no-repeat; text-align: left; direction: ltr; }
.hidden { display: none; visibility: hidden; }
.visuallyhidden { border: 0; clip: rect(0 0 0 0); height: 1px; margin: -1px; overflow: hidden; padding: 0; position: absolute; width: 1px; }
@@ -1,12 +1,9 @@
<!DOCTYPE html>
<html>
<head>
- <title>addShape test</title>
+ <title>append test</title>
+ <link rel="stylesheet" type="text/css" href="css/style.css" />
<style type="text/css">
- body
- {
- font-family: Calibri,Arial;
- }
label
{
display: block;
@@ -23,18 +20,20 @@
</head>
<body>
<div>
+ <a href="../" class="docLink">&lt; docs</a>
<h1>
- addShape test</h1>
+ append test</h1>
+ <p>
+ This page tests geomap's append method and some style options.</p>
<p>
- This page tests geomap's addShape method and some style options.</p>
+ A geomap widget is initialized to the continental US and a point is placed in Massachusetts. A line extends from MA to South Jersey where a triangle covers an area. For points, geomap draws a pixel-based oval around the map coordinate. Since the size of the oval is based on pixels, it will be the same size at all scales. The pixel length of lines and size of polygons changes at different scales because each point that makes up the shapes is locked at specific map coordinates. The stroke width for all shapes will be the same number of pixels at all scales.</p>
<p>
- A geomap widget is initialized to the continental US and a point is placed in Massachusetts. A line extends from MA to South Jersey where a triangle covers an area.</p>
- <p>All the geometry is stored in a single GeometryCollection. We first draw the entire collection with a broad stroked, white style to create a halo effect behind the real shapes. This makes them a little easier to see on the map. Then we draw each individual shape again with color. The first two have the default style which is red. For the last one, we change the color to blue.</p>
+ All the geometry is stored in a single GeometryCollection. This example first draws the entire collection with a broad stroked, off-white style to create a halo effect behind the real shapes. This makes them a little easier to see on the map. Then we draw each individual shape again with color. The first two have the default style which is red. For the last one, we change the color to blue.</p>
<div id="map" style="float: left; width: 640px; height: 480px;">
</div>
<pre style="float: left;"><code>var map = $("#map").geomap({
- center: [-94, 37],
- zoom: 3
+ center: [-75, 40],
+ zoom: 5
});
var gcol = {
@@ -63,21 +62,21 @@
]
};
-map.geomap(&quot;addShape&quot;, gcol, { strokeWidth: &quot;8px&quot;, color: &quot;#dedede&quot; });
+map.geomap(&quot;append&quot;, gcol, { strokeWidth: &quot;8px&quot;, color: &quot;#dedede&quot; });
-map.geomap(&quot;addShape&quot;, gcol.geometries[0]);
+map.geomap(&quot;append&quot;, gcol.geometries[0]);
-map.geomap(&quot;addShape&quot;, gcol.geometries[1]);
+map.geomap(&quot;append&quot;, gcol.geometries[1]);
-map.geomap(&quot;addShape&quot;, gcol.geometries[2], { color: &quot;blue&quot; });</code></pre>
+map.geomap(&quot;append&quot;, gcol.geometries[2], { color: &quot;blue&quot; });</code></pre>
</div>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.1/jquery.js"></script>
<script src="http://host.appgeo.com/libs/geo/test/jquery-geo-test.min.js"></script>
<script>
$(function () {
var map = $("#map").geomap({
- center: [-94, 37],
- zoom: 3
+ center: [-75, 40],
+ zoom: 5
});
var gcol = {
@@ -106,14 +105,14 @@
]
};
- map.geomap("addShape", gcol, { strokeWidth: "8px", color: "#dedede" });
+ map.geomap("append", gcol, { strokeWidth: "8px", color: "#dedede" });
- map.geomap("addShape", gcol.geometries[0]);
+ map.geomap("append", gcol.geometries[0]);
- map.geomap("addShape", gcol.geometries[1]);
+ map.geomap("append", gcol.geometries[1]);
- map.geomap("addShape", gcol.geometries[2], { color: "#00d" });
- });
+ map.geomap("append", gcol.geometries[2], { color: "#00d" });
+ });
</script>
</body>
</html>
View
@@ -2,11 +2,8 @@
<html>
<head>
<title>bbox test</title>
+ <link rel="stylesheet" href="css/style.css?v=2">
<style type="text/css">
- body
- {
- font-family: Calibri,Arial;
- }
label
{
display: block;
@@ -32,6 +29,7 @@
</head>
<body>
<div>
+ <a href="../" class="docLink">&lt; docs</a>
<h1>
bbox test</h1>
<p>
@@ -2,11 +2,8 @@
<html>
<head>
<title>center/zoom test</title>
+ <link rel="stylesheet" href="css/style.css?v=2">
<style type="text/css">
- body
- {
- font-family: Calibri,Arial;
- }
label
{
display: block;
@@ -32,6 +29,7 @@
</head>
<body>
<div>
+ <a href="../" class="docLink">&lt; docs</a>
<h1>
center/zoom test</h1>
<p>
@@ -0,0 +1,14 @@
+body { font-family: Calibri,Arial; }
+
+.docLink
+{
+ background: url(../../images/$.geo-logo-small.png) right no-repeat;
+ color: #7f0000;
+ display: block;
+ float: right;
+ font-size: 24px;
+ font-weight: bold;
+ padding-right: 24px;
+ text-decoration: none;
+ text-transform: uppercase;
+}
@@ -2,6 +2,7 @@
<html>
<head>
<title>Events test</title>
+ <link rel="stylesheet" type="text/css" href="css/style.css" />
<style type="text/css">
th
{
@@ -17,6 +18,7 @@
</head>
<body>
<div>
+ <a href="../" class="docLink">&lt; docs</a>
<h1>
Events test</h1>
<div id="map" style="position: relative; width: 320px; height: 240px;">
Oops, something went wrong.

0 comments on commit 659fbd3

Please sign in to comment.