About configuration, integration, and common use cases.
Architecture
User perspective
When using POLAR, it behaves a simple fragment that can be used in any web-based setting. It may either work standalone, in which case there are only inputs for configuration, or as a part of a process, in which case there are both inputs and outputs for further processing.
The purpose of POLAR is to handle all geospatial interactions of a user and utilize the decentralized geospatial infrastructure for that end.
Viewn from the outside, POLAR is just a component
Usage examples
POLAR is designed to increase application efficiency and correctness for the public sector, but may be used in any form process or as a standalone map client. The provided visualisations ease communication between citizens and administrative staff, allowing them to effectively share the where.
POLAR is already in use for ...
... citizens to ...
communicate parcel data in applications.
mark their current position for reports.
read information on water levels, bathing spots, and much other public information.
... officials in charge to ...
coordinate city services regarding reports.
present governmental data to the public.
manage and update department geospatial data.
... developers to ...
heavily reduce implementation time.
easily use geospatial systems without domain expertise.
use POLAR as component in low code platforms.
Inner architecture
On the inside, POLAR is constructed from many smaller and isolated packages that each encapsulate a specific part of the business logic. These parts can be mixed and matched, and are easily replacable for situations where further extension would make them overly complicated.
For client-specific business logic, this can be placed in the very client itself to prevent bloat in other parts of the product.
All in all, this makes POLAR a versatile map client factory.
Viewn from the inside, POLAR is a map client factory
Configuration
Client documentation
Each client comes with its own documentation built from its individual description and used plugins.
A service register defining which services are usable. You may either write this file yourself or use an existing register, for example Hamburg's service register ↗. This is built on the masterportalAPI and uses its service register interpreter. This works with all masterportalAPI-compatible fields of the Masterportal's service register description ↗.
A minimal example register with one background layer looks like this:
Startup code. This is mostly putting the aforementioned parts together and adding configuration and subscriptions.
For a minimum working example, checkout this repository ↗ which includes the example shown in the FOSSGIS 2024 presentation ↗.
import client from '@polar/client-generic'
client.createMap({
containerId: 'polarstern', // id from div
services: services, // URL to register or array of service descriptions
mapConfiguration: mapConfiguration, // for all things allowed, see full docs
enabledPlugins: ['iconMenu', 'zoom'] // only in generic client
}).then((map) => {
// subscriptions and watchers; see full docs for all observable fields
map.subscribe(
'plugin/zoom/zoomLevel',
(zoomLevel) => { /* Your code here. */ }
)
}))
And that's about it. For more examples, view the plugin gallery ↗ or choose a specific client's documentation files.
Development
HINTDeveloping yourself is optional. POLAR supplies ready-made clients for many use cases, and you may commission us to write additional features.
Where to code
POLAR clients run everywhere. To develop plugins and clients anew, a certain setup is required. To avoid redoing it, it is advised to create additional plugins and clients in a fork of the project.
There are no further requirements. If you aim to merge back, please contact us before starting to put in work.
Required skills
Depending on what exactly you plan to write anew, the required skills may vary. POLAR is a purely front-end solution and as such general knowledge about web development is advisable.
We are especially writing the client with the following libraries, to which additional knowledge is helpful for contributions.