libs/js/jquery-geo-1.0a4/docs/geomap/append.html

   1 <!doctype html>
   2
   3 <html lang="en" class="no-js">
   4 <head>
   5   <meta charset="utf-8">
   6
   7   <title>append | geomap</title>
   8   <meta name="description" content="geomap append method">
   9   <meta name="author" content="Ryan Westphal">
  10
  11   <meta name="viewport" content="width=device-width, initial-scale=1.0">
  12
  13   <link rel="stylesheet" href="../css/style.css?v=2">
  14   <link rel="stylesheet" href="http://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.css" />
  15 </head>
  16
  17 <body>
  18
  19   <div id="append" data-role="page">
  20     <div data-role="header" data-theme="e">
  21       <h1>append</h1>
  22     </div>
  23
  24     <div data-role="content">
  25       <table>
  26         <tr>
  27           <th>return type</th>
  28           <td>jQuery collection</td>
  29         </tr>
  30         <tr>
  31           <th>syntax</th>
  32           <td>.geomap( &quot;append&quot; <!--[ , String serviceId ]--> , Object shape ( <a href="http://geojson.org/geojson-spec.html" rel="external">GeoJSON object</a> ) [ , Object style ( geomap style ) ] [ , String label ] [ , Boolean refresh ] )</td>
  33         </tr>
  34         <tr>
  35           <th>usage</th>
  36           <td><pre><code>$(<i>map or service selector</i>).geomap( &quot;append&quot;, { type: &quot;Point&quot;, coordinates: [ -71, 40 ] } )
  37
  38 $(<i>map or service selector</i>).geomap( &quot;append&quot;, { type: &quot;Point&quot;, coordinates: [ -71, 40 ] }, false )
  39
  40 $(<i>map or service selector</i>).geomap( &quot;append&quot;, { type: &quot;Point&quot;, coordinates: [ -71, 40 ] }, { stroke: &quot;#11117f&quot;, strokeWidth: &quot;3px&quot; } )
  41
  42 $(<i>map or service selector</i>).geomap( &quot;append&quot;, { type: &quot;Point&quot;, coordinates: [ -71, 40 ] }, { stroke: &quot;#11117f&quot;, strokeWidth: &quot;3px&quot; }, false )
  43
  44 $(<i>map or service selector</i>).geomap( &quot;append&quot;, { type: &quot;Point&quot;, coordinates: [ -71, 40 ] }, &quot;My Point&quot; )
  45
  46 $(<i>map or service selector</i>).geomap( &quot;append&quot;, { type: &quot;Point&quot;, coordinates: [ -71, 40 ] }, &quot;My Point&quot;, false )
  47
  48 $(<i>map or service selector</i>).geomap( &quot;append&quot;, { type: &quot;Point&quot;, coordinates: [ -71, 40 ] }, { color: &quot;#00f&quot; }, &quot;Blue Point&quot; )
  49
  50 $(<i>map or service selector</i>).geomap( &quot;append&quot;, { type: &quot;Point&quot;, coordinates: [ -71, 40 ] }, { color: &quot;#00f&quot; }, '&lt;span style=&quot;color: #44f;&quot;&gt;Blue Point&lt;/span&gt;', false )</code></pre></td>
  51         </tr>
  52       </table>
  53       <p>The append method adds a shape to the map. In this documentation the word shape means a GeoJSON geometry object, GeoJSON feature or GeoJSON feature collection. Each feature in a FeatureCollection's features property is added as a separate shape whereas the other collection geometry types, e.g., MultiPoint, are added as a single shape. This is important distinction when considering the find method in that find can potentially return only one shape of a FeatureCollection but will return all shapes in a MultiPoint (as a reference to the original MultiPoint object supplied to append) even if only one intersects the find position.</p>
  54       <p>The geomap widget maintains a reference to your shape. It will not change the object in any way. You can use the same object in calls to remove in order to remove the shape from the map at any time.</p>
  55       <p>The jQuery UI widget factory returns the original jQuery collection to maintain call chaining.</p>
  56       <!--<p>geomap draws shapes ordered by geometry type and then by order of addition. It draws Polygon shapes first followed by LineString and finally Point shapes. </p>-->
  57       <h2>styling</h2>
  58
  59       <p>The optional style argument modifies how geomap draws the specific geometry or feature you are adding. Properties supplied in this style will override ones of the same name in geomap&#39;s base shapeStyle. Properties not referenced are inheritied from the base style and can change with future changes to the shapeStyle option. Please see the shapeStyle method documentation for information about what properties are valid for this object.</p>
  60
  61       <h2>labeling</h2>
  62
  63       <p>The optional label argument will display a label near the shape. Labels are a powerful way to add text, pixel-based graphics, or other HTML and CSS effects to the map. The label string can be any text or HTML. For example, consider the following:</p>
  64
  65       <ul>
  66         <li>
  67           <span>you append a Point shape setting its style to have zero for width and height:</span>
  68           <pre><code>{ width: &quot;0px&quot;, height: &quot;0px&quot; }</code></pre>
  69         </li>
  70
  71         <li>
  72           <span>you also supply a label of nothing more than a div element with a class:</span>
  73           <pre><code>'&lt;div class=&quot;marker&quot;&gt;&lt;/div&gt;'</code></pre>
  74         </li>
  75
  76         <li>
  77           <span>in a CSS style sheet, you give the marker class a width, height, background image and negative relative position:</span>
  78           <pre><code>.marker
  79 {
  80   width: 8px;
  81   height: 8px;
  82   background: url(../img/marker.png);
  83   position: relative;
  84   left: -4px;
  85   top: -4px;
  86 }</pre></code>
  87         </li>
  88       </ul>
  89
  90       <p>In the above example, marker.png will be centered on every point added with a similar label. The regular shape style will not show because the point style has no size.</p>
  91
  92       <p>For Point shapes, the top-left of the label is positioned at the Point's only coordinate. For LineString shapes, the label is usually positioned 50% along the shape but will be forced into view if its usual position is out of the map's current bbox. For Polygon shapes, the label is usually positioned at the centroid but will be forced into view if its usual position is out of the map's current bbox. All other non-basic shape types use the shape's centroid.</p>
  93
  94       <p>The geomap widget uses a div to position the labels. The div exists inside a container for the service. The div has the CSS class: geo-label. You can use this design to apply regular CSS style to all labels or all labels within a service. The following snippets show examples of using this, assuming the main map div has the id &quot;map&quot; and the default map service (which has the CSS class &quot;osm&quot;) has not been changed.</p>
  95
  96       <h3>JavaScript</h3>
  97
  98       <pre><code><span class="comment">/* add a point to the map itself */</span>
  99 $( &quot;#map&quot; ).geomap( &quot;append&quot;, { type: &quot;Point&quot;, coordinates: [ -71, 40 ] }, &quot;map point&quot; );
 100
 101 <span class="comment">/* add a point to the default map service */</span>
 102 $( &quot;#map .osm&quot; ).geomap( &quot;append&quot;, { type: &quot;Point&quot;, coordinates: [ -70, 40 ] }, &quot;service point&quot; );
 103 </code></pre>
 104
 105       <h3>CSS</h3>
 106
 107       <pre><code><span class="comment">/* turn the color of all labels blue */</span>
 108 #map .geo-label { color: blue; }
 109
 110 <span class="comment">/* make labels on the default basemap service bold */</span>
 111 #map .osm .geo-label { font-weight: bold; }</code></pre>
 112
 113       <p>One caveat is that, to keep performance high, jQuery Geo will not create the .geo-label container if you do not at least pass an empty string as the label. So, if you want to do something similar to the marker example above, but using the already provided .geo-label div, you will need to pass an empty string as the label.</p>
 114
 115       <p>Each .geo-label div is absolutely positioned to the correct location in the map view. Please keep that in mind because changing the position, left or top CSS properties on the .geo-label class may affect your labels drastically.</p>
 116
 117       <h2>delaying refresh</h2>
 118
 119       <p>The optional refresh argument determines if geomap refreshes the map graphics after this call to append. It defaults to true. If you pass false, geomap will add the shape internally but not immediately redraw the graphics. The changes will display if the user moves the map or you call geomap's refresh method.</p>
 120       <h2>service-level shapes</h2>
 121       <p>The geomap widget allows you to append a shape to a specific service. You do this by targeting a service inside a map instead of the map itself for your call to geomap's append method. For example, the default map service has the CSS class: osm. We can append a shape to that service specifically by using jQuery to target the service:</p>
 122       <pre><code>$( &quot;#map .osm&quot; ).geomap( &quot;append&quot;, shape );</code></pre>
 123       <p>Some of the important advantages with this syntax are:</p>
 124       <ul>
 125         <li>you can show or hide shapes as you toggle a service because shapes attached to a service are only visible if the service is visible</li>
 126         <li>service-level shapes draw in the order of their service in the <a href="services.html">services option</a> which gives you finer control over how they look</li>
 127         <li>shapes on the map itself always draw above service-level shapes</li>
 128         <li>you can style shapes differently depending on their service using a service-level <a href="shapeStyle.html">shapeStyle option</a></li>
 129       </ul>
 130       <h2>duplicate shapes</h2>
 131       <p>You can add the same GeoJSON object to more than one service, which allows you to give the same object two different styles at the same time. To do this, call append twice with the same object. Once on one service (or the map itself) and a second time on a different service.</p>
 132       <p>You can also do this at the same time by using the comma selector in one call to append:</p>
 133       <pre><code><span class="comment">// set the basemap service's shapeStyle option to a white halo effect</span>
 134 $( &quot;#map .osm&quot; ).geomap( &quot;option&quot;, &quot;shapeStyle&quot;, { strokeWidth: &quot;8px&quot;, color: &quot;#dedede&quot; } );
 135
 136 <span class="comment">// append the shape to both the map widget and basemap service</span>
 137 $( &quot;#map,#map .osm&quot; ).geomap( &quot;append&quot;, shape );</code></pre>
 138       <h2>updating</h2>
 139       <p>If you attempt to add a shape to the map or a service where it already exists, the shape will remain but you will update (or remove) the shape's style or label.</p>
 140       <pre><code><span class="comment">// add the shape with a green color</span>
 141 $( &quot;#map&quot; ).append( shape, { color: &quot;green&quot; } );
 142
 143 <span class="comment">// change the color to blue (shape is the same object as before in this case)</span>
 144 $( &quot;#map&quot; ).append( shape, { color: &quot;blue&quot; } );</code></pre>
 145       <p>Changing the type of geometry, e.g., from Point to LineString, or coordinates of a shape you have appended is not recommended and geomap's behavior is currently undefined. If you wish to do either of these, you should first call remove on the original object and append on a new one.</p>
 146       <!--<p>The following odd example will move the first coordinate of any clicked LineString 10 meters to the left. Notice it first removes the shape, then updates the first coordinate and finally appends the new shape.</p>
 147       <pre><code>var map = $( &quot;#map&quot; ).geomap( {
 148   click: function(e, geo) {
 149     <span class="comment">// find any shapes within 4 pixels of the clicked point</span>
 150     var shapes = map.geomap(&quot;find&quot;, geo, 4);
 151     if (shapes.length &gt; 0 &amp;&amp; shapes[0].type == &quot;LineString&quot;) {
 152       map.geomap("remove", shapes[0]);
 153       <span class="comment">// move the first point in the line 10 meters to the left</span>
 154       <span class="comment">// you can edit the coordinates directly since you've removed the shape</span>
 155
 156       <span class="comment">// we use proj because we want to temporarily work in meters</span>
 157       var firstCoord = $.geo.proj.fromGeodetic(shapes[0].coordinates[0]);
 158       <span class="comment">// firstCoord[0] is the x axis</span>
 159       firstCoord[0] -= 10;
 160       <span class="comment">// we need to convert it back to geodetic (lon/lat)</span>
 161       shapes[0].coordinates[0] = $.geo.proj.toGeodetic(firstCoord);
 162       <span class="comment">// re-append the shape</span>
 163       map.geomap( &quot;append&quot;, shapes[0] );
 164     }
 165   }
 166 } );</code></pre>-->
 167
 168     </div>
 169   </div> <!-- end of #container -->
 170
 171   <script src="http://code.jquery.com/jquery-1.7.1.min.js"></script>
 172   <script src="http://code.jquerygeo.com/jquery.geo-1.0a4.min.js"></script>
 173   <script src="../js/script.js"></script>
 174   <script src="http://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.js"></script>
 175 </body>
 176 </html>
 177