cdb

lib/assets/javascripts/cdb/doc/static_maps.md

@@ -0,0 +1,213 @@
+# Static Maps
+
+Static views of CARTO maps can be generated using the [Static Maps API](https://carto.com/docs/carto-engine/maps-api/static-maps-api/) within CARTO.js. The map's style, including the zoom and bounding box, follows from what was set in the `viz.json` file, but you can change the zoom, center, and size of your image with a few lines of code. You can also change your basemap Images can be placed in specified DOM elements on your page, or you can generate a URL for the image.
+
+## Quick Start
+
+The easiest way to generate an image is by using the following piece of code, which generates is replaced by an `img` tag once run in an HTML file:
+
+```javascript
+<script>
+var vizjson_url = 'https://documentation.carto.com/api/v2/viz/008b3ec6-02c3-11e4-b687-0edbca4b5057/viz.json';
+
+cartodb.Image(vizjson_url)
+  .size(600, 400)
+  .center([-3.4, 44.2])
+  .zoom(4)
+  .write({ class: "thumb", id: "AwesomeMap" });
+</script>
+```
+
+#### Result
+
+```html
+<img id="AwesomeMap" src="https://cartocdn-ashbu.global.ssl.fastly.net/documentation/api/v1/map/static/center/04430594691ff84a3fdac56259e5180b:1419270587670/4/-3.4/44.2/600/400.png" class="thumb">
+```
+
+### cartodb.Image(_layerSource[, options]_)
+
+#### Arguments
+
+Name |Description
+--- | ---
+layerSource | can be either a `viz.json` object or a [MapConfig object](https://carto.com/docs/carto-engine/maps-api/mapconfig#mapnik-layer-options).<br/><br/>**Note:** If defining an image through the MapConfig layer definition, you must set the `tiler_domain`, `tiler_port`, and `tiler_protocol`, as displayed in this [example](https://github.com/CartoDB/cartodb.js/blob/4ba5148638091fd2c194f48b2fa3ed6ac4ecdb23/examples/layer_definition.html). Otherwise the Static Image API tries to use your localhost to source the tiles and an error appears.
+
+options | 
+--- | ---
+&#124;_ basemap | change the basemap specified in the layer definition. Type: Object defining base map properties (see example below).
+&#124;_ no_cdn | Disable CDN usage. Type: Boolean. Default: `false` (use CDN)
+&#124;_ override_bbox | Override default of using the bounding box of the visualization. This is needed to use `Image.center` and `Image.zoom`. Type: Boolean. Default: `false` (use bounding box)
+
+#### Returns
+
+An `Image` object
+
+#### Example
+
+```javascript
+<script>
+var vizjson_url = 'https://documentation.carto.com/api/v2/viz/008b3ec6-02c3-11e4-b687-0edbca4b5057/viz.json';
+var basemap = {
+  type: "http",
+  options: {
+    urlTemplate: "http://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png",
+    subdomains: ["a", "b", "c"]
+  }
+};
+
+cartodb.Image(vizjson_url, {basemap: basemap})
+  .size(600, 400)
+  .center([0,0])
+  .write({ class: "thumb", id: "AwesomeMap" });
+</script>
+```
+
+---
+
+## cartodb.Image
+
+### Image.size(_width, height_)
+
+Sets the size of the image.
+
+#### Arguments
+
+Name |Description
+--- | ---
+width | the width of the resulting image in pixels
+height | the height of the resulting image in pixels
+
+#### Returns
+
+An `Image` object
+
+### Image.center(_latLng_)
+
+Sets the center of the map.
+
+#### Arguments
+
+Name |Description
+--- | ---
+latLng | an array of the latitude and longitude of the center of the map. Example: `[40.4378271, -3.6795367]`
+
+#### Returns
+
+An `Image` object
+
+### Image.zoom(_zoomLevel_)
+
+Sets the zoom level of the static map. Must be used with the option `override_bbox: true` if not using `Image.center` or `Image.bbox`.
+
+#### Arguments
+
+Name |Description
+--- | ---
+zoomLevel | the zoom of the resulting static map. `zoomLevel` must be an integer in the range [0,24].
+
+#### Returns
+
+An `Image` object
+
+### Image.bbox(_boundingBox_)
+
+If you set `bbox`, `center` and `zoom` will be overridden.
+
+#### Arguments
+
+Name |Description
+--- | ---
+boundingBox | an array of coordinates making up the bounding box for your map. `boundingBox` takes the form: `[sw_lat, sw_lon, ne_lat, ne_lon]`.
+
+#### Returns
+
+An `Image` object
+
+### Image.into(_HTMLImageElement_)
+
+Inserts the image into the HTML DOM element specified.
+
+#### Arguments
+
+Name |Description
+--- | ---
+HTMLImageElement | the DOM element where your image is to be located.
+
+#### Returns
+
+An `Image` object
+
+#### Example
+
+```javascript
+cartodb.Image(vizjson_url).into(document.getElementById('map_preview'))
+```
+
+### Image.write(_attributes_)
+
+Adds an `img` tag in the same place script is executed. It's possible to specify a class name (`class`) and/or an id attribute (`id`) for the resulting image:
+
+#### Arguments
+
+Name |Description
+--- | ---
+class | the DOM class applied to the resulting `img` tag.
+id | the DOM id applied to the resulting `img` tag.
+src | path to a temporary image that acts as a placeholder while the static map is retrieved.
+
+#### Returns
+
+An `Image` object
+
+#### Example
+
+```javascript
+<script>
+cartodb.Image(vizjson_url)
+  .size(600, 400)
+  .center([-3.4, 44.2])
+  .zoom(10)
+  .write({ class: "thumb", id: "ImageHeader", src: 'spinner.gif' });
+</script>
+```
+
+### Image.getUrl(_callback(err, url)_)
+
+Gets the URL for the image requested.
+
+#### Callback Arguments
+
+Name |Description
+--- | ---
+err | error associated with the image request, if any.
+url | URL of the generated image.
+
+#### Returns
+
+An `Image` object
+
+#### Example
+
+```javascript
+<script>
+cartodb.Image(vizjson_url)
+  .size(600, 400)
+  .getUrl(function(err, url) {
+    console.log('image url',url);
+  })
+</script>
+```
+
+### Image.format(_format_)
+
+Gets the URL for the image requested.
+
+#### Arguments
+
+Name |Description
+--- | ---
+format | image format of resulting image. One of `png` (default) or `jpg` (which have a quality of 85 dpi)
+
+#### Returns
+
+An `Image` object