293 lines
7.4 KiB
Markdown
293 lines
7.4 KiB
Markdown
Template maps are layergroup configurations that rather than being
|
|
fully defined contain variables that can be set to produce a different
|
|
layergroup configurations (instantiation).
|
|
|
|
Template maps are persistent, can only be created and deleted by the
|
|
CartoDB user showing a valid API_KEY.
|
|
|
|
Instantiating a signed template map would result in a [signed
|
|
map](https://github.com/CartoDB/Windshaft-cartodb/wiki/Signed-maps)
|
|
instance that would be signed with the same signature as the template.
|
|
|
|
Deleting a signed template results in deletion of all signatures created
|
|
as a result of instantiation.
|
|
|
|
|
|
# Template format
|
|
|
|
A templated layergroup would allow using placeholders
|
|
in the "cartocss" and "sql" elements in the "option"
|
|
field of any "layer" of a layergroup configuration
|
|
(see https://github.com/CartoDB/Windshaft/wiki/MapConfig-specification).
|
|
|
|
Valid placeholder names start with a letter and can only
|
|
contain letters, numbers or underscores. They have to be
|
|
written between ``<%= `` and `` %>`` strings in order to be
|
|
replaced. Example: ``<%= my_color %>``.
|
|
|
|
The set of supported placeholders for a template will need to be
|
|
explicitly defined specifying type and default value for each.
|
|
|
|
**placeholder types**
|
|
|
|
Placeholder type will determine the kind of escaping for the
|
|
associated value. Supported types are:
|
|
|
|
* sql_literal (internal single-quotes will be sql-escaped)
|
|
* sql_ident (internal double-quotes will be sql-escaped)
|
|
* number (can only contain numerical representation)
|
|
* css_color (can only contain color names or hex-values)
|
|
* ... (add more as need arises)
|
|
|
|
Placeholder default value will be used when not provided at
|
|
instantiation time and could be used to test validity of the
|
|
template by creating a default instance.
|
|
|
|
Additionally you'll be able to embed an authorization
|
|
certificate that would be used to sign any instance of the template.
|
|
|
|
```js
|
|
// template.json
|
|
{
|
|
version: '0.0.1',
|
|
// there can be at most 1 template with the same name for any user
|
|
// valid names start with a letter and only contains letter, numbers
|
|
// or underscores
|
|
name: 'template_name',
|
|
// embedded authorization certificate
|
|
auth: {
|
|
// See https://github.com/CartoDB/Windshaft-cartodb/wiki/Signed-maps
|
|
method: 'token', // or "open" (the default if no "method" is given)
|
|
valid_tokens: ['auth_token1','auth_token2'] // only (required and non empty) for 'token' method
|
|
},
|
|
// Variables not listed here are not substituted
|
|
// Variable not provided at instantiation time trigger an error
|
|
// A default is required for optional variables
|
|
// Type specification is used for quoting, to avoid injections
|
|
placeholders: {
|
|
color: {
|
|
type:'css_color',
|
|
default:'red'
|
|
},
|
|
cartodb_id: {
|
|
type:'number',
|
|
default: 1
|
|
}
|
|
},
|
|
layergroup: {
|
|
// see https://github.com/CartoDB/Windshaft/wiki/MapConfig-specification
|
|
"version": "1.0.1",
|
|
"layers": [{
|
|
"type": "cartodb",
|
|
"options": {
|
|
"cartocss_version": "2.1.1",
|
|
"cartocss": "#layer { polygon-fill: <%= color %>; }",
|
|
"sql": "select * from european_countries_e WHERE cartodb_id = <%= cartodb_id %>"
|
|
}
|
|
}]
|
|
}
|
|
}
|
|
```
|
|
|
|
# Creating a templated map
|
|
|
|
You can create a signed template map with a single call (for simplicity).
|
|
You'd use a POST sending JSON data:
|
|
|
|
```sh
|
|
curl -X POST \
|
|
-H 'Content-Type: application/json' \
|
|
-d @template.json \
|
|
'https://docs.cartodb.com/tiles/template?api_key=APIKEY'
|
|
```
|
|
|
|
The response would be like this:
|
|
```js
|
|
{
|
|
"template_id":"@template_name"
|
|
}
|
|
```
|
|
|
|
If a template with the same name exists in the user storage,
|
|
a 400 response is generated.
|
|
|
|
Errors are in this form:
|
|
```js
|
|
{
|
|
"error":"Some error string here"
|
|
}
|
|
```
|
|
|
|
# Updating an existing template
|
|
|
|
Update of a template map implies removal all signatures from previous
|
|
map instances.
|
|
|
|
You can update a signed template map with a PUT:
|
|
|
|
```sh
|
|
curl -X PUT \
|
|
-H 'Content-Type: application/json' \
|
|
-d @template.json \
|
|
'https://docs.cartodb.com/tiles/template/:template_name?api_key=APIKEY'
|
|
```
|
|
A template with the same name will be updated, if any.
|
|
|
|
The response would be like this:
|
|
```js
|
|
{
|
|
"template_id":"@template_name"
|
|
}
|
|
```
|
|
|
|
If a template with the same name does NOT exist,
|
|
a 400 HTTP response is generated with an error in this format:
|
|
|
|
```js
|
|
{
|
|
"error":"Some error string here"
|
|
}
|
|
```
|
|
|
|
|
|
# Listing available templates
|
|
|
|
You can get a list of available templates with a GET to ``/template``.
|
|
A valid api_key is required.
|
|
|
|
```sh
|
|
curl -X GET 'https://docs.cartodb.com/tiles/template?api_key=APIKEY'
|
|
```
|
|
|
|
The response would be like this:
|
|
```js
|
|
{
|
|
"template_ids": ["@template_name1","@template_name2"]
|
|
}
|
|
```
|
|
|
|
Or, on error:
|
|
|
|
```js
|
|
{
|
|
"error":"Some error string here"
|
|
}
|
|
```
|
|
|
|
# Getting a specific template
|
|
|
|
You can get the definition of a template with a
|
|
GET to ``/template/:template_name``.
|
|
A valid api_key is required.
|
|
|
|
Example:
|
|
|
|
```sh
|
|
curl -X GET 'https://docs.cartodb.com/tiles/template/@template_name?auth_token=AUTH_TOKEN'
|
|
```
|
|
|
|
The response would be like this:
|
|
```js
|
|
{
|
|
"template": {...} // see template.json above
|
|
}
|
|
```
|
|
|
|
Or, on error:
|
|
|
|
```js
|
|
{
|
|
"error":"Some error string here"
|
|
}
|
|
```
|
|
|
|
# Instantiating a template map
|
|
|
|
You can instantiate a template map passing all required parameters with
|
|
a POST to ``/template/:template_name``.
|
|
|
|
Valid credentials will be needed, if required by the template.
|
|
|
|
```js
|
|
// params.js
|
|
{
|
|
color: '#ff0000',
|
|
cartodb_id: 3
|
|
}
|
|
```
|
|
|
|
```sh
|
|
curl -X POST \
|
|
-H 'Content-Type: application/json' \
|
|
-d @params.js \
|
|
'https://docs.cartodb.com/tiles/template/@template_name?auth_token=AUTH_TOKEN'
|
|
|
|
```
|
|
|
|
The response would be like this:
|
|
```js
|
|
{
|
|
"layergroupid":"docs@fd2861af@c01a54877c62831bb51720263f91fb33:123456788",
|
|
"last_updated":"2013-11-14T11:20:15.000Z"
|
|
}
|
|
```
|
|
|
|
or, on error:
|
|
|
|
```js
|
|
{
|
|
"error":"Some error string here"
|
|
}
|
|
```
|
|
|
|
You can then use the ``layergroupid`` for fetching tiles and grids as you do
|
|
normally ( see https://github.com/CartoDB/Windshaft/wiki/Multilayer-API).
|
|
But you'll still have to show the ``auth_token``, if required by the template
|
|
(see https://github.com/CartoDB/Windshaft-cartodb/wiki/Signed-maps)
|
|
|
|
Instances of a signed template map will be signed with the same signature
|
|
certificate associated with the template. Such certificate would contain
|
|
a reference to the template identifier, so that it can be revoked every
|
|
time the template is updated or deleted.
|
|
|
|
### using JSONP
|
|
There is also a special endpoint to be able to instanciate using JSONP (for old browsers)
|
|
|
|
```
|
|
curl 'https://docs.cartodb.com/tiles/template/@template_name/jsonp?auth_token=AUTH_TOKEN&callback=function_name&config=template_params_json'
|
|
```
|
|
|
|
it takes the ``callback`` function (required), ``auth_token`` in case the template needs auth and ``config`` which is the variabñes for the template (in case it has variables). For example config may be created (using javascript)
|
|
```
|
|
url += "config=" + encodeURIComponent(
|
|
JSON.stringify({ color: 'red' });
|
|
```
|
|
|
|
the response it's in this format:
|
|
```
|
|
jQuery17205720721024554223_1390996319118(
|
|
{
|
|
layergroupid: "dev@744bd0ed9b047f953fae673d56a47b4d:1390844463021.1401",
|
|
last_updated: "2014-01-27T17:41:03.021Z"
|
|
}
|
|
)
|
|
```
|
|
# Deleting a template map
|
|
|
|
Deletion of a template map will imply removal all instance signatures
|
|
|
|
You can delete a templated map with a DELETE to ``/template/:template_name``:
|
|
|
|
```sh
|
|
curl -X DELETE 'https://docs.cartodb.com/tiles/template/@template_name?auth_token=AUTH_TOKEN'
|
|
```
|
|
|
|
On success, a 204 (No Content) response would be issued.
|
|
Otherwise a 4xx response with this format:
|
|
|
|
```js
|
|
{
|
|
"error":"Some error string here"
|
|
}
|
|
```
|