Deploy andrewgryan/leaflet-html to andrewgryan/leaflet-html:gh-pages

andrewgryan · May 16, 2024 · 1307fe1 · 1307fe1
commit 1307fe1
Show file tree

Hide file tree

Showing 19 changed files with 697 additions and 0 deletions.
diff --git a/404.html b/404.html
@@ -0,0 +1,3 @@
+<!doctype html>
+<title>404 Not Found</title>
+<h1>404 Not Found</h1>
diff --git a/articles/basic/index.html b/articles/basic/index.html
@@ -0,0 +1,122 @@
+
+
+
+<!DOCTYPE html>
+<html>
+<head lang="en">
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <style>
+  </style>
+    <link rel="stylesheet" href="/style.css" />
+    <link rel="stylesheet" href="/leaflet-html/style.css" />
+    <link
+      rel="stylesheet"
+      href="https://unpkg.com/[email protected]/dist/leaflet.css"
+      integrity="sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY="
+      crossorigin=""
+    />
+    <script type="importmap">
+      {
+        "imports": {
+          "leaflet": "https://unpkg.com/[email protected]/dist/leaflet-src.esm.js",
+          "leaflet-html": "https://unpkg.com/leaflet-html@latest/dist/leaflet-html.js"
+        }
+      }
+    </script>
+    <script type="module">
+      import "leaflet-html";
+    </script>
+    <script src="https://code.iconify.design/iconify-icon/2.1.0/iconify-icon.min.js"></script>
+</head>
+<body>
+<nav>
+  <a href="https://andrewgryan.github.io/leaflet-html/"><iconify-icon icon="mdi:home"></iconify-icon> Home</a>
+  <a href="https://andrewgryan.github.io/leaflet-html/articles/"><iconify-icon icon="material-symbols:article-outline-sharp"></iconify-icon> Articles</a>
+</nav>
+
+<main>
+  <h1>Basic usage</h1>
+  <p>The minimal <code>leaflet-html</code> app is a basemap centered and zoomed on a location.</p>
+<pre data-lang="html" style="background-color:#2b303b;color:#c0c5ce;" class="language-html "><code class="language-html" data-lang="html"><span>&lt;</span><span style="color:#bf616a;">l-map </span><span style="color:#d08770;">center</span><span>=&quot;</span><span style="color:#a3be8c;">[53, 0]</span><span>&quot; </span><span style="color:#d08770;">zoom</span><span>=&quot;</span><span style="color:#a3be8c;">4</span><span>&quot;&gt;
+</span><span>  &lt;</span><span style="color:#bf616a;">l-tile-layer
+</span><span>    </span><span style="color:#d08770;">url-template</span><span>=&quot;</span><span style="color:#a3be8c;">https://{s}.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}{r}.png</span><span>&quot;
+</span><span>  &gt;&lt;/</span><span style="color:#bf616a;">l-tile-layer</span><span>&gt;
+</span><span>&lt;/</span><span style="color:#bf616a;">l-map</span><span>&gt;
+</span></code></pre>
+<l-map center="[53, 0]" zoom="4">
+  <l-tile-layer
+    url-template="https://{s}.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}{r}.png"
+  ></l-tile-layer>
+</l-map>
+<p>To add the above widget to a HTML document both JS and CSS tags need to be included in the <code>&lt;head&gt;</code> of the page.</p>
+<h2 id="assets">Assets</h2>
+<p>Basic HTML recommended settings, e.g. <code>charset</code>, <code>lang</code>, and <code>viewport</code> to help with cross device support.
+Can be placed in the <code>&lt;head&gt;</code> tag, along with CSS and JS assets.</p>
+<pre data-lang="html" style="background-color:#2b303b;color:#c0c5ce;" class="language-html "><code class="language-html" data-lang="html"><span>&lt;</span><span style="color:#bf616a;">head </span><span style="color:#d08770;">lang</span><span>=&quot;</span><span style="color:#a3be8c;">en</span><span>&quot;&gt;
+</span><span>  &lt;</span><span style="color:#bf616a;">meta </span><span style="color:#d08770;">charset</span><span>=&quot;</span><span style="color:#a3be8c;">utf-8</span><span>&quot; /&gt;
+</span><span>  &lt;</span><span style="color:#bf616a;">meta </span><span style="color:#d08770;">name</span><span>=&quot;</span><span style="color:#a3be8c;">viewport</span><span>&quot; </span><span style="color:#d08770;">content</span><span>=&quot;</span><span style="color:#a3be8c;">width=device-width, initial-scale=1</span><span>&quot; /&gt;
+</span><span>&lt;/</span><span style="color:#bf616a;">head</span><span>&gt;
+</span></code></pre>
+<h3 id="leaflet">Leaflet</h3>
+<p>Leaflet is an external dependency of <code>leaflet-html</code>, as such,
+the standard Leaflet assets should be included.</p>
+<pre data-lang="html" style="background-color:#2b303b;color:#c0c5ce;" class="language-html "><code class="language-html" data-lang="html"><span>&lt;</span><span style="color:#bf616a;">head</span><span>&gt;
+</span><span>...
+</span><span>&lt;</span><span style="color:#bf616a;">link
+</span><span>  </span><span style="color:#d08770;">rel</span><span>=&quot;</span><span style="color:#a3be8c;">stylesheet</span><span>&quot;
+</span><span>  </span><span style="color:#d08770;">href</span><span>=&quot;</span><span style="color:#a3be8c;">https://unpkg.com/[email protected]/dist/leaflet.css</span><span>&quot;
+</span><span>  </span><span style="color:#d08770;">integrity</span><span>=&quot;</span><span style="color:#a3be8c;">sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY=</span><span>&quot;
+</span><span>  </span><span style="color:#d08770;">crossorigin</span><span>=&quot;&quot;
+</span><span>/&gt;
+</span><span>...
+</span><span>&lt;/</span><span style="color:#bf616a;">head</span><span>&gt;
+</span></code></pre>
+<h3 id="leaflet-html">Leaflet-HTML</h3>
+<p>Leaflet-HTML is available via <strong>npm</strong> and <strong>unpkg</strong>.
+To get started quickly, use the CDN version available on <strong>unpkg</strong>.</p>
+<pre data-lang="html" style="background-color:#2b303b;color:#c0c5ce;" class="language-html "><code class="language-html" data-lang="html"><span>&lt;</span><span style="color:#bf616a;">script </span><span style="color:#d08770;">type</span><span>=&quot;</span><span style="color:#a3be8c;">importmap</span><span>&quot;&gt;
+</span><span>  {
+</span><span>    &quot;imports&quot;: {
+</span><span>      &quot;leaflet&quot;: &quot;https://unpkg.com/[email protected]/dist/leaflet-src.esm.js&quot;,
+</span><span>      &quot;leaflet-html&quot;: &quot;https://unpkg.com/leaflet-html@latest/dist/leaflet-html.js&quot;
+</span><span>    }
+</span><span>  }
+</span><span>&lt;/</span><span style="color:#bf616a;">script</span><span>&gt;
+</span></code></pre>
+<pre data-lang="html" style="background-color:#2b303b;color:#c0c5ce;" class="language-html "><code class="language-html" data-lang="html"><span>&lt;</span><span style="color:#bf616a;">script </span><span style="color:#d08770;">type</span><span>=&quot;</span><span style="color:#a3be8c;">module</span><span>&quot;&gt;
+</span><span>  </span><span style="color:#b48ead;">import </span><span>&quot;</span><span style="color:#a3be8c;">leaflet-html</span><span>&quot;;
+</span><span>&lt;/</span><span style="color:#bf616a;">script</span><span>&gt;
+</span></code></pre>
+<p>The <code>@latest</code> keyword should keep your site up to date during development.</p>
+<h2 id="minimal-style">Minimal style</h2>
+<p>By default Custom elements are <code>display: inline</code>,
+meaning they are unaffected by <code>height</code>.
+Add the following ruleset to your stylesheet to enable map size.</p>
+<pre data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#bf616a;">l-map </span><span>{
+</span><span>  display: block;
+</span><span>}
+</span></code></pre>
+<p>It's not always necessary to set <code>block</code> directly on an <code>l-map</code> tag.
+For example, a parent with <code>display: grid</code>, will size the <code>l-map</code> tag appropriately.</p>
+<h3 id="z-index">Z-index</h3>
+<p>Leaflet has fairly strong <code>z-index</code> settings that are not easy to override.
+The easiest way to get around them is to start a new stacking context using <code>isolation: isolate</code>.</p>
+<h3 id="sensible-defaults">Sensible defaults</h3>
+<p>Without knowing anything specific about your application the following settings should be a good starting place.</p>
+<pre data-lang="css" style="background-color:#2b303b;color:#c0c5ce;" class="language-css "><code class="language-css" data-lang="css"><span style="color:#bf616a;">l-map </span><span>{
+</span><span>  display: block;
+</span><span>  block-size: </span><span style="color:#d08770;">40ch</span><span>;
+</span><span>  isolation: isolate;
+</span><span>  z-index: </span><span style="color:#d08770;">1</span><span>;
+</span><span>}
+</span></code></pre>
+<p>This allows overlaying your own UI elements and gives full control over size and position of each map on the page.</p>
+
+</main>
+
+<footer>
+  <div class="logo">Leaflet-HTML</div>
+</footer>
+</body>
+</html>
diff --git a/articles/htmx/index.html b/articles/htmx/index.html
@@ -0,0 +1,120 @@
+
+
+
+<!DOCTYPE html>
+<html>
+<head lang="en">
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <style>
+  </style>
+    <link rel="stylesheet" href="/style.css" />
+    <link rel="stylesheet" href="/leaflet-html/style.css" />
+    <link
+      rel="stylesheet"
+      href="https://unpkg.com/[email protected]/dist/leaflet.css"
+      integrity="sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY="
+      crossorigin=""
+    />
+    <script type="importmap">
+      {
+        "imports": {
+          "leaflet": "https://unpkg.com/[email protected]/dist/leaflet-src.esm.js",
+          "leaflet-html": "https://unpkg.com/leaflet-html@latest/dist/leaflet-html.js"
+        }
+      }
+    </script>
+    <script type="module">
+      import "leaflet-html";
+    </script>
+    <script src="https://code.iconify.design/iconify-icon/2.1.0/iconify-icon.min.js"></script>
+</head>
+<body>
+<nav>
+  <a href="https://andrewgryan.github.io/leaflet-html/"><iconify-icon icon="mdi:home"></iconify-icon> Home</a>
+  <a href="https://andrewgryan.github.io/leaflet-html/articles/"><iconify-icon icon="material-symbols:article-outline-sharp"></iconify-icon> Articles</a>
+</nav>
+
+<main>
+  <h1>Working with HTMX</h1>
+  <p>To add HTMX to a project.
+Add a script tag to pull the library into your page.</p>
+<pre data-lang="html" style="background-color:#2b303b;color:#c0c5ce;" class="language-html "><code class="language-html" data-lang="html"><span>&lt;</span><span style="color:#bf616a;">script </span><span style="color:#d08770;">src</span><span>=&quot;</span><span style="color:#a3be8c;">https://unpkg.com/[email protected]</span><span>&quot;&gt;&lt;/</span><span style="color:#bf616a;">script</span><span>&gt;
+</span><span style="color:#65737e;">&lt;!-- have a button POST a click via AJAX --&gt;
+</span><span>&lt;</span><span style="color:#bf616a;">button </span><span style="color:#d08770;">hx-get</span><span>=&quot;</span><span style="color:#a3be8c;">/clicked</span><span>&quot; </span><span style="color:#d08770;">hx-swap</span><span>=&quot;</span><span style="color:#a3be8c;">outerHTML</span><span>&quot;&gt;
+</span><span>  Click Me
+</span><span>&lt;/</span><span style="color:#bf616a;">button</span><span>&gt;
+</span></code></pre>
+<script src="https://unpkg.com/[email protected]"></script>
+<button hx-get=https://andrewgryan.github.io/leaflet-html/htmx/clicked.html
+ hx-swap="outerHTML">
+  Click Me
+</button>
+<h2 id="use-with-leaflet-html">Use with Leaflet-HTML</h2>
+<p>The principles that govern HTMX development also hold for Leaflet-HTML.
+A button that requests HTML to replace part of the document should update the map.</p>
+<pre data-lang="html" style="background-color:#2b303b;color:#c0c5ce;" class="language-html "><code class="language-html" data-lang="html"><span style="color:#65737e;">&lt;!-- Initial map --&gt;
+</span><span>&lt;</span><span style="color:#bf616a;">l-map </span><span style="color:#d08770;">center</span><span>=&quot;</span><span style="color:#a3be8c;">[55,-5]</span><span>&quot; </span><span style="color:#d08770;">zoom</span><span>=&quot;</span><span style="color:#a3be8c;">4</span><span>&quot;&gt;
+</span><span>  &lt;</span><span style="color:#bf616a;">l-tile-layer
+</span><span>    </span><span style="color:#d08770;">url-template</span><span>=&quot;</span><span style="color:#a3be8c;">https://{s}.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}{r}.png</span><span>&quot;
+</span><span>  &gt;&lt;/</span><span style="color:#bf616a;">l-tile-layer</span><span>&gt;
+</span><span>&lt;/</span><span style="color:#bf616a;">l-map</span><span>&gt;
+</span><span>
+</span><span style="color:#65737e;">&lt;!-- Tiles --&gt;
+</span><span>&lt;</span><span style="color:#bf616a;">button </span><span style="color:#d08770;">hx-get</span><span>=&quot;</span><span style="color:#a3be8c;">/tile-osm.html</span><span>&quot; </span><span style="color:#d08770;">hx-target</span><span>=&quot;</span><span style="color:#a3be8c;">l-tile-layer</span><span>&quot; </span><span style="color:#d08770;">hx-swap</span><span>=&quot;</span><span style="color:#a3be8c;">outerHTML</span><span>&quot;&gt;
+</span><span>  OSM
+</span><span>&lt;/</span><span style="color:#bf616a;">button</span><span>&gt;
+</span><span>&lt;</span><span style="color:#bf616a;">button </span><span style="color:#d08770;">hx-get</span><span>=&quot;</span><span style="color:#a3be8c;">/tile-voyager.html</span><span>&quot; </span><span style="color:#d08770;">hx-target</span><span>=&quot;</span><span style="color:#a3be8c;">l-tile-layer</span><span>&quot; </span><span style="color:#d08770;">hx-swap</span><span>=&quot;</span><span style="color:#a3be8c;">outerHTML</span><span>&quot;&gt;
+</span><span>  Voyager
+</span><span>&lt;/</span><span style="color:#bf616a;">button</span><span>&gt;
+</span><span>&lt;</span><span style="color:#bf616a;">button </span><span style="color:#d08770;">hx-get</span><span>=&quot;</span><span style="color:#a3be8c;">/tile-esri.html</span><span>&quot; </span><span style="color:#d08770;">hx-target</span><span>=&quot;</span><span style="color:#a3be8c;">l-tile-layer</span><span>&quot; </span><span style="color:#d08770;">hx-swap</span><span>=&quot;</span><span style="color:#a3be8c;">outerHTML</span><span>&quot;&gt;
+</span><span>  ESRI
+</span><span>&lt;/</span><span style="color:#bf616a;">button</span><span>&gt;
+</span><span>
+</span><span style="color:#65737e;">&lt;!-- Marker --&gt;
+</span><span>&lt;</span><span style="color:#bf616a;">button </span><span style="color:#d08770;">hx-get</span><span>=&quot;</span><span style="color:#a3be8c;">/marker.html</span><span>&quot; </span><span style="color:#d08770;">hx-target</span><span>=&quot;</span><span style="color:#a3be8c;">l-map</span><span>&quot; </span><span style="color:#d08770;">hx-swap</span><span>=&quot;</span><span style="color:#a3be8c;">beforeend</span><span>&quot;&gt;
+</span><span>  Add marker
+</span><span>&lt;/</span><span style="color:#bf616a;">button</span><span>&gt;
+</span><span>&lt;</span><span style="color:#bf616a;">button </span><span style="color:#d08770;">hx-get</span><span>=&quot;</span><span style="color:#a3be8c;">/marker.html</span><span>&quot; </span><span style="color:#d08770;">hx-target</span><span>=&quot;</span><span style="color:#a3be8c;">l-marker</span><span>&quot; </span><span style="color:#d08770;">hx-swap</span><span>=&quot;</span><span style="color:#a3be8c;">delete</span><span>&quot;&gt;
+</span><span>  Delete marker
+</span><span>&lt;/</span><span style="color:#bf616a;">button</span><span>&gt;
+</span></code></pre>
+<l-map center="[55,-5]" zoom="4">
+  <l-tile-layer
+    url-template="https://{s}.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}{r}.png"
+  ></l-tile-layer>
+</l-map>
+<button hx-get=https://andrewgryan.github.io/leaflet-html/htmx/tile-osm.html
+ hx-target="l-tile-layer" hx-swap="outerHTML">
+  OSM
+</button>
+<button hx-get=https://andrewgryan.github.io/leaflet-html/htmx/tile-voyager.html
+ hx-target="l-tile-layer" hx-swap="outerHTML">
+  Voyager
+</button>
+<button hx-get=https://andrewgryan.github.io/leaflet-html/htmx/tile-esri.html
+ hx-target="l-tile-layer" hx-swap="outerHTML">
+  ESRI
+</button>
+<button hx-get=https://andrewgryan.github.io/leaflet-html/htmx/marker.html
+ hx-target="l-map" hx-swap="beforeend">
+  Add marker
+</button>
+<button hx-get=https://andrewgryan.github.io/leaflet-html/htmx/marker.html
+ hx-target="l-marker" hx-swap="delete">
+  Delete marker
+</button>
+<p>The above approach works by triggering the change handlers in the <code>&lt;l-tile-layer&gt;</code> custom element.
+The additional HTML tags generated by Leaflet are also inside the <code>&lt;l-map&gt;</code> tag.
+Care should be taken to not <code>hx-swap</code> the tags governed by Leaflet.</p>
+<p>All Leaflet-HTML tags, e.g. <code>&lt;l-marker&gt;</code>, <code>&lt;l-icon&gt;</code>, etc. can be swapped however you like.
+It is just the contents of <code>&lt;l-map&gt;</code> that needs careful consideration.</p>
+<p>A more elegant mechanism in the future will make it clear which part of the document is controlled by Leaflet.</p>
+
+</main>
+
+<footer>
+  <div class="logo">Leaflet-HTML</div>
+</footer>
+</body>
+</html>