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

   1 <!doctype html>
   2
   3 <html lang="en" class="no-js">
   4 <head>
   5   <meta charset="utf-8">
   6
   7   <title>services | geomap</title>
   8   <meta name="description" content="geomap services option">
   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="services" data-role="page">
  20     <div data-role="header" data-theme="f">
  21       <h1>services</h1>
  22     </div>
  23
  24     <div data-role="content">
  25       <table>
  26         <tr>
  27           <th>type</th>
  28           <td>Array</td>
  29         </tr>
  30         <tr>
  31           <th>default</th>
  32         </tr>
  33         <tr>
  34           <td colspan=2><code><pre>[ {
  35   &quot;class&quot;: &quot;osm&quot;,
  36   type: &quot;tiled&quot;,
  37   src: function( view ) {
  38     return &quot;http://tile.openstreetmap.org/&quot; + view.zoom + &quot;/&quot; + view.tile.column + &quot;/&quot; + view.tile.row + &quot;.png&quot;;
  39   },
  40   attr: &quot;&amp;copy; OpenStreetMap &amp;amp; contributors, CC-BY-SA&quot;
  41 } ]</pre></code></td>
  42         </tr>
  43         <tr>
  44           <th>init</th>
  45         </tr>
  46         <tr>
  47           <td colspan=2><pre><code>$( <i>selector</i> ).geomap( { services: [ {
  48   &quot;class&quot;: &quot;osm&quot;,
  49   type: &quot;tiled&quot;,
  50   src: function( view ) {
  51     return &quot;http://tile.openstreetmap.org/&quot; + view.zoom + &quot;/&quot; + view.tile.column + &quot;/&quot; + view.tile.row + &quot;.png&quot;;
  52   },
  53   attr: &quot;&amp;copy; OpenStreetMap &amp;amp; contributors, CC-BY-SA&quot;,
  54   style: {
  55     visibility: &quot;visible&quot;,
  56     opacity: 1.0
  57   }
  58 } ] } );</code></pre></td>
  59         </tr>
  60         <tr>
  61           <th>get</th>
  62           <td><pre><code>var services = $( <i>selector</i> ).geomap( &quot;option&quot;, &quot;services&quot; );</code></pre></td>
  63         </tr>
  64         <tr>
  65           <th>set</th>
  66         </tr>
  67         <tr>
  68           <td colspan=2><pre><code>$( <i>selector</i> ).geomap( &quot;option&quot;, &quot;services&quot;, [ {
  69   id: &quot;mapquest-open&quot;,
  70   &quot;class&quot;: &quot;basemap&quot;,
  71   type: &quot;tiled&quot;,
  72   src: function( view ) {
  73     return &quot;http://otile&quot; + ((view.index % 4) + 1) + &quot;.mqcdn.com/tiles/1.0.0/osm/&quot; + view.zoom + &quot;/&quot; + view.tile.column + &quot;/&quot; + view.tile.row + &quot;.png&quot;;
  74   },
  75   attr: &quot;&lt;p&gt;Tiles Courtesy of &lt;a href='http://www.mapquest.com/' target='_blank'&gt;MapQuest&lt;/a&gt; &lt;img src='http://developer.mapquest.com/content/osm/mq_logo.png'&gt;&lt;/p&gt;&quot;
  76 } ] );</code></pre></td>
  77         </tr>
  78       </table>
  79
  80       <p>The services option is an array of service objects. The service objects are JavaScript objects that control how the geomap widget displays map images.</p>
  81
  82       <p>By default, geomap will display OpenStreetMap tiles. You can change all services at once by setting this option with an entirely new array of service objects. You can set a specific part of of a specific service by getting the current array, modifying, adding, or deleting one of the service objects and then re-setting the services option with the modified array.</p>
  83
  84       <pre><code><span class="comment">// get the current services array</span>
  85 var services = map.geomap( &quot;option&quot;, &quot;services&quot; );
  86
  87 <span class="comment">// add a service</span>
  88 services.push( {
  89   id: &quot;Ortho_MapQuest&quot;,
  90   type: &quot;tiled&quot;,
  91   src: function (view) {
  92     return &quot;http://oatile&quot; + ((view.index % 4) + 1) + &quot;.mqcdn.com/naip/&quot; + view.zoom + &quot;/&quot; + view.tile.column + &quot;/&quot; + view.tile.row + &quot;.png&quot;;
  93   },
  94   attr: &quot;&lt;p&gt;Tiles Courtesy of &lt;a href='http://www.mapquest.com/' target='_blank'&gt;MapQuest&lt;a&gt; &lt;img src='http://developer.mapquest.com/content/osm/mq_logo.png'&gt;&lt;p&gt;&quot;
  95 } );
  96
  97 <span class="comment">// re-set the services option</span>
  98 map.geomap( &quot;option&quot;, &quot;services&quot;, services );</code></pre>
  99
 100       <h2>service object</h2>
 101
 102       <p>A service object has six properties, two of which are required. The id and class properties are optional but at least one is recommended so you can target specific services with the toggle and opacity methods.</p>
 103       <h3>id</h3>
 104       <p>Each service can have an id that distinguishes it from other service objects in the array. The id is a string and must be follow the HTML element id naming conditions. If present, the id must be unique across all services in all maps as well as unique from any other HTML element on the page. The default service object of a geomap widget does not have an id.</p>
 105       <h3>class</h3>
 106       <p>Each service can have a class as well. The class is a string and must be follow the CSS class naming conditions. You can consider this as the class of images the service will supply and usually name it after the service, such as osm, mass-gis, etc. The default service object of a geomap widget has the class: osm.</p>
 107       <p>All services also get the class geo-service whether you supply a class to the service object or not. Therefore, the default service is both .osm (as part of its service object) and .geo-service (as added by the widget).</p>
 108       <p>Unfortunately, class is a reserved word in JavaScript. When you specify class in your service object, you must quote the word class. This is exactly how it's done in jQuery itself when applying attributes to an element based on an object. To quote the jQuery API:</p>
 109       <blockquote>The name &quot;class&quot; must be quoted since it is a JavaScript reserved word, and &quot;className&quot; cannot be used since it is not the correct attribute name.</blockquote>
 110       <h3>type</h3>
 111       <p>A service object has a type property which is either &quot;tiled&quot; or &quot;shingled&quot;. Tiled servies will get one image request per tile needed to fill a given view when the map refreshes. The tile request's bbox will only be the size of the given tile. Shingled services will get only one image request each time the map refreshes and the bbox will be the extent of the whole map view.</p>
 112       <h3>src</h3>
 113       <p>The src property of a service object can be one of the following three options:</p>
 114       <ul>
 115         <li>a function that accepts an object specifying information about the current image request which <b>returns a URL to an image</b> or null to indicate that no image is available or required</li>
 116         <li>a function that accepts an object specifying information about the current image request which <b>returns a jQuery Promise object</b> and, later, calls either resolve passing a URL to an image or reject to indicate that no image is available</li>
 117         <li>a template string that the geomap widget can use to build a URL itself</li>
 118       </ul>
 119       <p>For tiled services, the image is placed at the tile location specified. For shingled services, the image will fill the whole map view.</p>
 120       <p>If the browser's request of the image results in a 404 status the map will not show that tile or image.</p>
 121       <p>When src is a function, the argument to that function has the following properties:</p>
 122       <table>
 123         <tr>
 124           <th>bbox (Array)</th><td>A <a href="http://geojson.org/geojson-spec.html#bounding-boxes" rel="external">GeoJSON bounding box</a> of the current tile or image in map units. The map unit type (projected or geodetic) depends on how you last set the bbox or center options on the geomap widget.</td>
 125         </tr>
 126         <tr>
 127           <th>width (Number)</th><td>The width of the tile or image in pixels.</td>
 128         </tr>
 129         <tr>
 130           <th>height (Number)</th><td>The height of the tile or image in pixels.</td>
 131         </tr>
 132         <tr>
 133           <th>zoom (Number)</th><td>The current zoom level of the map during this request.</td>
 134         </tr>
 135         <tr>
 136           <th>tile (Object)</th><td>If the service is tiled, this object has column and row properties specifying the location of the tile of this request in the current zoom, otherwise it is null.</td>
 137         </tr>
 138         <tr>
 139           <th>index (Number)</th><td>A whole number which is usually incremented between requests that you can use to cycle image URLs to different index, e.g., if there are four servers hosting the same tile images named tile0, tile1, tile2 and tile3 you can target them in your src function with the string: &quot;tile&quot; + (view.index % 4).</td>
 140         </tr>
 141       </table>
 142       <p>You can use the properties of this argument to build and return a URL (or initiate an AJAX request and return a Promise).</p>
 143       <p>For more infomration about returning a jQuery Promise, please read the section on <a href="http://api.jquery.com/category/deferred-object/" rel="external">Deferred Objects</a> in the jQuery API documentation. It might useful to know that, as of jQuery 1.5, the <a href="http://api.jquery.com/jQuery.ajax/" rel="external">$.ajax method</a> returns a Promise object. If your ajax call returns a URL to an image, your src function can look something like this:</p>
 144       <pre><code>src: function ( view ) { return $.ajax( { ... } ); }</code></pre>
 145       <p>When src is a string, those same properties can be used in the template by surrounding each property with: {{=propertyName}}.</p>
 146       <p>The default value for src is a function because it is slightly faster than rendering a template. However, as an example, we can rewrite the default src function as a template string:</p>
 147       <pre><code>src: &quot;http://tile.openstreetmap.org/{{=zoom}}/{{=tile.column}}/{{=tile.row}}.png&quot;</code></pre>
 148       <p>A couple advantages of using a string are that it is more concise and, unlike a function, can be stored as JSON.</p>
 149       <p>You do not have to have template parameters in the string, so if you want a static map image, you can set src to a static URL.</p>
 150       <h3>attr</h3>
 151       <p>The attr property is optional. It stands for attribution and is a way to give credit to the source of your map imagery. It defaults to an empty string if not specified in a service object. When present, the map widget displays the HTML provided on the bottom-left corner of the map when the service is visible. Users can click links but cannot interact with all other text or images.</p>
 152       <h3>style</h3>
 153       <p>The style property is optional. It contains presentation options for the service.</p>
 154
 155       <p>The visibility property defaults to &quot;visible&quot;. It determines whether or not the map will show images from this service while refreshing. You can change the visibility of a service either by changing the visibility property of the service object to &quot;visible&quot; or &quot;hidden&quot; and then setting geomap's services option or by using the toggle method of the geomap widget. The latter is recommended because it is a lot faster and does not cause services to be recreated.</p>
 156
 157       <p>The opacity defaults to 1.0. It determines how transparent a service is when it is visible. Valid values are floating point numbers between 0 and 1 inclusive. Services with an opacity of 0 will not show on the map even if visible is true. You can change the opacity of a service either by changing the opacity property of the service object and then setting geomap's services option or by using the opacity method of the geomap widget. The latter is recommended because it is a lot faster and does not cause services to be recreated.</p>
 158     </div>
 159   </div> <!-- end of #container -->
 160
 161   <script src="http://code.jquery.com/jquery-1.7.1.min.js"></script>
 162   <script src="http://code.jquerygeo.com/jquery.geo-1.0a4.min.js"></script>
 163   <script src="../js/script.js"></script>
 164   <script src="http://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.js"></script>
 165 </body>
 166 </html>
 167