@situm/cordova 3.3.0 → 3.3.2

package/www/map-view-controller.js

@@ -1,38 +1,80 @@
-const Situm = require("@situm/cordova.situm");
+const Situm = require('@situm/cordova.situm')
 
 /**
+ * Here's an example on how to use this controller class:
+ * <div id="codeSnippet">
+ * <pre id="textToCopy">
+ * <p style="font-weight: bold;position: absolute;top: 10px;left: 10px;text-decoration: underline">JAVASCRIPT</p>
+ * cordova.plugins.MapView.onLoad((controller: any) => {
+ *  // Once the MapView was loaded you can start managing our map by:
+ *
+ *  // 1. Sending actions like selecting or navigating to a POI in a building:
+ *   // controller.selectPoi('YOUR_POI_IDENTIFIER');
+ *   // controller.navigateToPoi('YOUR_POI_IDENTIFIER');
+ *
+ *   // 2. Listen to events that take place inside our map like a POI being selected or deselected:
+ *   controller.onPoiSelected((poiSelectedResult: any) => {
+ *     console.log("EXAMPLE> onPoiSelected -> ", poiSelectedResult);
+ *   });
+ *
+ *   controller.onPoiDeselected((poiDeselectedResult: any) => {
+ *     console.log("EXAMPLE> onPoiDeselected -> ", poiDeselectedResult);
+ *   });
+ * });
+ * </pre>
+ * 
+ * <button id="copySnippetButton">Copy</button>
+ * </div>
+ * 
+ * <script>
+    document.getElementById("copySnippetButton").addEventListener("click", function() {
+      var textToCopy = document.getElementById("textToCopy");
+
+      var range = document.createRange();
+      range.selectNode(textToCopy);
+      window.getSelection().removeAllRanges();
+      window.getSelection().addRange(range);
+
+      document.execCommand("copy");
+      window.getSelection().removeAllRanges();
+      this.textContent = "Copied!";
+    });
+    </script>
+ *
+ *
  * @namespace MapViewControllerImpl
+ * @name MapViewController
  */
 class MapViewControllerImpl {
-  _onLoadCallback = undefined;
-  _onPoiSelectedCallback = undefined;
-  _onPoiDeselectedCallback = undefined;
-  _buildings = undefined;
-  _mapView = undefined;
-  _isNavigating = false;
+  _onLoadCallback = undefined
+  _onPoiSelectedCallback = undefined
+  _onPoiDeselectedCallback = undefined
+  _buildings = undefined
+  _mapView = undefined
+  _isNavigating = false
 
   constructor() {
-    Situm.internalSetEventDelegate(this._handleSdkNativeEvents.bind(this));
+    Situm.internalSetEventDelegate(this._handleSdkNativeEvents.bind(this))
   }
 
   _prepare(mapView) {
-    this._mapView = mapView;
+    this._mapView = mapView
   }
 
   _setOnLoadCallback(callback) {
-    this._onLoadCallback = callback;
+    this._onLoadCallback = callback
   }
 
   _sendMessageToViewer(type, payload) {
     let message = {
       type: type,
       payload: payload,
-    };
+    }
     if (this._mapView && this._mapView.firstElementChild) {
       this._mapView.firstElementChild.contentWindow.postMessage(
         message,
         this._mapView._getViewerDomain()
-      );
+      )
     }
   }
 
@@ -42,20 +84,20 @@ class MapViewControllerImpl {
 
   _handleSdkNativeEvents(eventName, payload) {
     switch (eventName) {
-      case "onLocationUpdate":
+      case 'onLocationUpdate':
         // TODO: iOS is sending messages here not related to Location. Check
         // some fields to avoid assuming that we receive an object of type Location.
         if (payload.buildingIdentifier && payload.position) {
-          this._handleOnLocationUpdate(payload);
+          this._handleOnLocationUpdate(payload)
         } else if (payload.statusName) {
-          this._handleOnLocationStatus(payload);
+          this._handleOnLocationStatus(payload)
         }
-        break;
+        break
     }
   }
 
   _handleOnLocationUpdate(payload) {
-    this._sendMessageToViewer("location.update", payload);
+    this._sendMessageToViewer('location.update', payload)
     if (this._isNavigating) {
       Situm.updateNavigationWithLocation(
         [payload],
@@ -63,16 +105,16 @@ class MapViewControllerImpl {
           // Do nothing.
         },
         () => {
-          console.error("Error at updateNavigationWithLocation");
+          console.error('Error at updateNavigationWithLocation')
         }
-      );
+      )
     }
   }
 
   _handleOnLocationStatus(payload) {
-    this._sendMessageToViewer("location.update_status", {
+    this._sendMessageToViewer('location.update_status', {
       status: payload.statusName,
-    });
+    })
   }
 
   // ==================================================
