Skip to content

Commit

Permalink
deploy: 722a499
Browse files Browse the repository at this point in the history
  • Loading branch information
@ludoholic
ludoholic committed Aug 20, 2024
1 parent 446e6f1 commit e7fd265
Show file tree
Hide file tree
Showing 87 changed files with 649 additions and 649 deletions.
12 changes: 6 additions & 6 deletions docs/afm/client-afm.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,21 +22,21 @@
</head>
<body>
<article class="markdown-body">
<h1>POLAR AfM map client</h1>
<h1 id="polar-afm-map-client" tabindex="-1">POLAR AfM map client</h1>
<p>This is a default compilation of POLAR feature packages for online services. This document and its child documents describe the setup.</p>

<h2>Requirements</h2>
<h2 id="requirements" tabindex="-1">Requirements</h2>
<p>To understand this document, programming knowledge (preferably in JavaScript) are required. This is a technical document describing how to integrate the map client with its programmatic API.</p>
<h2>Versioning</h2>
<h2 id="versioning" tabindex="-1">Versioning</h2>
<p>The map client honors <a href="https://semver.org/lang/de/">SemVer</a> versioning. Breaking Changes without a change in leading version number are bugs.</p>
<h2>Library integration</h2>
<h2 id="library-integration" tabindex="-1">Library integration</h2>
<p>You may either use the AfM client with import syntax or via HTML tags. In the following, the integration via HTML is shown.</p>
<pre><code class="language-html">&lt;script src=&quot;&lt;Path&gt;/dist/polar-client.js&quot;&gt;&lt;/script&gt;
</code></pre>
<p>The global variable <code>MapClient</code> is now available. All other files in the dist folder are pulled on demand by relative pathing.</p>
<h2>Configuration and creation</h2>
<h2 id="configuration-and-creation" tabindex="-1">Configuration and creation</h2>
<p>The map client can be controlled with a configuration object. An example file is supplied in the folder <code>example</code>. This file can be used as base for your own configuration.</p>
<h3>Programmatic integration</h3>
<h3 id="programmatic-integration" tabindex="-1">Programmatic integration</h3>
<p>The following is an abstract example.</p>
<p>In your HTML, a div with unique ID is required that holds the following style properties. Width and height can be changed as you need, but are required to be defined.</p>
<pre><code class="language-html">&lt;div
Expand Down
38 changes: 19 additions & 19 deletions docs/afm/core.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,24 +22,24 @@
</head>
<body>
<article class="markdown-body">
<h1>Core</h1>
<h2>Scope</h2>
<h1 id="core" tabindex="-1">Core</h1>
<h2 id="scope" tabindex="-1">Scope</h2>
<p>The client's core is the base package to create clients in the POLAR environment.</p>
<p>It offers this functionality:</p>
<ul>
<li>Plugin mechanism</li>
<li>@masterportal/masterportalapi functionality</li>
<li>Localization mechanism</li>
</ul>
<h2>Interaction</h2>
<h2 id="interaction" tabindex="-1">Interaction</h2>
<p>If a client is rendered as part of another page, the zoom and drag-pan behaviour is different to if the client is rendered as complete page.<br>
If it's part of another page, drag-panning on mobile devices is only usable if at least two fingers are being used while on desktop clients the user can only zoom if using the respective platform modifier key (e.g. CTRL).</p>
<p>It is important to note that the behaviour will be desktop-like on larger touchscreen devices (e.g. tablets).</p>
<h2>Initialization / Configuration</h2>
<h2 id="initialization-%2F-configuration" tabindex="-1">Initialization / Configuration</h2>
<p>It depends on the client how exactly the initialization will take place for the embedding programmer. However, the core mechanism remains the same.</p>
<p>The exported default object is an extended masterportalAPI, adding the <code>addPlugins</code> and extending the <code>createMap</code> functions. For masterportalAPI details, <a href="https://bitbucket.org/geowerkstatt-hamburg/masterportalapi/src/master/">see their repository</a>.</p>
<p>To be able to see the map in production mode, the imported stylesheet has to have the property <code>data-polar</code>. The value can be chosen arbitrarily. ⚠️ Deprecated. The new field 'stylePath' should be used instead.</p>
<h3>addPlugins</h3>
<h3 id="addplugins" tabindex="-1">addPlugins</h3>
<p>Before instantiating the map, all required plugins have to be added. Depending on how you use POLAR, this may already have been done. Ready-made clients (that is, packages prefixed <code>@polar/client-</code>) come with plugins prepared. You may add further plugins or proceed with <code>createMap</code>.</p>
<p>In case you're integrating new plugins, call <code>addPlugins</code> with an array of instances.</p>
<pre><code class="language-js">client.addPlugins([Plugin({ pluginConfig })])
Expand All @@ -55,7 +55,7 @@ <h3>addPlugins</h3>
})
</code></pre>
<p>If the storeModule features a <code>setupModule</code> action, it will be executed automatically after initialization.</p>
<h3>createMap</h3>
<h3 id="createmap" tabindex="-1">createMap</h3>
<p>The map is created by calling the <code>createMap</code> method. Depending on how you use POLAR, this may already have been done, as some clients come as ready-made standalone HTML pages that do this for you.</p>
<pre><code class="language-js">MapClient.createMap({
// arbitrary id, must point to a div
Expand All @@ -66,7 +66,7 @@ <h3>createMap</h3>
/* Your Code, e.g. for setting up callbacks. */
})
</code></pre>
<h4>mapConfiguration</h4>
<h4 id="mapconfiguration" tabindex="-1">mapConfiguration</h4>
<p>The mapConfiguration allows controlling many client instance details.</p>
<table>
<thead>
Expand Down Expand Up @@ -124,7 +124,7 @@ <h4>mapConfiguration</h4>
</tr>
</tbody>
</table>
<h5>mapConfiguration.LanguageOption</h5>
<h5 id="mapconfiguration.languageoption" tabindex="-1">mapConfiguration.LanguageOption</h5>
<p>A language option is an object consisting of a type (its language key) and the i18next resource definition. You may e.g. decide that the texts offered in the LayerChooser do not fit the style of your client, or that they could be more precise in your situation since you're only using <em>very specific</em> overlays.</p>
<p>An example for a LanguageOption array usable in <code>createMap</code> is this array:</p>
<pre><code class="language-ts">const languageOptions: LanguageOption[] = [
Expand All @@ -151,7 +151,7 @@ <h5>mapConfiguration.LanguageOption</h5>
]
</code></pre>
<p>To figure out the name of the locales to override, inspect the matching plugin in GitHub's file browser. In <code>packages/plugins</code>, open the plugin you desire to override. Each plugin's <code>src</code> folder contains a <code>language.ts</code> listing all used locale keys with appropriate nesting.</p>
<h5>mapConfiguration.extendedMasterportalapiMarkers</h5>
<h5 id="mapconfiguration.extendedmasterportalapimarkers" tabindex="-1">mapConfiguration.extendedMasterportalapiMarkers</h5>
<table>
<thead>
<tr>
Expand Down Expand Up @@ -193,7 +193,7 @@ <h5>mapConfiguration.extendedMasterportalapiMarkers</h5>
</tr>
</tbody>
</table>
<h6>mapConfiguration.extendedMasterportalapiMarkers.MarkerStyle</h6>
<h6 id="mapconfiguration.extendedmasterportalapimarkers.markerstyle" tabindex="-1">mapConfiguration.extendedMasterportalapiMarkers.MarkerStyle</h6>
<table>
<thead>
<tr>
Expand Down Expand Up @@ -281,15 +281,15 @@ <h6>mapConfiguration.extendedMasterportalapiMarkers.MarkerStyle</h6>
</tbody>
</table>
</blockquote>
<h5>mapConfiguration.LayerConf</h5>
<h5 id="mapconfiguration.layerconf" tabindex="-1">mapConfiguration.LayerConf</h5>
<p>The layer configuration (or: service register) is read by the masterportalAPI. The full definition can be read <a href="https://bitbucket.org/geowerkstatt-hamburg/masterportal/src/dev/doc/services.json.md">here</a>.</p>
<p>However, not all listed services have been implemented in the masterportalAPI yet, and no documentation regarding implemented properties exists there yet.</p>
<p>Whitelisted and confirmed parameters include:</p>
<ul>
<li>WMS: id, name, url, typ, format, version, transparent, layers, STYLES</li>
<li>WFS: id, name, url, typ, outputFormat, version, featureType</li>
</ul>
<h6>Example services register</h6>
<h6 id="example-services-register" tabindex="-1">Example services register</h6>
<pre><code class="language-json">[
{
&quot;id&quot;: &quot;my-wfs-id&quot;,
Expand All @@ -313,7 +313,7 @@ <h6>Example services register</h6>
]
</code></pre>
<p>Since this is the base for many functions, the service ID set in this is used to reference map material in many places of the map client.</p>
<h5>&lt;...masterportalAPI.fields&gt;</h5>
<h5 id="%3C...masterportalapi.fields%3E" tabindex="-1">&lt;...masterportalAPI.fields&gt;</h5>
<p>The <code>&lt;...masterportalAPI.fields&gt;</code> means that any masterportalAPI field may also be used here <em>directly</em>. The most common fields are the following ones; for more, see masterportalAPI.</p>
<table>
<thead>
Expand Down Expand Up @@ -356,10 +356,10 @@ <h5>&lt;...masterportalAPI.fields&gt;</h5>
</tr>
</tbody>
</table>
<h5>&lt;plugin.fields&gt;</h5>
<p>Plugins in POLAR are modular components that extend the functionality of the map client. They can be added using the <a href="#addPlugins">addPlugins</a> method and configured through the <code>mapConfiguration</code> object. Each plugin has its own set of fields and options that can be customized.</p>
<h5 id="%3Cplugin.fields%3E" tabindex="-1">&lt;plugin.fields&gt;</h5>
<p>Plugins in POLAR are modular components that extend the functionality of the map client. They can be added using the <a href="#addplugins">addPlugins</a> method and configured through the <code>mapConfiguration</code> object. Each plugin has its own set of fields and options that can be customized.</p>
<p>On how to configure a plugin, see the respective plugin. The configuration is given in the <code>mapConfiguration</code> object by the plugin's name as specified in its respective documentation.</p>
<h6>Global Plugin Parameters</h6>
<h6 id="global-plugin-parameters" tabindex="-1">Global Plugin Parameters</h6>
<p>Most plugins honor this additional field.</p>
<table>
<thead>
Expand All @@ -377,7 +377,7 @@ <h6>Global Plugin Parameters</h6>
</tr>
</tbody>
</table>
<h6>Example Configuration</h6>
<h6 id="example-configuration" tabindex="-1">Example Configuration</h6>
<p>For example, a <code>@polar/plugin-address-search</code> plugin can be configured like this:</p>
<pre><code class="language-js">{
addressSearch: {
Expand All @@ -387,7 +387,7 @@ <h6>Example Configuration</h6>
}
}
</code></pre>
<h5>mapConfiguration.vuetify</h5>
<h5 id="mapconfiguration.vuetify" tabindex="-1">mapConfiguration.vuetify</h5>
<p>These fields let you e.g. specify a <a href="https://vuetifyjs.com/en/features/theme/">Vuetify-Theme</a>. For more options, refer to the official vuetify documentation.</p>
<p>Additionally to the regular fields, <code>primaryContrast</code> and <code>secondaryContrast</code> are interpreted. They serve as contrast colors to their respective fields and are used for e.g. button icons.</p>
<pre><code class="language-js">{
Expand All @@ -403,7 +403,7 @@ <h5>mapConfiguration.vuetify</h5>
}
}
</code></pre>
<h2>Store</h2>
<h2 id="store" tabindex="-1">Store</h2>
<p>The core module features a vuex root store that all plugin vuex modules are plugged into. However, the root contents are only relevant to plugins. It is accessible with <code>map.$store</code>, and can be used as a starting point for plugin access.</p>
<p>To ease use, the map instance also features a <code>subscribe</code> method that will register a watcher to any state field. Please mind that only documented paths should be used, and all others are subject to change without notice.</p>
<pre><code class="language-js">// state subscription – listening to data held by the map client
Expand Down
40 changes: 20 additions & 20 deletions docs/afm/plugin-address-search.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,8 @@
</head>
<body>
<article class="markdown-body">
<h1>AddressSearch</h1>
<h2>Scope</h2>
<h1 id="addresssearch" tabindex="-1">AddressSearch</h1>
<h2 id="scope" tabindex="-1">Scope</h2>
<p>The AddressSearch plugin allows users to search for an address. If multiple addresses are returned by services, the user is prompted to select a result.</p>
<p>The plugin saves the chosen information as GeoJSON to the store so that following procedures may grab it or so that other plugins may use it.</p>
<p>Currently supported services:</p>
Expand All @@ -32,8 +32,8 @@ <h2>Scope</h2>
<li>WFS</li>
<li>Some gazetteers/WFS-G (please request a check or try yourself, not 100% done)</li>
</ul>
<h2>Configuration</h2>
<h3>addressSearch</h3>
<h2 id="configuration" tabindex="-1">Configuration</h2>
<h3 id="addresssearch-1" tabindex="-1">addressSearch</h3>
<p>The configuration allows defining and grouping services. Grouped services can be requested in a search at the same time, and one group of searches can be active at a time. When multiple searches are in a group, they may be extended with category information to make the results easier to browse.</p>
<p>It is advised to either use one-search-per-group <em>or</em> all services in a singular group to avoid an overly complex UI. Mixed configurations may be required for more complex search requirements.</p>
<p>In <code>categoryProperties</code> and <code>groupProperties</code>, id strings called <code>groupId</code> and <code>categoryId</code> are used. These are arbitrary strings you can introduce and reuse to group or categorize elements together. Regarding what groups and categories are, see further below.</p>
Expand Down Expand Up @@ -104,7 +104,7 @@ <h3>addressSearch</h3>
</tbody>
</table>
<p>For details on the <code>displayComponent</code> attribute, refer to the <a href="https://dataport.github.io/polar/docs/afm/core.html#global-plugin-parameters">Global Plugin Parameters</a> section of <code>@polar/core</code>.</p>
<h4>addressSearch.searchMethodsObject</h4>
<h4 id="addresssearch.searchmethodsobject" tabindex="-1">addressSearch.searchMethodsObject</h4>
<table>
<thead>
<tr>
Expand Down Expand Up @@ -156,7 +156,7 @@ <h4>addressSearch.searchMethodsObject</h4>
</tr>
</tbody>
</table>
<h4>addressSearch.customSearchMethod</h4>
<h4 id="addresssearch.customsearchmethod" tabindex="-1">addressSearch.customSearchMethod</h4>
<p>This is a function with the following signature:</p>
<pre><code>(
// should be used to actually abort request
Expand All @@ -170,7 +170,7 @@ <h4>addressSearch.customSearchMethod</h4>
) =&gt; Promise&lt;FeatureCollection&gt; | never
</code></pre>
<p>With this, arbitrary services can be supported.</p>
<h4>addressSearch.customSelectFunction</h4>
<h4 id="addresssearch.customselectfunction" tabindex="-1">addressSearch.customSelectFunction</h4>
<p>This is a function with the following signature:</p>
<pre><code>({
// VueX context object
Expand All @@ -182,7 +182,7 @@ <h4>addressSearch.customSelectFunction</h4>
}) =&gt; void
</code></pre>
<p>With this, arbitrary click results can be supported. Please mind that undocumented mutations and actions fired in such a function are subject to change without further notice.</p>
<h4>addressSearch.groupProperties</h4>
<h4 id="addresssearch.groupproperties" tabindex="-1">addressSearch.groupProperties</h4>
<table>
<thead>
<tr>
Expand Down Expand Up @@ -219,7 +219,7 @@ <h4>addressSearch.groupProperties</h4>
</tr>
</tbody>
</table>
<h4>addressSearch.categoryProperties</h4>
<h4 id="addresssearch.categoryproperties" tabindex="-1">addressSearch.categoryProperties</h4>
<table>
<thead>
<tr>
Expand All @@ -236,7 +236,7 @@ <h4>addressSearch.categoryProperties</h4>
</tr>
</tbody>
</table>
<h5>addressSearch.searchMethodsObject.queryParameters (type:common)</h5>
<h5 id="addresssearch.searchmethodsobject.queryparameters-(type%3Acommon)" tabindex="-1">addressSearch.searchMethodsObject.queryParameters (type:common)</h5>
<p>These fields are interpreted by all implemented services.</p>
<table>
<thead>
Expand All @@ -254,7 +254,7 @@ <h5>addressSearch.searchMethodsObject.queryParameters (type:common)</h5>
</tr>
</tbody>
</table>
<h5>addressSearch.searchMethodsObject.queryParameters (type:wfs)</h5>
<h5 id="addresssearch.searchmethodsobject.queryparameters-(type%3Awfs)" tabindex="-1">addressSearch.searchMethodsObject.queryParameters (type:wfs)</h5>
<table>
<thead>
<tr>
Expand Down Expand Up @@ -317,7 +317,7 @@ <h5>addressSearch.searchMethodsObject.queryParameters (type:wfs)</h5>
<li>WFS 2.0.0 <code>{wildCard: &quot;%&quot;, singleChar: &quot;*&quot;, escapeChar: &quot;\&quot;}</code></li>
<li>WFS 1.0.0 <code>{wildCard: &quot;*&quot;, singleChar: &quot;*&quot;, escape: &quot;\&quot;}</code></li>
</ul>
<h5>addressSearch.searchMethodsObject.queryParameters (type:gazetteer)</h5>
<h5 id="addresssearch.searchmethodsobject.queryparameters-(type%3Agazetteer)" tabindex="-1">addressSearch.searchMethodsObject.queryParameters (type:gazetteer)</h5>
<blockquote>
<p>⚠️ &quot;gazetteer&quot; is deprecated. Please use &quot;mpapi&quot; instead.</p>
</blockquote>
Expand Down Expand Up @@ -362,7 +362,7 @@ <h5>addressSearch.searchMethodsObject.queryParameters (type:gazetteer)</h5>
</tr>
</tbody>
</table>
<h5>addressSearch.searchMethodsObject.queryParameters (type:mpapi)</h5>
<h5 id="addresssearch.searchmethodsobject.queryparameters-(type%3Ampapi)" tabindex="-1">addressSearch.searchMethodsObject.queryParameters (type:mpapi)</h5>
<blockquote>
<p><strong>Please mind that this requires a configured backend. A WFS's Stored Query is requested with predefined parameters using the <a href="https://bitbucket.org/geowerkstatt-hamburg/masterportalapi/src/master/">masterportalApi</a>. This implementation is meant for e.g. https://geodienste.hamburg.de/HH_WFS_GAGES, but works with other WFS configured in the same manner.</strong></p>
</blockquote>
Expand Down Expand Up @@ -408,23 +408,23 @@ <h5>addressSearch.searchMethodsObject.queryParameters (type:mpapi)</h5>
</tbody>
</table>
<p>While all fields are optional, configuring none of them will yield undefined behaviour. At least one search instruction should be set to <code>true</code>.</p>
<h5>addressSearch.searchMethodsObject.queryParameters (type:bkg)</h5>
<h5 id="addresssearch.searchmethodsobject.queryparameters-(type%3Abkg)" tabindex="-1">addressSearch.searchMethodsObject.queryParameters (type:bkg)</h5>
<p>In <em>BKG</em> mode, queryParameter's key-value pairs are used in the service query. E.g. <code>{filter: { bundesland: 'Bremen' }}</code> results in the GET request URL having <code>&amp;filter=bundesland:Bremen</code> as suffix.</p>
<p>For more options, please check the <a href="https://sg.geodatenzentrum.de/web_public/gdz/dokumentation/deu/geokodierungsdienst.pdf">official documentation</a> regarding what query parameters are interpreted.</p>
<p>Additionally, it is possible to configure the parameters <code>accesstoken</code> (<code>Authorization</code>) or <code>apiKey</code> (custom header <code>X-Api-Key</code>) to send the described headers to the search service for authentication purposes.
Note that this changes the request to be non-simple. To be able to use the parameters, the request has to be sent in <a href="https://developer.mozilla.org/en-US/docs/Web/API/Request/mode"><code>cors</code> mode</a> and has to support preflight request <code>OPTIONS</code>.</p>
<h2>Store</h2>
<h3>Mutations</h3>
<h4>setSelectedGroupName</h4>
<h2 id="store" tabindex="-1">Store</h2>
<h3 id="mutations" tabindex="-1">Mutations</h3>
<h4 id="setselectedgroupname" tabindex="-1">setSelectedGroupName</h4>
<p>This can be used to change the selected search group by name.</p>
<pre><code class="language-js">map.$store.commit(
'plugin/addressSearch/setSelectedGroupName',
'Flurstückssuche'
)
</code></pre>
<p>Please mind that programmatically changing the search group will <em>not</em> trigger a search, unlike a search group change by the user. If you need a search after change, consider the <code>search</code> action.</p>
<h3>Actions</h3>
<h4>search</h4>
<h3 id="actions" tabindex="-1">Actions</h3>
<h4 id="search" tabindex="-1">search</h4>
<p>This is a purely programmatical search method. It is not used by user input.</p>
<pre><code class="language-js">map.$store.dispatch('plugin/addressSearch/search', {
input: 'Bahnhofsstraße 12',
Expand Down Expand Up @@ -453,7 +453,7 @@ <h4>search</h4>
</tr>
</tbody>
</table>
<h3>State</h3>
<h3 id="state" tabindex="-1">State</h3>
<pre><code class="language-js">map.subscribe('plugin/addressSearch/chosenAddress', (chosenAddress) =&gt; {
/* Your code. */
})
Expand Down
Loading

0 comments on commit e7fd265

Please sign in to comment.