From 7c55b0c76ba4aeb4a7114c0d9378766f2d6667ed Mon Sep 17 00:00:00 2001
From: Marcel Werk <burntime@woltlab.com>
Date: Fri, 6 Jan 2023 18:21:44 +0100
Subject: [PATCH] Add documentation for google maps web component

---
 docs/javascript/components_google_maps.md | 173 ++++++++++++++++++++++
 mkdocs.yml                                |   1 +
 2 files changed, 174 insertions(+)
 create mode 100644 docs/javascript/components_google_maps.md

diff --git a/docs/javascript/components_google_maps.md b/docs/javascript/components_google_maps.md
new file mode 100644
index 00000000..f3074c01
--- /dev/null
+++ b/docs/javascript/components_google_maps.md
@@ -0,0 +1,173 @@
+# Google Maps - JavaScript API
+
+The Google Maps component is used to show a map using the Google Maps API.
+
+## Example
+
+The component can be included directly as follows:
+
+```html
+<woltlab-core-google-maps
+    id="id"
+    class="googleMap"
+    api-key="your_api_key"
+></woltlab-core-google-maps>
+```
+
+Alternatively, the component can be included via a template that uses the API key from the configuration and also handles the user content:
+
+```smarty
+{include file='googleMapsElement' googleMapsElementID="id"}
+```
+
+## Parameters
+
+### `id`
+
+ID of the map instance.
+
+### `api-key`
+
+Google Maps API key.
+
+### `zoom`
+
+Defaults to `13`.
+
+Default zoom factor of the map.
+
+### `lat`
+
+Defaults to `0`.
+
+Latitude of the default map position.
+
+### `lng`
+
+Defaults to `0`.
+
+Longitude of the default map position.
+
+### `access-user-location`
+
+If set, the map will try to center based on the user's current position.
+
+## Map-related Functions
+
+### `addMarker`
+
+Adds a marker to the map.
+
+#### Example
+
+```html
+<script data-relocate="true">
+	require(['WoltLabSuite/Core/Component/GoogleMaps/Marker'], ({ addMarker }) => {
+		addMarker(document.getElementById('map_id'), 52.4505, 13.7546, 'Title', true);
+	});
+</script>
+```
+
+#### Parameters
+
+##### `element`
+
+`<woltlab-core-google-maps>` element.
+
+##### `latitude`
+
+Marker position (latitude)
+
+##### `longitude`
+
+Marker position (longitude)
+
+##### `title`
+
+Title of the marker.
+
+##### `focus`
+
+Defaults to `false`.
+
+True, to focus the map on the position of the marker.
+
+### `addDraggableMarker`
+
+Adds a draggable marker to the map.
+
+#### Example
+
+```html
+<script data-relocate="true">
+	require(['WoltLabSuite/Core/Component/GoogleMaps/Marker'], ({ addDraggableMarker }) => {
+		addDraggableMarker(document.getElementById('map_id'), 52.4505, 13.7546);
+	});
+</script>
+```
+
+#### Parameters
+
+##### `element`
+
+`<woltlab-core-google-maps>` element.
+
+##### `latitude`
+
+Marker position (latitude)
+
+##### `longitude`
+
+Marker position (longitude)
+
+### `Geocoding`
+
+Enables the geocoding feature for a map.
+
+#### Example
+
+```html
+<input
+	type="text"
+	data-google-maps-geocoding="map_id"
+	data-google-maps-marker
+>
+```
+
+#### Parameters
+
+##### `data-google-maps-geocoding`
+
+ID of the `<woltlab-core-google-maps>` element.
+
+##### `data-google-maps-marker`
+
+If set, a movable marker is created that is coupled with the input field.
+
+### `MarkerLoader`
+
+Handles a large map with many markers where markers are loaded via AJAX.
+
+#### Example
+
+```html
+<script data-relocate="true">
+	require(['WoltLabSuite/Core/Component/GoogleMaps/MarkerLoader'], ({ setup }) => {
+		setup(document.getElementById('map_id'), 'action_classname', {});
+	});
+</script>
+```
+
+#### Parameters
+
+##### `element`
+
+`<woltlab-core-google-maps>` element.
+
+##### `actionClassName`
+
+Name of the PHP class that is called to retrieve the markers via AJAX.
+
+##### `additionalParameters`
+
+Additional parameters that are transmitted when querying the markers via AJAX.
diff --git a/mkdocs.yml b/mkdocs.yml
index da3ed91e..55773c6c 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -57,6 +57,7 @@ nav:
     - 'Components':
       - 'Confirmation': 'javascript/components_confirmation.md'
       - 'Dialog': 'javascript/components_dialog.md'
+      - 'Google Maps': 'javascript/components_google_maps.md'
       - 'Pagination': 'javascript/components_pagination.md'
     - 'New API':
       - 'Writing a module': 'javascript/new-api_writing-a-module.md'
-- 
2.20.1