mapa-gcba/README.md

Mapa Interactivo de la Ciudad de Buenos Aires

# Mapa Interactivo

Una forma rápida y sencilla utilizar un mapa de la Ciudad Autónoma de Buenos Aires utilizando la librería [Leaflet](https://leafletjs.com/)

## Instalación

```bash
npm install mapa-gcba
```

## Configuración

### Estilos

Importar los estilos del paquete

```ts
import "mapa-gcba/dist/assets/css/main.css";
```

### Crear una instancia de la clase MapaInteractivo

Importar la clase MapaInteractivo

```ts
import "mapa-gcba/dist/index";
```

El constructor del MapaInteractivo recibe un parámetro obligatorio, que representa el id del elemento HTML donde se insertará el mapa.

```ts
const map = new MapaInteractivo("mapa");
```

### Etiqueta HTML contenedora de mapa

Crear la etiqueta donde se insertará el mapa (el valor de id debe coincidir con el parámetro obligatorio del paso anterior). Además, se deberán agregar los estilos de altura y ancho (height y width) para poder ver el mapa.

```html
<div id="mapa"></div>
```

```css
#mapa {
  height: 500px;
  width: 800px;
}
```

## Mapa Interactivo

### Opciones

La instancia del MapaInteractivo puede recibir un segundo parámetro **options** que permite definir ciertas configuraciones y funcionalidades del mapa. Estas opciones se dividen en params, language, texts, reverseOptions, etc.

Parámetro options:

| Opción             |  Tipo   |       Default       |                 Descripción                  |
| :----------------- | :-----: | :-----------------: | :------------------------------------------: |
| params             | object  | Ver sección params  |    Definir las caraceterísticas del mapa     |
| reverseOptions     | object  | Ver sección reverse | Definir las opciones para el reversegeocoding |
| language           | string  |         es          |           Definir idioma (es o en)           |
| texts              | object  |  Ver sección texts  |        Definir los mensajes a mostrar        |
| showScaleControl   | boolean |        false        |            Mostrar escala de mapa            |
| showLoadingControl | boolean |        false        |           Mostrar mensaje de carga           |
| onClick            | function |        null        |    Callback al hacer _click_ en el mapa    |
| onDblClick         | function |        null        | Callback al hacer doble _click_ en el mapa |
| onContextMenu         | function |        null        | Callback al hacer _click_ secundario en el mapa |

#### Opción _params_

| Opción             |   Tipo   |      Default       |               Descripción                |
| :----------------- | :------: | :----------------: | :--------------------------------------: |
| center             |  Array   | [-34.606, -58.435] |             Centro del mapa              |
| zoom               |  Number  |         12         |              Nivel de zoom               |
| zoomControl        | Boolean  |        true        |             Control de zoom              |
| dragging           | Boolean  |        true        |             Arrastre de mapa             |
| scrollWheelZoom    | Boolean  |        true        |              Zoom con rueda              |
| attributionControl | Boolean  |       false        |          Control de atribución           |
| doubleClickZoom    | Boolean  |       false        |           Zoom con doble click           |
| touchZoom          | Boolean  |        true        |               Zoom táctil                |
| tap                | Boolean  |        true        |             Tocar para zoom              |
| attributionControl | Boolean  |       false        |          Control de atribución           |
| minZoom            |  Number  |         -          |          Zoom mínimo permitido           |
| maxZoom            |  Number  |         -          |          Zoom máximo permitido           |


#### Opción _reverseOptions_

| Opción | Tipo    | Default |                       Descripción                       |
| :----- | :------ | :------ | :-----------------------------------------------------: |
| active | boolean | false   |                Activar reversegeocoding                 |
| type   | string  | address |      Definir el tipo de reverse (address o place/places)      |
| radius | number  | 100     | Definir el radio de búsqueda cuando el _type_ es place/places |

#### Opción _texts_

Valores por defecto para el objeto _texts_

```ts
texts: {
    es: {
      loadingLayers: "Cargando capas...",
      loadingMaps: "Cargando Mapa Base...",
      loadingInformation: "Cargando información...",
      errorLoadingInformation:
        "Se produjo un error al acceder a la información. Reintente más tarde.",
    },
    en: {
      loadingLayers: "Loading layers...",
      loadingMaps: "Loading Base Map...",
      loadingInformation: "Loading information...",
      errorLoadingInformation: "An error ocurred. Please try again later.",
    },
  },
```

### Métodos

**getParamsOptions()**

Retorna las opciones del atributo _params_

**setOptions(options)**

Método Setter de los parámetros del atributo _params_ y los métodos onClick, onDblClick y onContextMenu.

**getReverseOptions()**

Retorna las opciones del atributo _reverseOptions_

**setReverseOptions(options)**

Método Setter de las opciones del atributo _reverseOptions_

**setMarkerView(lat, lng, popup?)**
Este método permite georeferenciar y agregar un marcador de acuerdo a las coordenadas ingresadas.
La opción popup permite agregar un cuadro de diálogo informativo en formato html o texto plano.

**getMap()**

Retorna la instancia interna del mapa

**getOptions()**

Retorna las todas configuraciones del Mapa

## Ejemplos
### Mapa Interactivo en Angular

#### Creación del Proyecto
Utilizar Angular CLI para crear un nuevo proyecto. Abrir una consola de comando y ejecutar:

```bash
ng new map-app
```

Seguir las instrucciones para configurar el proyecto. Una vez creado, navegar hacia la raiz del proyecto:
```bash
cd map-app
```

#### Instalación del Paquete
Instalar el mapa-gcba:

```bash
npm install mapa-gcba
```

#### Importación e Instancia del MapaInteractivo
En `src/app/app.component.ts` se deberá agregar las siguientes líneas de código:
* Importar la clase MapaInteractivo y sus estilos:

```ts
import "mapa-gcba/dist/assets/css/main.css";
import MapaInteractivo from "mapa-gcba/dist/index"
```

* Incializar e instanciar un objeto de la clase MapaInteractivo dentro del método ngAfterViewInit de AppComponent
```ts
ngAfterViewInit() {
    this.map = new MapaInteractivo("mapa");
  }
```

En `src/app/app.component.html` se deberá agregar el la etiqueta _div_ con su correspondiente id:
```html
<div style="text-align:center">
  <h1> {{ title }} </h1>
  <div id="mapa"></div>
</div>
```

En `src/app/app.component.css` se deberá agregar estilos para visualizar el mapa:
```css
#mapa {
    height: 500px;
    width: 800px;
    margin: 0 auto;
}
```

### Mapa Interactivo en ReactJs

#### Creación del Proyecto
Crear un proyecto con CRA o Vite. Abrir una consola de comando y ejecutar:

```bash
npm create vite@latest map-app
```

Seguir las instrucciones para configurar el proyecto. Una vez creado, navegar hacia la raiz del proyecto:
```bash
cd map-app
```

#### Instalación del Paquete
Instalar el mapa-gcba:

```bash
npm install mapa-gcba
```
#### Importación e Instancia del MapaInteractivo
En `src/App.jsx` se deberá agregar las siguientes líneas de código:
* Importar la clase MapaInteractivo y sus estilos:

```js
import "mapa-gcba/dist/assets/css/main.css";
import MapaInteractivo from "mapa-gcba/dist/index"
```

* Incializar e instanciar un objeto de la clase MapaInteractivo dentro de un hook useEffect en un componente React (ejemplo App):
```js
  const mapaInicializado = useRef(false); 

  useEffect(() => {
    if (!mapaInicializado.current) {
      const mapa = new MapaInteractivo("mapa"); 
      mapaInicializado.current = true;      
    }
  }, []);
```

En el _return_ del componente, se deberá agregar una etiqueta _div_ con su correspondiente id:
```jsx
return (
    <>
      <h1>Mapa Interactivo</h1>
      <div id="mapa"></div>
    </>
  );
```

En `App.css` se deberá agregar estilos para visualizar el mapa:
```css
#mapa {
    height: 500px;
    width: 800px;
    margin: 0 auto;
}
```