@@ -81,46 +123,46 @@ class MapViewControllerImpl {
 
   _handleMapViewMessages(m) {
     switch (m.type) {
-      case "app.map_is_ready":
+      case 'app.map_is_ready':
         if (
           this._onLoadCallback &&
-          typeof this._onLoadCallback === "function"
+          typeof this._onLoadCallback === 'function'
         ) {
-          this._onLoadCallback(this);
-          console.debug("Map is ready!");
+          this._onLoadCallback(this)
+          console.debug('Map is ready!')
         }
-        break;
-      case "cartography.poi_selected":
-        console.debug(`poi (${m.payload.identifier}) was selected`);
+        break
+      case 'cartography.poi_selected':
+        console.debug(`poi (${m.payload.identifier}) was selected`)
         const poiSelectedResult = {
           poi: {
             identifier: m.payload.identifier,
             buildingIdentifier: m.payload.buildingIdentifier,
           },
-        };
-        this._onPoiSelectedCallback(poiSelectedResult);
-        break;
-      case "cartography.poi_deselected":
+        }
+        this._onPoiSelectedCallback(poiSelectedResult)
+        break
+      case 'cartography.poi_deselected':
         const poiDeselectedResult = {
           poi: {
             identifier: m.payload.identifier,
             buildingIdentifier: m.payload.buildingIdentifier,
           },
-        };
-        this._onPoiDeselectedCallback(poiDeselectedResult);
-        break;
-      case "directions.requested":
-        this._onDirectionsRequested(m.payload);
-        break;
-      case "navigation.requested":
-        this._onNavigationRequested(m.payload);
-        break;
-      case "navigation.stopped":
-        this._onNavigationCancel();
-        break;
+        }
+        this._onPoiDeselectedCallback(poiDeselectedResult)
+        break
+      case 'directions.requested':
+        this._onDirectionsRequested(m.payload)
+        break
+      case 'navigation.requested':
+        this._onNavigationRequested(m.payload)
+        break
+      case 'navigation.stopped':
+        this._onNavigationCancel()
+        break
       default:
-        console.debug("Got unmanaged message: ", m);
-        break;
+        console.debug('Got unmanaged message: ', m)
+        break
     }
   }
 
