¿Qué hay aquí? (What is here?)
Nomenclatura usada en la documentación:
- POI: Point Of Interest (punto de interés)
- MBR: Minimum Bounding Rectangle (define un área en un mapa por medio de dos coordenadas)
Descripción de la funcionalidad
WhatIsHere es un control de OpenLayers que muestra puntos de interés en el mapa. Los POIs representan lugares. Por ejemplo, los POIs pueden representar:
- Actividades: farmacias, cines, bares, restaurantes
- Parques y jardines
- Esculturas
- ...
Cada POI está compuesto por:
- Coordenada en el mapa (punto donde se encuentra).
- Icono representativo utilizado como marker al mostrar el punto.
- Código único de identificación.
- Geometría en formato GML del lugar representado por el POI (opcional, si está presente se mostrará la geometría, si no, sólo se mostrará el punto).
Además, se define el concepto de "categorías de POI". Cada categoría de POI representa un conjunto de tipos de POIs. Ejemplos de categorías podrían ser:
- Sanidad, compuesto por: farmacias, hospitales y clínicas
- Cultura, compuesto por: museos, esculturas y bibliotecas
Uso del control
Se trata de un control estándar de OpenLayers, por lo que puede ser añadido al mapa de igual forma a los controles ya proporcionados por OpenLayers:
map.addControl( new OpenLayersExt.Control.WhatIsHere());
Una vez el control ha sido añadido el mapa, este puede ser activado por el usuario haciendo click en la pestaña del panel del control.
Acceso a la información y secuencia de funcionamiento
El control WhatIsHere hace uso de tres URLs (opcionalmente definidas por el usuario) para obtener la información necesaria. Estas URLs se describen con más detalle más adelante.
La secuencia de funcionamiento es la siguiente:
-
El control WhatIsHere se añade al mapa.
-
WhatIsHere carga las categorias disponibles usando la URL "url.categories" y las muestra en la interfaz de usuario.
- Cuando se activa una categoría, se usa la URL "url.search" para cargar los POIs en el MBR visible.
- Cada vez que se mueva el mapa, se usa la URL "url.search" para cargar los nuevos POIs que antes estaban fuera del mapa.
- Cuando el usuario hace click en el icono de un POI, se usa la URL "url.query" para cargar la descripción del POI.
- Esta descripción es mostrada en un pop-up asociada al POI.
- Cuando el usuario hace click en el botón de "mostrar geometría" de un POI, se usa la URL "url.geometry" para cargar la geometría del lugar representado por el POI.
Parámetros de configuración del control
El control puede ser configurado por una serie de parámetros especificados en un objeto (hash) de configuración:
| Parámetro | Valor por defecto |
| { | |
| enabled: | true, |
| urls: { | |
| categories: | /categories.json, |
| search: | /search/mbr/xmin/:xmin/ymin/:ymin/xmax/:xmax/ymax/:ymax/categories/:categories.json, |
| geometry: | /geometry/code/:code.gml, |
| query: | /query/code/:code.html |
| } | |
| } |
Los parámetros de configuración pueden ser especificados parcialmente. Si un parámetro de configuración no es especificado por el usuario, el control usará el valor por defecto para este parámetro.
Estos parámetros de configuración pueden ser pasados al control en tiempo de instanciación:
map.addControl( new OpenLayersExt.Control.WhatIsHere( {
urls: {
categories: "categories/..."
}
}));
También pueden ser pasados al instanciar el OpenLayers Extended:
OpenLayersExtLoader.load( {
"version": "1.0",
"debug": true,
"height": "600px",
"map-libs": {
"google": { "version": "...", "key": "..." },
"yahoo": { "version": "...", "key": "..." },
"microsoft": { "version": "...", "key": "..."}
},
"config": {
"whatishere": {
"enabled": false // desactivamos el control totalmente
}
}
});
En el caso que se le pasen múltiples parámetros de configuración, la prioridad es la siguiente:
- Parámetros pasados directamente en la creación del control.
-
Parámetros pasados al crear el OpenLayers Extended.
Las URLs especificadas en los parámetros de configuración describen "plantillas de URLs" en el sentido de que también tiene parámetros de configuración. El control WhatIsHere reemplaza estos parámetros de URLs por los valores reales antes de hacer la carga de datos de esa URL. Los parámetros de configuración de las URLs tienen la forma ":nombre-de-parámetro".
Parámetro "enabled"
- "true" habilita el control.
- "false" deshabilita el control.
Parámetro "urls.categories"
Especifica la URL usada por el control para cargar los datos de las categorías. Esta URL no admite ningún parámetro de configuración.
El control espera que los datos sean devueltos en formato JSON con el siguiente formato de ejemplo:
{
"categories": [ // inicio de la descripción de categorías
{
"description": "Centros de Salud", // descripción larga usada en la interfaz de usuario
"title": "Sanidad", // descripción corta usada en la interfaz de usuario
"code": "SANIDAD", // cadena de texto arbitraría que identifica esta categoría (usada luego en otras URLS)
"icon": { // descripción del icono usado en la interfaz de usuario
"width": "26", // anchura de la imagen del icono (en píxeles)
"height": "33", // altura de la imagen del icono (en píxeles)
"offset_x": "-13", // desplazamiento en horizontal del centro o "punto activo" del icono con respecto a la esquina superior izquierda
"offset_y": "-33", // desplazamiento en vertical del centro o "punto activo" del icono con respecto a la esquina superior izquierda
"url": "/placemarker_icons/wb_02_01.png" // URL de la imagen del icono a mostrar
}
},
{ "description": "Paradas de autobus", // siguiente categoría
"title": "Transporte",
"code": "TRANSPORTE",
"icon": {
"width": "26",
"height": "33",
"offset_x": "-13",
"offset_y": "-33",
"url": "/placemarker_icons/wb_05.png"
}
}
]
}
Parámetro "urls.search"
Especifica la URL usada para cargar los POIs en un MBR determinado. Esta URL admite los siguientes parámetros de configuración:
| Parámetro | Descripción |
| :xmin | Coordenada X mínima del MBR |
| :ymin | Coordenada Y mínima del MBR |
| :xmax | Coordenada X máxima del MBR |
| :ymax | Coordenada Y máxima del MBR |
| :categories | Lista de códigos separados por comas de categorías cuyos POIs se han de devolver |
Ejemplo de URL con parámetros de configuración:
/api/1.0/es/what-is-here/search/mbr/xmin/:xmin/ymin/:ymin/xmax/:xmax/ymax/:ymax/categories/:categories.json
Y la misma URL con los parámetros reemplazados por el control con valores reales:
/api/1.0/es/what-is-here/search/mbr/xmin/-228933.86930244/ymin/5356355.4330135/xmax/-213684.68216226/ymax/5364954.5986941/categories/SANIDAD,TRANSPORTE.json
El control espera que los datos sean devueltos en formato JSON con el siguiente formato de ejemplo:
{
"categories": [ // agrupa las distintas categorías
{
"code": "SANIDAD", // código de esta categoría
"pois": [ // POIs pertenecientes a esta categoría
{
"code": "C_4_5-508", // código único que identifica este POI (código arbitrario pero único entre todos los POIs posibles)
"coordinate": { // coordenada del POI
"lat": "5361617.12211161",
"lon": "-214381.92653163"
},
"show_geometry_on_search": false, // mostrar la geometría del POI de forma inicial
"icon": { // icono descriptivo del POI (puede ser diferente al de la categoría)
"offset_x": "-13",
"url": "/placemarker_icons/wb_02_01.png",
"width": "26",
"height": "33",
"offset_y": "-33"
}
},
{
"code": "C_4_2-7637", // siguiente POI en esta categoría
"coordinate": {
"lat": "5361319.95580418",
"lon": "-214777.79362183"
},
"show_geometry_on_search": false,
"icon": {
"offset_x": "-13",
"url": "/placemarker_icons/wb_05_06.png",
"width": "26",
"height": "33",
"offset_y": "-33"
}
}
]
},
{
"code": "TRANSPORTE", // siguiente categoría con sus POIs
"pois": [
{
"code": "C_8_8-12971",
"coordinate": {
"lat": "5361710.61043426",
"lon": "-214513.297781279"
},
"show_geometry_on_search": false,
"icon": {
"offset_x": "-13",
"url": "/placemarker_icons/wb_04_03.png",
"width": "26",
"height": "33",
"offset_y": "-33"
}
}
]
}
]
}
Parámetro "urls.geometry"
Especifica la URL usada para cargar la geometría de un POI determinado.
Esta URL admite los siguientes parámetros de configuración:
| Parámetro | Descripción |
| :code | Código identificativo del POI |
Ejemplo de URL con parámetros de configuración:
/api/1.0/es/what-is-here/geometry/code/:code.gml
Y la misma URL con los parámetros reemplazados por el control con valores reales:
/api/1.0/es/what-is-here/geometry/code/C_4_5-281.gml
El formato de la geometría tiene que estar en formato GML (http://en.wikipedia.org/wiki/Geography_Markup_Language) como el siguiente ejemplo:
<wfs:FeatureCollection xmlns:bsc="http://www.bsc-eoc.org/bsc"
xmlns:wfs="http://www.opengis.net/wfs"
xmlns:gml="http://www.opengis.net/gml"
xmlns:ogc="http://www.opengis.net/ogc"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<gml:featureMember>
<gml:Polygon srsName="SDO:900913" xmlns:gml="http://www.opengis.net/gml">
<gml:outerBoundaryIs>
<gml:LinearRing>
<gml:coordinates decimal="." cs="," ts=" ">-230059.094096,5337565.546496 -230070.777861,5337562.873749 -230065.280491,5337538.788359 -230053.610295,5337541.474988 -230059.094096,5337565.546496 </gml:coordinates>
</gml:LinearRing>
</gml:outerBoundaryIs>
</gml:Polygon>
</gml:featureMember>
</wfs:FeatureCollection>
Parámetro "urls.query"
Especifica la URL usada para obtener la información de un POI determinado.
Esta URL admite los siguientes parámetros de configuración:
| Parámetro | Descripción |
| :code | Código identificativo del POI |
Ejemplo de URL con parámetros de configuración:
/api/1.0/es/what-is-here/query/code/:code.html
Y la misma URL con los parámetros reemplazados por el control con valores reales:
/api/1.0/es/what-is-here/query/code/C_4_5-281.html
La información tiene que ser devuelta en HTML como en el siguiente ejemplo:
<div class="b5map-queryResults">
<div class="b5map-queryResult b5map-queryResultActive">
<h2>Centro de salud</h2>
<h3>C. Irura:Irurako K.</h3>
<p>943 690720</p>
<p class="b5map-queryResultActions clearfix">
<a class="b5map-cleanBtn b5map-showGeometry" href="#">
<span>Mostrar en el mapa</span>
<span style="display:none">Ocultar en el mapa</span>
</a>
</p>
</div>
</div>
Ejemplo de uso
El control WhatIsHere solo puede ser usado con OpenLayers Extended.
La siguiente página HTML muestra el uso de WhatIsHere con unas URLs que usan "parámetros de query" (http://en.wikipedia.org/wiki/URI_scheme#Examples):
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="es" xml:lang="es">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title> Ejemplo del control WhatIsHere </title>
<script src="/api/1.0/es/library/openlayers-ext/openlayers-ext-loader.js" type="text/javascript"></script>
<script type="text/javascript">
//<![CDATA[
OpenLayersExtLoader.load( {
"version": "1.0",
"debug": true,
"height": "600px",
"map-libs": {
"google": { "version": "2", "key": "google-key" },
"yahoo": { "version": "3.0", "key": "yahoo-key" },
"microsoft": { "version": "6.1", "key": "microsoft-key"}
},
"config": {
"whatishere": {
"urls": {
categories: "/categories.php",
search: "/search.php?xmin=:xmin&ymin=:ymin&xmax=:xmax&ymax=:ymax&categories=:categories",
geometry: "/geometry.php?code=:code",
query: "/query.php?code=:code"
}
}
}
});
//]]>
</script>
<script type="text/javascript">
//<![CDATA[
Event.observe( window, "load", function() {
window.b5map = new OpenLayersExt.Map( "mymap");
});
//]]>
</script>
<style type="text/css">
#mymap {
width: 90%;
margin: auto;
margin-top: 2em;
}
</style>
</head>
<body>
<div id="mymap">
</div>
</body>
</html>
