Merge pull request #214 from Dataport/add-meldemichel-embedded-scenario

add embedded scenario for meldemichel
Dataport · Jan 21, 2025 · 8dee461 · 8dee461
2 parents 68a4f86 + f4477c7
commit 8dee461
Show file tree

Hide file tree

Showing 3 changed files with 176 additions and 1 deletion.
diff --git a/packages/clients/meldemichel/API.md b/packages/clients/meldemichel/API.md
@@ -136,8 +136,54 @@ A document rendering the map client could e.g. look like this:
 </html>
 ```
 
-## Rendering COMPLETE mode
+## Rendering COMPLETE mode (full page)
 
 The `index.html` included in the package's `dist` folder has been prepared for this mode and must merely be hosted.
 
 Please see the table in chapter `Basic usage` about configuration options.
+
+## Rendering COMPLETE mode (embedded element)
+
+To embed the COMPLETE mode map on any page, provide a div with an id like `meldemichel-map-client`; you may choose any id you like.
+
+The following script tag can then be used to render the productive services of the Meldemichel map client.
+
+```html
+<script type="module">
+  // adjust path to where the client is
+  import meldemichelMapClient from '../dist/client-meldemichel.js'
+
+  meldemichelMapClient.createMap({
+    containerId: 'meldemichel-map-client', // the id you used
+    mode: 'COMPLETE',
+    afmUrl: `https://afm.hamburg.de/intelliform/forms/mml_melde_michel/standard/mml_melde_michel/index`,
+    reportServiceId: '6059',
+    configOverride: {
+      // adjust path to where the client is
+      stylePath: '../dist/style.css'
+    }
+  })
+</script>
+```
+
+POLAR will rebuild the given div to contain a ShadowDOM that hosts the map. The outer div will change to have the id `meldemichel-map-client-wrapper` (resp. `${yourId}-wrapper`) and can be used to style the map's height and width with, for example:
+
+```css
+#meldemichel-map-client-wrapper {
+  /* "position: relative;" is the minimum required styling */
+  position: relative;
+  height: 400px;
+  width: 100%;
+}
+```
+
+To also serve users with JS disabled some content, this fragment is common:
+
+```html
+<div id="meldemichel-map-client">
+  <!-- Optional, if your page does not have its own <noscript> information -->
+  <noscript>Please use a browser with active JavaScript to use the map client.</noscript>
+</div>
+```
+
+For a complete example, you may also check [the running embedded scenario](https://dataport.github.io/polar/docs/meldemichel/example/complete_embedded.html) or its [source file](https://github.com/Dataport/polar/blob/main/packages/clients/meldemichel/example/complete_embedded.html).
diff --git a/packages/clients/meldemichel/example/complete_embedded.html b/packages/clients/meldemichel/example/complete_embedded.html
@@ -0,0 +1,125 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"
+    />
+    <meta
+      http-equiv="Cache-Control"
+      content="no-cache, no-store, must-revalidate, max-age=0"
+    />
+    <title>MML INTEGRATION TEST</title>
+    <style>
+      /* div with this id is created on `createMap` call to host shadow DOM */
+      #polarstern-wrapper {
+        position: relative;
+        height: 400px;
+        width: 100%;
+      }
+
+      /* the following styling is purely for surrounding example content */
+      html, body {
+        margin: 0;
+        padding: 0;
+        font-family: sans-serif;
+      }
+
+      header {
+        padding: 0 2em;
+      }
+
+      #hh-bug {
+        height: 35px;
+        width: 400px;
+        margin-left: -280px;
+        transform: skew(-35deg);
+        background: #e10019;
+        border-bottom-right-radius: 6px;
+        margin-bottom: 1em;
+      }
+
+      main {
+        display: flex;
+        flex-direction: column;
+        gap: 2em;
+      }
+
+      .blue-content {
+        color: white;
+        background: #1a4573;
+      }
+
+      .padded-x {
+        padding-right: 10vw;
+        padding-left: 10vw;
+      }
+
+      .padded-y {
+        padding-top: 4em;
+        padding-bottom: 4em;
+      }
+
+      h2 {
+        font-size: 38pt;
+      }
+
+      p {
+        font-size: 32px;
+      }
+
+      footer {
+        color: white;
+        background: #003063;
+        padding: 1em 5vw;
+      }
+    </style>
+  </head>
+  <body>
+    <nav></nav>
+    <header>
+      <h1>Meldemichel-Einbindesimulation</h1>
+    </header>
+    <div id="hh-bug"></div>
+    <main>
+      <section class="blue-content padded-x padded-y">
+        <h2>Blindtext</h2>
+        <p>Li Europan lingues es membres del sam familie. Lor separat existentie es un myth. Por scientie, musica, sport etc, litot Europa usa li sam vocabular.</p>
+      </section>
+      <section>
+        <h2 class="padded-x">Aktuell gemeldete Schäden</h2>
+        <!-- ID can be anything as long as it's used in .createMap, too -->
+        <div id="polarstern"></div>
+      </section>
+      <section class="padded-x padded-y">
+        <h2>Blindtext II.</h2>
+        <p>Li lingues differe solmen in li grammatica, li pronunciation e li plu commun vocabules. Omnicos directe al desirabilite de un nov lingua franca: On refusa continuar payar custosi traductores.</p>
+      </section>
+    </main>
+    <footer>At solmen va esser necessi far uniform grammatica, pronunciation e plu sommun paroles.</footer>
+    <script type="module">
+      import meldemichelMapClient from '../dist/client-meldemichel.js'
+
+      // toggle to switch between stage/prod layer and report system
+      const stage = true
+
+      meldemichelMapClient.createMap({
+        containerId: 'polarstern',
+        mode: 'COMPLETE',
+        afmUrl: `https://${
+          stage ? 'stage.' : ''
+        }afm.hamburg.de/intelliform/forms/mml_melde_michel/standard/mml_melde_michel/index`,
+        reportServiceId: stage ? '6061' : '6059',
+        configOverride: {
+          stylePath: '../dist/style.css',
+          attributions: {
+            staticAttributions: [
+              `<a href="https://github.com/Dataport/polar/blob/main/LEGALNOTICE.md">Legal Notice (Impressum)</a>`
+            ]
+          }
+        }
+      })
+    </script>
+  </body>
+</html>
diff --git a/packages/clients/meldemichel/example/index.html b/packages/clients/meldemichel/example/index.html
@@ -38,6 +38,10 @@ <h1>Meldemichel Example Hub</h1>
         <a href="./complete.html">"COMPLETE" (Übersichtskarte)</a>
       </dt>
       <dd>Meldemichel Map Client rendered fullpage in mode COMPLETE.</dd>
+      <dt>
+        <a href="./complete_embedded.html">"COMPLETE_EMBEDDED" (Übersichtskarte eingebettet)</a>
+      </dt>
+      <dd>Meldemichel Map Client rendered as page element in mode COMPLETE.</dd>
       <dt>
         <a href="../dist/index.html"
           >"COMPLETE" (Übersichtskarte) – Production Mode Test</a