feat: examples updated and cleaned up (#7)

* fix: update html examples HTML examples were still using the prerelease versions for the library, these are now replaced with files loaded from unpkg.com. * fix: add minimal typescript/vite example * fix: cleanup playground, remove prerelease content
googlemaps · Aug 18, 2023 · fd3be63 · fd3be63
1 parent d96e6b0
commit fd3be63
Show file tree

Hide file tree

Showing 14 changed files with 798 additions and 44 deletions.
diff --git a/examples/html/README.md b/examples/html/README.md
@@ -0,0 +1,22 @@
+# Advanced Markers Utils – HTML Examples
+
+This directory contains examples for the different ways to use
+`@googlemaps/adv-markers-utils` in a plain html file without needing a
+bundler or similar.
+
+- **`esm.html`** shows how to load the library from a CDN
+  ([unpkg.com](https://unpkg.com) in this example) as a native ES module.
+- **`importmap.html`** is similar, but it uses [importmaps][mdn_importmap]
+  to load the library.
+- **`umd.html`** uses the UMD build of the library for older browsers.
+
+To run these examples, you only need an HTTP-Server and [a Google Maps API Key][gmp_apikey].
+If you have node.js installed, you can start a server by running the command
+
+    npx http-server
+
+in this directory and opening the URL shown in your browser (typically http://localhost:8080).
+The site will then ask for the Google Maps API Key to use and show the map with the marker.
+
+[mdn_importmap]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap
+[gmp_apikey]: https://developers.google.com/maps/documentation/javascript/get-api-key#create-api-keys
diff --git a/examples/html/esm.html b/examples/html/esm.html
@@ -1,4 +1,4 @@
-<!DOCTYPE html>
+<!doctype html>
 <!--
  Copyright 2023 Google LLC
 
@@ -22,7 +22,7 @@
       name="viewport"
       content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"
     />
-    <title>Map / Marker example using importmaps</title>
+    <title>Map / Marker example using native ES modules</title>
     <style>
       body {
         margin: 0;
@@ -64,11 +64,10 @@
     <div id="map"></div>
 
     <script type="module">
-      import {Marker} from 'https://storage.ubidev.net/marker-api-playground/lib/index.module.js';
+      import {Marker} from 'https://unpkg.com/@googlemaps/adv-markers-utils/dist/index.module.js';
 
       async function main() {
         const {Map} = await google.maps.importLibrary('maps');
-
         await google.maps.importLibrary('marker');
 
         const map = new Map(document.querySelector('#map'), {

diff --git a/examples/html/importmap.html b/examples/html/importmap.html
@@ -1,4 +1,4 @@
-<!DOCTYPE html>
+<!doctype html>
 <!--
  Copyright 2023 Google LLC
 
@@ -41,9 +41,9 @@
     <script type="importmap">
       {
         "imports": {
-          "@googlemaps/marker": "https://storage.ubidev.net/marker-api-playground/lib/index.module.js",
-          "@googlemaps/marker/icons": "https://storage.ubidev.net/marker-api-playground/lib/icons.module.js",
-          "@googlemaps/marker/places": "https://storage.ubidev.net/marker-api-playground/lib/places.module.js"
+          "@googlemaps/marker": "https://unpkg.com/@googlemaps/adv-markers-utils/dist/index.module.js",
+          "@googlemaps/marker/icons": "https://unpkg.com/@googlemaps/adv-markers-utils/dist/icons.module.js",
+          "@googlemaps/marker/places": "https://unpkg.com/@googlemaps/adv-markers-utils/dist/places.module.js"
         }
       }
     </script>

diff --git a/examples/html/umd.html b/examples/html/umd.html
@@ -1,4 +1,4 @@
-<!DOCTYPE html>
+<!doctype html>
 <!--
  Copyright 2023 Google LLC
 
@@ -59,17 +59,17 @@
         v: "beta"
       });
     </script>
-    <script src="https://storage.ubidev.net/marker-api-playground/lib/index.umd.js"></script>
+    <script src="https://unpkg.com/@googlemaps/adv-markers-utils/dist/index.umd.js"></script>
   </head>
   <body>
     <div id="map"></div>
 
-    <script type="module">
+    <script>
       async function main() {
         const {Map} = await google.maps.importLibrary('maps');
         await google.maps.importLibrary('marker');
 
-        const {Marker} = google.maps.plugins.marker;
+        const {Marker} = google.maps.plugins.advMarkersUtils;
 
         const map = new Map(document.querySelector('#map'), {
           mapId: 'bf51a910020fa25a',

diff --git a/examples/playground/README.md b/examples/playground/README.md
@@ -1,25 +1,24 @@
-# Marker API Playground
+# Advanced Markers Utils – Marker Playground
 
-This directory is the testing ground and development-environment for
-the marker API.
+This directory contains a simple playground application for the marker API.
 
 ## Get Started
 
-1. Change into the playground-folder and install dependencies:
+1.  Change into the playground-folder and install dependencies:
 
         cd examples/playground
         npm install
 
-2. [Create an API-key][gmp_create_apikey] for the Google Maps API.
-3. create a file `.env` with the API key in the following format:
+2.  [Create an API-key][gmp_create_apikey] for the Google Maps API.
+3.  create a file `.env` with the API key in the following format:
 
-       GOOGLE_MAPS_API_KEY="<INSERT API KEY HERE>"
+    GOOGLE_MAPS_API_KEY="<INSERT API KEY HERE>"
 
-4. start the development server:
+4.  start the development server:
 
-       npm start
+    npm start
 
-5. open http://localhost:5173 in your browser
+5.  open http://localhost:5173 in your browser
 
 [gmp_create_apikey]: https://developers.google.com/maps/documentation/embed/get-api-key#create-api-keys
 
@@ -31,14 +30,14 @@ marker-API can be written and executed to get a feel for the api and test
 different usage-scenarios in a fast way. The contents of the editor can be
 serialized into the URL for sharing.
 
-Compiling the typescript happens in a worker via the typescript-support
+Compiling the typescript from the editor happens in a worker via the typescript-support
 already built into the monaco-editor. For execution, a wrapper emulates the
-common.js environment to allow importing a predefined set of modules. Other
+common.js environment to allow importing a predefined set of modules. External
 modules can only be imported using async imports from urls.
 
 ## Code Organization
 
-- `/`: contains `index.html`, `examples.html` and configuration-files
+- `/`: contains `index.html` and configuration-files
 - `/src`: the typescript source-root. The application entrypoint is in `main.ts`
 - `/src/code-samples`: contains the source-files for all examples. The
   typescript files here should all follow the conventions for examples below.
@@ -49,35 +48,22 @@ modules can only be imported using async imports from urls.
 - each example should demonstrate a single aspect of the library in a
   concise way - try to remove 'noise', that is code for unrelated aspects,
   as much as possible, embrace duplication
-- the first line of the example has to contain a comment in the form:
-  `// title: This describes what it does` - this comment will be the text
-  shown in the example-index
 - the example must import components from the marker-library using regular
-  imports (e.g. `import {Marker} from '@ubilabs/google-maps-marker';`).
+  imports (e.g. `import {Marker} from '@googlemaps/adv-markers-utils';`).
 - there has to be a default export, which will be called with the
   map-instance as parameter when the script is run
 - When any changes are done in the browser environment (event-listeners,
   timeouts, intervals, ...), the exported function has to return a cleanup
-  function removing all those. This doesn't apply for created markers and
-  marker-collections, those are automatically removed from the map when a
-  new version of the script is executed.
+  function removing all those. For convenience, this does not apply for
+  created markers and marker-collections, those are automatically removed
+  from the map when a new version of the script is executed.
 
 ## scripts, npm-tasks and deployment
 
-The published version of this is hosted on google cloud storage and available
-here: https://storage.ubidev.net/marker-api-playground
-
-Be aware that people outside ubilabs have access to the deployed version
-and while we can actively develop and publish new versions, the deployed
-version should always be manually checked after a deployment.
-
 The following supporting scripts and tasks are available:
 
-- `npm start`: starts the vite dev-server (this will also run the `build:dts`
-  and `build:examples` tasks)
+- `npm start`: starts the vite dev-server
 - `npm run build`: runs all `build:*` tasks followed by `vite build` to
   generate the full application in `./dist`
 - `npm run preview`: runs the full build and starts the vite preview server
   to review everything as if it were in production
-- `npm run deploy`: deploys the application to google cloud storage bucket
-  `gs://storage.ubidev.net/marker-api-playground`
diff --git a/examples/playground/package.json b/examples/playground/package.json
@@ -6,7 +6,6 @@
     "build:lib": "cd ../.. && npm run build",
     "build": "run-p build:* && vite build",
     "preview": "run-s build && vite preview",
-    "deploy": "run-s build && gsutil -m rsync -rc ./dist/ gs://geo-devrel-public-buckets/adv-markers-util-playground/",
     "serve": "vite",
     "watch:library": "cd ../.. && npm run watch"
   },

diff --git a/examples/typescript/.gitignore b/examples/typescript/.gitignore
@@ -0,0 +1 @@
+/node_modules
diff --git a/examples/typescript/README.md b/examples/typescript/README.md
@@ -0,0 +1,13 @@
+# Advanced Markers Utils – TypeScript / vite Example
+
+This directory contains a minimal example application built with typescript/vite.
+
+To run these examples, you need [a Google Maps API Key][gmp_apikey]. change into the `./examples/typescript`-directory and run
+
+    npm install
+    npm start
+
+This will start the vite development-server, and print the URL to the console (typically http://localhost:5173/).
+When opening the site, it will ask for the Google Maps API Key.
+
+[gmp_apikey]: https://developers.google.com/maps/documentation/javascript/get-api-key#create-api-keys
diff --git a/examples/typescript/env.d.ts b/examples/typescript/env.d.ts
@@ -0,0 +1,23 @@
+/*
+ * Copyright 2023 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/// <reference types="vite/client" />
+interface ImportMetaEnv {
+  readonly VITE_GOOGLEMAPS_API_KEY: string;
+}
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
diff --git a/examples/typescript/index.html b/examples/typescript/index.html
@@ -0,0 +1,36 @@
+<!doctype html>
+<!--
+ Copyright 2023 Google LLC
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>@googlemaps/marker - vite / typescript example</title>
+    <style>
+      body {
+        margin: 0;
+      }
+      #map {
+        width: 100vw;
+        height: 100vh;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="map"></div>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>
diff --git a/examples/typescript/main.ts b/examples/typescript/main.ts
@@ -0,0 +1,64 @@
+/*
+ * Copyright 2023 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {Loader} from '@googlemaps/js-api-loader';
+import {Marker} from '@googlemaps/adv-markers-utils';
+
+const mapDiv = document.querySelector('#map') as HTMLElement;
+
+async function main() {
+  const apiKey = getApiKey();
+  console.log('loading maps API with key: ' + apiKey);
+
+  const loader = new Loader({apiKey});
+
+  const {Map} = await loader.importLibrary('maps');
+  await loader.importLibrary('marker');
+
+  const map = new Map(mapDiv, {
+    mapId: 'bf51a910020fa25a',
+    center: {lat: 53.55, lng: 10.01},
+    zoom: 12
+  });
+
+  const marker = new Marker();
+
+  marker.position = {lat: 53.55, lng: 10.01};
+  marker.map = map;
+}
+
+// get Google Maps API Key from url or environment
+function getApiKey() {
+  const url = new URL(location.href);
+  const apiKey =
+    url.searchParams.get('apiKey') || import.meta.env.VITE_GOOGLEMAPS_API_KEY;
+
+  if (!apiKey) {
+    const key = prompt(
+      'Please provide your Google Maps API key in the URL\n' +
+        '(using the parameter `?apiKey=YOUR_API_KEY_HERE`) or enter it here:'
+    );
+
+    if (key) {
+      url.searchParams.set('apiKey', key);
+      location.replace(url.toString());
+    }
+  }
+
+  return apiKey;
+}
+
+main().catch(err => console.error(err));