@@ -129,35 +171,35 @@ class MapViewControllerImpl {
     if (this._buildings) {
       let building = this._buildings.find(
         (b) => b.buildingIdentifier == buildingId
-      );
-      callback(building);
+      )
+      callback(building)
     } else {
       // Fetch buildings and calculate route.
       cordova.plugins.Situm.fetchBuildings(
         (res) => {
-          this._buildings = res;
+          this._buildings = res
           let building = this._buildings.find(
             (b) => b.buildingIdentifier == buildingId
-          );
-          callback(building);
+          )
+          callback(building)
         },
         (err) => {
-          callback(undefined);
+          callback(undefined)
         }
-      );
+      )
     }
   }
 
   // DIRECTIONS:
 
   _onDirectionsRequested(payload) {
-    let directionsRequest = payload.directionsRequest;
+    let directionsRequest = payload.directionsRequest
     let mapViewerData = {
       identifier: payload.identifier,
       originIdentifier: payload.originIdentifier,
       destinationIdentifier: payload.destinationIdentifier,
       type: directionsRequest.accessibilityMode,
-    };
+    }
     this._ensureBuilding(payload.buildingIdentifier, (building) => {
       if (building) {
         Situm.requestDirections(
@@ -168,38 +210,38 @@ class MapViewControllerImpl {
             directionsRequest,
           ],
           (route) => {
-            this._sendMessageToViewer("directions.update", {
+            this._sendMessageToViewer('directions.update', {
               ...route,
               ...mapViewerData,
-            });
+            })
           },
           (error) => {
-            this._sendMessageToViewer("directions.update", {
+            this._sendMessageToViewer('directions.update', {
               error: -1,
               identifier: mapViewerData.identifier,
-            });
+            })
           }
-        );
+        )
       } else {
-        this._sendMessageToViewer("directions.update", {
+        this._sendMessageToViewer('directions.update', {
           error: -1,
           identifier: payload.identifier,
-        });
+        })
       }
-    });
+    })
   }
 
   // NAVIGATION
 
   _onNavigationRequested(payload) {
-    let directionsRequest = payload.directionsRequest;
+    let directionsRequest = payload.directionsRequest
     let mapViewerData = {
       identifier: payload.identifier,
       originIdentifier: payload.originIdentifier,
       destinationIdentifier: payload.destinationIdentifier,
       type: directionsRequest.accessibilityMode,
-    };
-    let navigationRequest = payload.navigationRequest;
+    }
+    let navigationRequest = payload.navigationRequest
     this._ensureBuilding(payload.buildingIdentifier, (building) => {
       // Request directions again to update the calculated route on the native side.
       Situm.requestDirections(
@@ -210,59 +252,59 @@ class MapViewControllerImpl {
           directionsRequest,
         ],
         (route) => {
-          this._isNavigating = true;
-          this._sendMessageToViewer("navigation.start", {
+          this._isNavigating = true
+          this._sendMessageToViewer('navigation.start', {
             ...route,
             ...mapViewerData,
-          });
+          })
           Situm.requestNavigationUpdates(
             [navigationRequest],
             (progress) => {
               // Navigation is working, handle different progress types:
-              if (progress.type == "progress") {
-                progress.type = "PROGRESS"; // The map-viewer waits for an upper case "type".
-                this._sendMessageToViewer("navigation.update", progress);
-              } else if (progress.type == "destinationReached") {
-                this._sendMessageToViewer("navigation.update", {
-                  type: "DESTINATION_REACHED",
-                });
-                this._isNavigating = false;
-              } else if (progress.type == "userOutsideRoute") {
-                this._sendMessageToViewer("navigation.update", {
-                  type: "OUT_OF_ROUTE",
-                });
+              if (progress.type == 'progress') {
+                progress.type = 'PROGRESS' // The map-viewer waits for an upper case "type".
+                this._sendMessageToViewer('navigation.update', progress)
+              } else if (progress.type == 'destinationReached') {
+                this._sendMessageToViewer('navigation.update', {
+                  type: 'DESTINATION_REACHED',
+                })
+                this._isNavigating = false
+              } else if (progress.type == 'userOutsideRoute') {
+                this._sendMessageToViewer('navigation.update', {
+                  type: 'OUT_OF_ROUTE',
+                })
               }
             },
             (error) => {
-              this._sendMessageToViewer("directions.update", {
+              this._sendMessageToViewer('directions.update', {
                 error: -1,
                 identifier: mapViewerData.identifier,
-              });
-              this._isNavigating = false;
+              })
+              this._isNavigating = false
             }
-          );
+          )
         },
         (error) => {
-          this._sendMessageToViewer("directions.update", {
+          this._sendMessageToViewer('directions.update', {
             error: -1,
             identifier: mapViewerData.identifier,
-          });
-          this._isNavigating = false;
+          })
+          this._isNavigating = false
         }
-      );
-    });
+      )
+    })
   }
 
   _onNavigationCancel() {
-    this._isNavigating = false;
+    this._isNavigating = false
     Situm.removeNavigationUpdates(
       () => {
         // Do nothing.
       },
       () => {
-        console.error("Error removing navigation updates.");
+        console.error('Error removing navigation updates.')
       }
-    );
+    )
   }
 
   // ==================================================
