@vidro/map-handler 1.2.12 → 1.2.19

package/examples/react-next/README.md

@@ -0,0 +1,282 @@
+# Map Component React Integration
+
+#### Feb, 2025
+
+## Getting Started
+
+This example is a basic mapComponent integration based in React 19 and Next.js
+
+Requirements:
+
+Node & npm ^19. We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage multiple Node versions on a single server.
+
+
+>Install project
+
+```bash
+npm install
+```
+>Run
+
+```bash
+npm run dev
+```
+You can create an `.env` file with default values for the API URL, user, and password. Simply rename `.env.sample` to `.env`:
+
+```
+NEXT_PUBLIC_APIURL="https://your api url"
+NEXT_PUBLIC_USER="your user"
+NEXT_PUBLIC_PWD="your password"
+```
+
+This example uses [Tailwindcss](https://tailwindcss.com) for layout
+
+
+## Example flow
+
+1. **Signs in to the Maps API**  
+
+   The API sign-in request returns an authentication token and a list of maps the user can access.  
+
+   If the sign-in is successful, a dropdown with available maps will be populated.  
+
+2. **Select a map and click `Load map`**  
+
+   The selected map will be loaded. 😉  
+
+## Project structure
+
+- **pages**
+	- **index.js** is the main file
+
+- **contexts**
+	- **auth.js** handles user's sign in and sign out
+	- **map.js** handles map info
+	- **messajes** handles communication with map component (mapHandler integration)
+
+- **hooks**
+	- **useMapEvents** - custom hook for handling map events
+
+
+- **components**
+	- **AuthComponent** component with auth
+	- **MapList** component with available maps
+	- **MapIframe** component with map iframe
+	- **MapButtons** component with map buttons
+	- **MapLayers** component with map layers, with toggle button
+	- **MapInfo** component for display map info
+	- **MapFilters** component for handle filters
+
+- **shared**
+	- **constants.js** file with constants to minimize typos
+
+	
+## Step by step
+* `components/SessionComponent` interacts with `contexts/auth.js` to handle sign-in and load the map list. Maps and the authentication token are stored in context state variables `projects` and `token`.  
+* If sign-in is successful, `components/SessionComponent` displays a dropdown with the map list and a `Load Map` button.  
+* When `Load Map` is clicked, it calls the `GetMap` method from `contexts/maps`. This sends a request to the maps API and retrieves the iframe URL along with the session token. The API response looks something like this:
+
+
+```
+{
+    "message": {
+        "sessionToken": "eyJ0eXAiOiJKV1QiLC.... very long",
+        "iframe": "https:\/\/your.domain.com\/yourcomponent\/"
+    }
+}
+```
+
+* `contexts/maps` sets context vars `map` and `sessionToken`. `map` will contain the url required by the iframe:
+
+```
+ setSessionToken(message.essionToken);
+      setMap(
+        `${message.iframe}?sessionToken=${message.sessionToken}`
+      );
+``` 
+
+* `components/MapIframe` will render the iframe and start the mapHandler library:
+
+```
+  useEffect(() => {
+    if (!sessionToken) return;
+    start(sessionToken); //starts communicator
+  }, [sessionToken]);
+```
+
+* `hooks/useMapEvents` listens to map events. When the map is loaded, a `loaded` event is emitted, and a context variable `mapReady` is set to `true`. This ensures that all child components recognize when the map is ready for interaction.  
+
+
+```
+ useEffect(() => {
+    if (!message) return;
+    switch (message.type) {
+      case MAP_EVENTS.LOADED:
+        if (message.what === "map") {
+          console.log("useMapEvents Map loaded and ready");
+          setMapReady(true);
+        }
+        setMessage(null);
+        break;
+    }
+  }, [message]);
+```
+  
+ 
+Map is ready and buttons active!
+
+
+## Map Events
+
+The map emits several events. To avoid race conditions caused by concurrent events, we use a message queue.
+
+In `contexts/messages.js` we manage this queue.
+
+We have to state vars:
+
+```
+  const [message, setMessage] = useState(null);
+  const [messageQueue, setMessageQueue] = useState([]);
+```
+ 
+
+We set listeners for the events we need:
+
+``` 
+useEffect(() => {
+    if (!communicator) return;
+    communicator.on(MAP_EVENTS.ZOOM_CHANGE, onMapEvent);
+    communicator.on(MAP_EVENTS.LOADED, onMapEvent);
+
+    return () => {
+      if (!communicator) return;
+      communicator.off(MAP_EVENTS.ZOOM_CHANGE, onMapEvent);
+      communicator.off(MAP_EVENTS.LOADED, onMapEvent);
+     
+      setCommunicator(null);
+    };
+  }, [communicator, events]);
+  
+``` 
+Each time an event is received we add the event to the queue
+
+``` 
+  const onMapEvent = (data) => {
+    console.log(`onMapEvent`, { type: data.type, data });
+    setMessageQueue((prevQueue) => [...prevQueue, data]);
+  };
+```
+When `messageQueue` or `message` changes to `null`, we pick the next message in the queue `messageQueue[0]` 
+
+```
+
+  useEffect(() => {
+    if (message) return;
+    if (messageQueue.length === 0) {
+      return;
+    }
+    setMessage(messageQueue[0]);
+    setMessageQueue((prevQueue) => {
+      return prevQueue.slice(1);
+    });
+  }, [messageQueue, message]);
+```
+
+In this project, all events are handled in `hooks/useMapEvents` , each event, when is handled sets `message` to `null` -> `setMessage(null)`, for example:
+
+```
+ useEffect(() => {
+    if (!message) return;
+    switch (message.type) {
+      case MAP_EVENTS.LOADED:
+        if (message.what === "map") {
+          console.log("useMapEvents Map loaded and ready");
+          setMapReady(true);
+        }
+        setMessage(null);
+        break;
+     
+      default:
+        setMessage(null);
+        break;
+    }
+  }, [message, displayedLayers]);
+```
+
+## Adding elements to map
+
+There's an example of how to add a point to map.
+
+Button `Add point` starts the map component add point flow. 
+
+```
+const { drawPoint } = useMessages();
+<button
+    onClick={(e) => {
+     console.log("Draw point");
+     drawPoint({});
+    }}
+ >
+Add point
+</button>
+```
+When point is added, in `hooks/useMapEvents` we receive the event and we draw the geometry:
+
+```
+  useEffect(() => {
+    if (!message) return;
+    switch (message.type) {
+ case MAP_EVENTS.GEOM_ADDED:
+        console.log("GeomAdded", message);
+        setCurrentMapAction(null);
+        //Highlight the added geom
+        Highlight(
+          {
+            feature_type: "HIGHLIGHT",
+            geom: message?.geom_astext,
+          },
+          2,
+          {
+            duration: 1500,
+            repeat: true,
+          },
+          0,
+          null
+        );
+        if (message?.geom_astext === null) {
+          setMessage(null);
+          return;
+        }
+      }, [message, displayedLayers]);
+```
+ 
+Check [Highlight method documentation](https://github.com/Vidro-Software-SL/maphandler?tab=readme-ov-file#higlight) to understand method params
+
+## Filtering layers
+
+In `components/MapFilters` there's an example of how to apply filters
+
+Method `applyFilter`:
+
+- Checks if there is an active layer selected.
+- Constructs a filter object based on the selected layer and filter criteria.
+- Sends the filter to the mapComponent to be applied on the map.
+
+## Next.js 
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn-pages-router) - an interactive Next.js tutorial.
+
+## Tailwindcss
+
+o learn more about Tailwindcss, take a look [https://tailwindcss.com](https://tailwindcss.com)
+
+
+## Support
+
+Join us in [Discord](https://discord.com/channels/1305257097843179642/1305257098313072714) 
+
+![](public/logo.png)
+

package/examples/react-next/components/AuthComponent.js

@@ -0,0 +1,88 @@
+import { useAuth } from "@/contexts/auth";
+import { useState } from "react";
+
+const AuthComponent = () => {
+  const { apiUrl, setApiUrl, login, logged, logout } = useAuth();
+  const [user, setUser] = useState(
+    process.env.NEXT_PUBLIC_USER ? process.env.NEXT_PUBLIC_USER : ""
+  );
+  const [pwd, setPwd] = useState(
+    process.env.NEXT_PUBLIC_PWD ? process.env.NEXT_PUBLIC_PWD : ""
+  );
+  const [selectedMap, setSelectedMap] = useState("-1");
+
+  // Handler for API URL input changes
+  const handleApiUrlChange = (event) => {
+    setApiUrl(event.target.value);
+  };
+
+  return (
+    <div>
+      {logged && (
+        <div className="bg-gray-200 p-2  text-left">
+          <div className="text-xs">
+            Logged as <b>{user}</b>
+          </div>
+          <div className="text-xs">
+            API: <b>{apiUrl}</b>
+          </div>
+          <button
+            onClick={(e) => {
+              logout();
+            }}
+            className="border border-gray-300 bg-black text-white rounded-md p-2 mt-1 text-xs"
+          >
+            Logout
+          </button>
+        </div>
+      )}
+      {!logged && (
+        <div>
+          <div className="mb-4 flex gap-1">
+            <label className="w-32">API URL</label>
+            <input
+              type="text"
+              value={apiUrl}
+              onChange={handleApiUrlChange}
+              placeholder="Enter API URL..."
+              className="border border-gray-300 rounded-md p-2 w-full"
+            />
+          </div>
+          <div className="mb-4 flex gap-1">
+            <label className="w-32">User</label>
+            <input
+              type="text"
+              value={user}
+              onChange={(e) => setUser(e.target.value)}
+              placeholder="User"
+              disabled={logged}
+              className="border border-gray-300 rounded-md p-2 w-full"
+            />
+          </div>
+          <div className="mb-4 flex gap-1">
+            <label className="w-32">Password</label>
+            <input
+              type="password"
+              value={pwd}
+              onChange={(e) => setPwd(e.target.value)}
+              disabled={logged}
+              placeholder="User"
+              className="border border-gray-300 rounded-md p-2 w-full"
+            />
+          </div>
+
+          <button
+            onClick={(e) => {
+              login(user, pwd);
+            }}
+            className="border border-gray-300 bg-black text-white rounded-md p-2"
+          >
+            Login
+          </button>
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default AuthComponent;

package/examples/react-next/components/MapButtons.js

@@ -0,0 +1,161 @@
+import { useAuth } from "@/contexts/auth";
+import { useMaps } from "@/contexts/maps";
+import { useMessages } from "@/contexts/messages";
+import { useEffect, useState } from "react";
+
+const MapButtons = () => {
+  const { logged } = useAuth();
+  const { map, mapReady, clickedCoordinates } = useMaps();
+  const {
+    ZoomIn,
+    ZoomOut,
+    zoomToExtent,
+    drawPoint,
+    Clear,
+    Highlight,
+    centerMap,
+  } = useMessages();
+  if (!logged) return null;
+  return (
+    <>
+      {!mapReady && <div>Waiting map...</div>}
+      {mapReady && (
+        <div className="flex gap-1 text-xs">
+          <button
+            onClick={(e) => {
+              console.log("Zoom +");
+              ZoomIn();
+            }}
+            disabled={!map}
+            className="border border-gray-300 bg-black text-white rounded-md p-2"
+          >
+            Zoom +
+          </button>
+          <button
+            onClick={(e) => {
+              console.log("Zoom -");
+              ZoomOut();
+            }}
+            className="border border-gray-300 bg-black text-white rounded-md p-2"
+          >
+            Zoom -
+          </button>
+          <button
+            onClick={(e) => {
+              console.log("Zoom to extent");
+              zoomToExtent();
+            }}
+            className="border border-gray-300 bg-black text-white rounded-md p-2"
+          >
+            Zoom to extent
+          </button>
+          <button
+            onClick={(e) => {
+              console.log("Draw point");
+              drawPoint({});
+            }}
+            className="border border-gray-300 bg-black text-white rounded-md p-2"
+          >
+            Add point
+          </button>
+          <button
+            onClick={(e) => {
+              console.log("Clear");
+              Clear();
+            }}
+            className="border border-gray-300 bg-black text-white rounded-md p-2"
+          >
+            Clear
+          </button>
+          <button
+            onClick={(e) => {
+              console.log("Highlight clickedCoordinates", clickedCoordinates);
+              Highlight(
+                {
+                  feature_type: "HIGHLIGHT",
+                  geom: `POINT(${clickedCoordinates[0]} ${clickedCoordinates[1]})`,
+                },
+                2,
+                {
+                  duration: 1500,
+                  repeat: true,
+                },
+                0,
+                null
+              );
+            }}
+            disabled={!clickedCoordinates}
+            className="border border-gray-300 bg-black text-white rounded-md p-2"
+          >
+            Highlight clicked coordinates
+          </button>
+          <button
+            onClick={(e) => {
+              console.log("Highlight clickedCoordinates", clickedCoordinates);
+              centerMap(clickedCoordinates);
+            }}
+            disabled={!clickedCoordinates}
+            className="border border-gray-300 bg-black text-white rounded-md p-2"
+          >
+            Center map to clicked coordinates
+          </button>
+          <ZoomToScaleButton />
+        </div>
+      )}
+    </>
+  );
+};
+export default MapButtons;
+
+const ZoomToScaleButton = () => {
+  const { zoomToScale } = useMessages();
+  const { mapScale } = useMaps();
+  const scales = [
+    { id: "1:100", val: "1:100", label: "1:100" },
+    { id: "1:200", val: "1:200", label: "1:200" },
+    { id: "1:500", val: "1:500", label: "1:500" },
+    { id: "1:1000", val: "1:1000", label: "1:1000" },
+    { id: "1:2000", val: "1:2000", label: "1:2000" },
+    { id: "1:5000", val: "1:5000", label: "1:5000" },
+    { id: "1:10000", val: "1:10000", label: "1:10000" },
+    { id: "1:50000", val: "1:50000", label: "1:50000" },
+  ];
+
+  const [actualValue, setActualValue] = useState(mapScale ? mapScale : "-1");
+  useEffect(() => {
+    if (!mapScale) return;
+    const scale = scales.find((s) => s.val === mapScale);
+    if (scale) {
+      setActualValue(scale.val);
+    } else {
+      setActualValue("-1");
+    }
+    console.log("mapScale", mapScale, scale);
+  }, [mapScale]);
+  return (
+    <div className="mx-2 pt-2">
+      <label>Zoom to scale:</label>
+      <select
+        value={actualValue}
+        onChange={(e) => {
+          const newVal = !isNaN(e.target.value)
+            ? Number(e.target.value)
+            : e.target.value;
+          setActualValue(newVal);
+          zoomToScale(newVal);
+        }}
+      >
+        <option key={`opt_select_scale`} value="-1">
+          Select scale...
+        </option>
+        {scales.map((opt, index) => {
+          return (
+            <option key={`opt_${index}`} value={opt.val}>
+              {opt.label}
+            </option>
+          );
+        })}
+      </select>
+    </div>
+  );
+};

package/examples/react-next/components/MapFilters.js

@@ -0,0 +1,120 @@
+import { useAuth } from "@/contexts/auth";
+import { useMaps } from "@/contexts/maps";
+import { useMessages } from "@/contexts/messages";
+import { useEffect, useState } from "react";
+
+const MapFilters = () => {
+  const {
+    configuredFilters,
+    mapId,
+    filters,
+    activeFilters,
+
+    activeLayer,
+    mapLayers,
+  } = useMaps();
+  const { Filters } = useMessages();
+  const { logged } = useAuth();
+  const [currentFilter, setCurrentFilter] = useState("");
+  const [filterValue, setFilterValue] = useState("");
+  useEffect(() => {
+    if (!configuredFilters) return;
+    console.log("MapFilters configuredFilters", configuredFilters);
+  }, [configuredFilters]);
+
+  useEffect(() => {
+    if (!activeFilters) return;
+    console.log("MapFilters activeFilters", activeFilters);
+  }, [activeFilters]);
+
+  useEffect(() => {
+    if (!filters) return;
+    console.log("MapFilters filters", filters);
+  }, [filters]);
+
+  const applyFilter = () => {
+    if (!activeLayer) {
+      console.log("No active layer");
+      return;
+    }
+    console.log("Apply filter", {
+      currentFilter,
+      filterValue,
+      activeLayer,
+    });
+    //find layer info
+    const lay = mapLayers.find((l) => l.qgis_name === activeLayer);
+    console.log("Layer info", lay);
+    //format filter for mapComponent digest
+    const filter = [
+      {
+        layer_id: lay.id,
+        layer_name: lay.qgis_name,
+        filters: [
+          [
+            {
+              name: currentFilter,
+              condition: "=", //default condition - you can get condition from configuredFilters
+              value: filterValue,
+              value2: null,
+              layer_id: lay.id,
+              mapId: mapId,
+            },
+          ],
+        ],
+      },
+    ];
+    Filters(filter);
+    console.log("Filter", filter);
+  };
+
+  if (!logged) return null;
+  if (!mapId) return null;
+  return (
+    <>
+      <div>
+        {configuredFilters && configuredFilters.length === 0 && (
+          <div>No filters available</div>
+        )}
+
+        <div className="m-2 flex gap-2">
+          <label className="block text-sm font-medium text-gray-700 pt-2">
+            Filters
+          </label>
+          {configuredFilters && configuredFilters.length > 0 && (
+            <select
+              className="border border-gray-300 rounded-md p-2 w-60"
+              onChange={(e) => setCurrentFilter(e.target.value)}
+              value={currentFilter}
+            >
+              <option value="-1">Select filter...</option>
+              {configuredFilters.map((ele) => (
+                <option key={ele.id} value={ele.name}>
+                  {ele.name}
+                </option>
+              ))}
+            </select>
+          )}
+          <input
+            type="text"
+            value={filterValue}
+            onChange={(e) => setFilterValue(e.target.value)}
+            className="border border-gray-300 rounded-md p-2 w-60"
+          />
+          <button
+            onClick={(e) => {
+              console.log("Apply filter");
+              applyFilter();
+            }}
+            disabled={filterValue === "" || currentFilter === "-1"}
+            className="border border-gray-300 bg-black text-white rounded-md p-2 mt-1 text-xs"
+          >
+            Apply filter
+          </button>
+        </div>
+      </div>
+    </>
+  );
+};
+
+export default MapFilters;

package/examples/react-next/components/MapIframe.js

@@ -0,0 +1,25 @@
+import { useMaps } from "@/contexts/maps";
+import { useMessages } from "@/contexts/messages";
+import { useEffect } from "react";
+
+const MapIframe = () => {
+  const { map, sessionToken } = useMaps();
+  const { start } = useMessages();
+
+  useEffect(() => {
+    if (!sessionToken) return;
+    start(sessionToken); //starts communicator
+  }, [sessionToken]);
+
+  if (!map && !sessionToken) return null;
+  return (
+    <iframe
+      id="map-frame"
+      name="map-frame"
+      src={map}
+      allow="geolocation"
+      className="h-screen w-full"
+    ></iframe>
+  );
+};
+export default MapIframe;