@@ -271,13 +313,16 @@ class MapViewControllerImpl {
 
   /**
    * Allows you to select a {@link POI} programmatically in your venue. This will cause the {@link MapView} to center the view on that POI and show its information.
-   * 
+   *
    * @param {number} identifier The unique identifier of the resource.
+   * @memberof MapViewController
+   * @name selectPoi
+   * @method
    * */
   selectPoi(identifier) {
-    this._sendMessageToViewer("cartography.select_poi", {
+    this._sendMessageToViewer('cartography.select_poi', {
       identifier: identifier,
-    });
+    })
   }
 
   /**
@@ -290,25 +335,30 @@ class MapViewControllerImpl {
    *
    * accessibilityMode defaults to CHOOSE_SHORTEST.
    *
-   * @param {number} identifier The identifier of the poi.
+   * @param {number} identifier The identifier of the POI.
    * @param {'CHOOSE_SHORTEST' | 'ONLY_ACCESSIBLE' | 'ONLY_NOT_ACCESSIBLE_FLOOR_CHANGES' | undefined} accessibilityMode Choose the route type to calculate.
+   * @memberof MapViewController
+   * @name navigateToPoi
+   * @method
    * */
   navigateToPoi(identifier, accessibilityMode) {
-    this._sendMessageToViewer("navigation.start", {
+    this._sendMessageToViewer('navigation.start', {
       navigationTo: Number.parseInt(identifier),
       type: accessibilityMode,
-    });
+    })
   }
 
   /**
-   * Allows you to change the initial language that <map-view> uses to display its UI. 
-   * Checkout the [Situm docs](https://situm.com/docs/query-params/) to see the list of
-   * supported languages.
-   * 
+   * Allows you to change the initial language that &lt;map-view> uses to display its UI.
+   * Checkout the <a href="https://situm.com/docs/13-internationalization/">Situm docs</a> to see the list of supported languages.
+   *
    * @param {string} language an ISO 639-1 code.
+   * @memberof MapViewController
+   * @name setLanguage
+   * @method
    */
-  setLanguage(language){
-    this._sendMessageToViewer("ui.set_language", language);
+  setLanguage(language) {
+    this._sendMessageToViewer('ui.set_language', language)
   }
 
   // ==================================================
@@ -318,19 +368,25 @@ class MapViewControllerImpl {
   /**
    * Informs you, through the function you pass as callback ({@link cb}), that a {@link POI} was selected in your building.
    * @param {Function} cb A callback that returns a {@link PoiSelectedResult} by its parameters.
+   * @memberof MapViewController
+   * @name onPoiSelected
+   * @method
    * */
   onPoiSelected(cb) {
-    this._onPoiSelectedCallback = cb;
+    this._onPoiSelectedCallback = cb
   }
 
   /**
    * Informs you, through the function you pass as callback ({@link cb}), that a {@link POI} was deselected in your building.
    * @param {Function} cb A callback that returns a {@link PoiDeselectedResult} by its parameters.
+   * @memberof MapViewController
+   * @name onPoiDeselected
+   * @method
    * */
   onPoiDeselected(cb) {
-    this._onPoiDeselectedCallback = cb;
+    this._onPoiDeselectedCallback = cb
   }
 }
 
-let MapViewController = new MapViewControllerImpl();
-module.exports = MapViewController;
+let MapViewController = new MapViewControllerImpl()
+module.exports = MapViewController

package/www/map-view.js

@@ -1,16 +1,70 @@
-const MapViewController = require("./map-view-controller");
+const MapViewController = require('./map-view-controller')
 /**
+ * <h4>CODE SNIPPET</h4>
+ *
+ * Here's an example on how to implement this in your html view:
+ * <div id="codeSnippet">
+ * <pre id="textToCopy">
+ * <p style="font-weight: bold;position: absolute;top: 10px;left: 10px;text-decoration: underline">HTML</p>
+ * &lt;map-view
+ *   situm-api-key="YOUR_SITUM_API_KEY"
+ *   building-identifier="YOUR_BUILDING_IDENTIFIER"
+ *   remote-identifier="YOUR_REMOTE_IDENTIFIER"
+ * /&gt;
+ * </pre>
+ * 
+ * <button id="copySnippetButton">Copy</button>
+ * </div>
+ * 
+ * <script>
+    document.getElementById("copySnippetButton").addEventListener("click", function() {
+      var textToCopy = document.getElementById("textToCopy");
+
+      var range = document.createRange();
+      range.selectNode(textToCopy);
+      window.getSelection().removeAllRanges();
+      window.getSelection().addRange(range);
+
+      document.execCommand("copy");
+      window.getSelection().removeAllRanges();
+      this.textContent = "Copied!";
+    });
+    </script>
+ *
+ * <h4>ATTRIBUTES</h4>
+ * <dl>
+ *   <dt>situm-api-key</dt>
+ *   <dd>Your API Key to authenticate yourself in our plugin.
+ *      You can manage out your Situm API Key in <a href="https://dashboard.situm.com/accounts/profile"> https://dashboard.situm.com/accounts/profile</a>.</dd>
+ *
+ *   <dt>building-identifier</dt>
+ *   <dd>The identifier of the building you want to display on the map.
+ *      You can manage this identifier with this guide <a href="https://situm.com/docs/sdk-cartography/#building-details"> https://situm.com/docs/sdk-cartography/#building-details</a>.</dd>
+ *
+ *   <dt>remote-identifier</dt>
+ *   <dd>An identifier that allows you to remotely configure all map settings.</dd>
+ *
+ *   <dt>language</dt>
+ *   <dd>Choose the language that map-view will use to display its UI by specifying an ISO 639-1 code.
+ *      You can also change the language by calling {@link MapViewController.setLanguage()}.
+ *      Checkout the <a href="https://situm.com/docs/13-internationalization/">Situm docs</a> to see the list of supported languages.</dd>
+ *
+ *   <dt>viewer-domain</dt>
+ *   <dd>A parameter that allows you to specify which domain will be displayed inside our webview.
+ *       Default is <a href="https://map-viewer.situm.com">https://map-viewer.situm.com</a></dd>
+ * </dl>
+ *
  * @namespace MapView
  */
 class MapView extends HTMLElement {
-  _viewerDomain;
+  _viewerDomain
 
   constructor() {
-    super();
+    super()
   }
 
   connectedCallback() {
-    MapViewController._prepare(this);
+    MapViewController._prepare(this)
     this.innerHTML = `
       <iframe
         id="map-view-iframe"
@@ -19,74 +73,74 @@ class MapView extends HTMLElement {
         height="100%"
         style="border: none; box-shadow: none;"
       />
-    `;
-    window.addEventListener("message", this._messageReceivedCallback);
+    `
+    window.addEventListener('message', this._messageReceivedCallback)
   }
 
   _getViewerDomain() {
-    return this._viewerDomain;
+    return this._viewerDomain
   }
 
   _getViewerURL() {
     let viewerDomain = this._formatValidDomain(
-      this.getAttribute("viewer-domain")
-    );
-    let situmApiKey = this.getAttribute("situm-api-key") ?? "";
-    let buildingIdentifier = this.getAttribute("building-identifier") ?? "";
-    let language = this.getAttribute("language") ?? "";
+      this.getAttribute('viewer-domain')
+    )
+    let situmApiKey = this.getAttribute('situm-api-key') ?? ''
+    let buildingIdentifier = this.getAttribute('building-identifier') ?? ''
+    let language = this.getAttribute('language') ?? ''
 
-    let situmApiKeyQP = situmApiKey.length > 0 ? `apikey=${situmApiKey}` : "";
+    let situmApiKeyQP = situmApiKey.length > 0 ? `apikey=${situmApiKey}` : ''
     let buildingIdentifierQP =
-      buildingIdentifier.length > 0 ? `&buildingid=${buildingIdentifier}` : "";
-    let languageQP = language.length > 0 ? `&lng=${language}` : "";
+      buildingIdentifier.length > 0 ? `&buildingid=${buildingIdentifier}` : ''
+    let languageQP = language.length > 0 ? `&lng=${language}` : ''
 
-    let query = `${situmApiKeyQP}${buildingIdentifierQP}${languageQP}&mode=embed`;
+    let query = `${situmApiKeyQP}${buildingIdentifierQP}${languageQP}&mode=embed`
 
-    let remoteIdentifier = this.getAttribute("remote-identifier");
+    let remoteIdentifier = this.getAttribute('remote-identifier')
     if (remoteIdentifier) {
-      return `${viewerDomain}/id/${remoteIdentifier}?${query}`;
+      return `${viewerDomain}/id/${remoteIdentifier}?${query}`
     }
-    return `${viewerDomain}/?${query}`;
+    return `${viewerDomain}/?${query}`
   }
 
   _formatValidDomain(domain) {
-    let result = domain;
+    let result = domain
     if (result == null) {
-      return "https://map-viewer.situm.com";
+      return 'https://map-viewer.situm.com'
     }
-    if (!result.startsWith("https://") && !result.startsWith("http://")) {
-      result = `https://${result}`;
+    if (!result.startsWith('https://') && !result.startsWith('http://')) {
+      result = `https://${result}`
     }
-    if (result.endsWith("/")) {
-      result = result.substring(0, result.length - 1);
+    if (result.endsWith('/')) {
+      result = result.substring(0, result.length - 1)
     }
-    this._viewerDomain = result;
-    return result;
+    this._viewerDomain = result
+    return result
   }
 
   _messageReceivedCallback(m) {
     try {
-      const msg = JSON.parse(m.data);
+      const msg = JSON.parse(m.data)
       if (msg && msg.type) {
-        MapViewController._handleMapViewMessages(msg);
+        MapViewController._handleMapViewMessages(msg)
       }
     } catch (error) {
-      console.warn("Got unparseable message:", m);
+      console.warn('Got unparseable message:', m)
     }
   }
 
   /**
    * MapView was loaded.
-   * The {@link MapViewControllerImpl} will be sent by the callback.
+   * The {@link MapViewController} will be sent by the callback.
    * @param {Function} cb The callback that gives back the controller of this visual component.
    */
   static onLoad(cb) {
     // For now, setting the on-load callback from the integrator is done using this (static) bridge.
     // Probably this could be improved.
-    MapViewController._setOnLoadCallback(cb);
+    MapViewController._setOnLoadCallback(cb)
   }
 }
 
-customElements.define("map-view", MapView);
+customElements.define('map-view', MapView)
 
-module.exports = MapView;
+module.exports = MapView