From 89bc715fd6ebfd655d7b075a679fdb7ece380054 Mon Sep 17 00:00:00 2001 From: Candid Dauth Date: Sat, 24 Apr 2021 16:17:12 +0200 Subject: [PATCH] Fix links in documentation --- docs/Dockerfile | 2 + docs/src/developers/README.md | 4 +- docs/src/developers/client/README.md | 6 +- docs/src/developers/client/advanced.md | 2 +- docs/src/developers/client/events.md | 38 +++---- docs/src/developers/client/methods.md | 120 +++++++++++------------ docs/src/developers/client/properties.md | 52 +++++----- docs/src/developers/client/types.md | 10 +- docs/src/developers/leaflet/README.md | 22 ++--- docs/src/developers/leaflet/bbox.md | 2 +- docs/src/developers/leaflet/filter.md | 4 +- docs/src/developers/leaflet/hash.md | 6 +- docs/src/developers/leaflet/layers.md | 4 +- docs/src/developers/leaflet/lines.md | 4 +- docs/src/developers/leaflet/markers.md | 2 +- docs/src/developers/leaflet/route.md | 4 +- docs/src/developers/leaflet/search.md | 2 +- docs/src/developers/leaflet/views.md | 6 +- docs/src/developers/server/README.md | 4 +- docs/src/developers/server/docker.md | 4 +- docs/src/developers/server/standalone.md | 6 +- 21 files changed, 153 insertions(+), 151 deletions(-) diff --git a/docs/Dockerfile b/docs/Dockerfile index bbf06b86..22246b04 100644 --- a/docs/Dockerfile +++ b/docs/Dockerfile @@ -3,6 +3,8 @@ MAINTAINER Candid Dauth RUN apk add --no-cache nodejs yarn +RUN echo "ErrorDocument 404 /404.html" >> /usr/local/apache2/conf/httpd.conf + COPY ./ /tmp/facilmap-docs RUN cd /tmp/facilmap-docs && yarn install && yarn build && mv dist/* /usr/local/apache2/htdocs/ && rm -rf /tmp/facilmap-docs diff --git a/docs/src/developers/README.md b/docs/src/developers/README.md index d3757f3a..3828037a 100644 --- a/docs/src/developers/README.md +++ b/docs/src/developers/README.md @@ -2,10 +2,10 @@ ## Quick links -* [Embed FacilMap](./embed) into any website using an iframe. +* [Embed FacilMap](./embed.md) into any website using an iframe. * Run your own [FacilMap server](./server/). * Use the [FacilMap client](./client/) to programmatically access and modify data on a collaborative map. -* Read about the [dev setup](./development/dev-setup) to start contributing to the FacilMap code. +* Read about the [dev setup](./development/dev-setup.md) to start contributing to the FacilMap code. ## Structural overview diff --git a/docs/src/developers/client/README.md b/docs/src/developers/client/README.md index 0830be3e..eb7d43f9 100644 --- a/docs/src/developers/client/README.md +++ b/docs/src/developers/client/README.md @@ -41,7 +41,7 @@ One instance of the client class represents one connection to one specific colla * Map ID set: All methods are available. Events are received when the map settings, types, views and lines (only metadata, not track points) are created/updated/deleted. * Map ID and bbox set: All methods are available. In addition to the other events, events are received when markers and lines in the specified bounding box are created/updated/deleted. -It is possible to initialize a client without a map ID and later open a map using [`setPadId`](./methods#setpadid-padid) or [`createPad`](./methods#createpad-data). Once a specific map is loaded, it is not possible to close it or switch to another map anymore. To do that, a new client instance has to be created. +It is possible to initialize a client without a map ID and later open a map using [`setPadId`](./methods.md#setpadid-padid) or [`createPad`](./methods.md#createpad-data). Once a specific map is loaded, it is not possible to close it or switch to another map anymore. To do that, a new client instance has to be created. The bbox can be updated continuously. In the official FacilMap UI, the bbox is updated every time the user pans the map, causing the server to send the markers within that bbox and a simplified version of the line track points and active routes fit to the bbox and zoom level. @@ -55,9 +55,9 @@ await client.setPadId("myMapId"); console.log(client.padData, client.types, client.lines); ``` -The client [constructor](./methods#constructor-server-padid) takes the URL where the FacilMap server is running and opens a socket.io connection to the server. +The client [constructor](./methods.md#constructor-server-padid) takes the URL where the FacilMap server is running and opens a socket.io connection to the server. -When opening a collaborative map using [`setPadId`](./methods#setpadid-padid), the server sends [events](./events) for the map settings, types, views and lines (without track points). The same types of events will be received later if the respective objects are changed while the connection is open. The client has some default listeners registered that will store the data received as events in its [properties](./properties). For example, a `padData` event contains the map settings and is emitted the first time the map ID is set and every time the map settings are changed while the connection is open. The `client.padData` property always contains the latest state of the map settings. +When opening a collaborative map using [`setPadId`](./methods.md#setpadid-padid), the server sends [events](./events.md) for the map settings, types, views and lines (without track points). The same types of events will be received later if the respective objects are changed while the connection is open. The client has some default listeners registered that will store the data received as events in its [properties](./properties.md). For example, a `padData` event contains the map settings and is emitted the first time the map ID is set and every time the map settings are changed while the connection is open. The `client.padData` property always contains the latest state of the map settings. Note that most methods of the client are asynchronous. Events that the server fires in response to a method call are always fired before the method returns. This is why in the above example, `client.padData` and the other properties are available right after the `setPadId` call. diff --git a/docs/src/developers/client/advanced.md b/docs/src/developers/client/advanced.md index c2761128..2a76c315 100644 --- a/docs/src/developers/client/advanced.md +++ b/docs/src/developers/client/advanced.md @@ -44,6 +44,6 @@ client._decodeData = (data) => new Map(Object.entries(data)); client._encodeData = (data) => Object.fromEntries([...data]); ``` -Doing this will change the type of the `data` property of the [`Marker`](./types#marker) and [`Line`](./types#line) types in all properties, methods and events that deal with such objects. +Doing this will change the type of the `data` property of the [`Marker`](./types.md#marker) and [`Line`](./types.md#line) types in all properties, methods and events that deal with such objects. In TypeScript, you can specify the data type using a generic (`Client>`). \ No newline at end of file diff --git a/docs/src/developers/client/events.md b/docs/src/developers/client/events.md index b7480e50..77f4acf3 100644 --- a/docs/src/developers/client/events.md +++ b/docs/src/developers/client/events.md @@ -1,10 +1,10 @@ # Events -The FacilMap server uses events to send information about objects on a collaborative map to the client. The events are fired when the client opens a map or a particular section of a map for the first time, and whenever an object is changed on the map (including when the change is made by the same instance of the client). The client has some listeners already attached to most events and uses them to persist and update the received objects in its [properties](./properties). +The FacilMap server uses events to send information about objects on a collaborative map to the client. The events are fired when the client opens a map or a particular section of a map for the first time, and whenever an object is changed on the map (including when the change is made by the same instance of the client). The client has some listeners already attached to most events and uses them to persist and update the received objects in its [properties](./properties.md). Note that events are always fired _before_ the method causing them returns. For example, when updating a marker using the `editMarker()` method, a `marker` event with the updated marker is fired first (if the marker is within the current bbox), and only then the method returns the updated marker as well. -Subscribe to events using the [`on(eventName, function)`](./methods#on-eventname-function) method. Example: +Subscribe to events using the [`on(eventName, function)`](./methods.md#on-eventname-function) method. Example: ```js const client = new FacilMap.Client("https://facilmap.org/", "testPad"); @@ -21,14 +21,14 @@ These events come from socket.io and are [documented there under the section “ The settings of the map have changed or are retrieved for the first time. -Note that when this event is fired, the read-only and/or the read-write ID of the map might have changed. The [`padId`](./properties#padid) +Note that when this event is fired, the read-only and/or the read-write ID of the map might have changed. The [`padId`](./properties.md#padid) property is updated automatically. -_Type:_ [PadData](./types#paddata) +_Type:_ [PadData](./types.md#paddata) ## `serverError` -[`setPadId()`](./methods#setpadid-padid) failed and the map could not be opened. +[`setPadId()`](./methods.md#setpadid-padid) failed and the map could not be opened. _Type:_ Error @@ -40,7 +40,7 @@ The map has been deleted. An existing marker is retrieved for the first time, has been modified, or a new marker has been created in the current bbox. -_Type:_ [Marker](./types#marker) +_Type:_ [Marker](./types.md#marker) ## `deleteMarker` @@ -55,7 +55,7 @@ An existing line is retrieved for the first time, has been modified, or a new li objects only contain the line metadata, not its track points (those are handled separately as `linePoints`). This is why all line objects of the map are sent to the client, regardless of the current bbox. -_Type:_ [Line](./types#line) (without trackPoints) +_Type:_ [Line](./types.md#line) (without trackPoints) ## `deleteLine` @@ -72,13 +72,13 @@ _Type:_ object with the following properties: * __id__ (number): The ID of the line that these track points belong to * __reset__ (boolean): Whether to remove all cached track points for this line (`true`) or to merge these track points with the cached ones (`false`). -* __trackPoints__ (Array<[TrackPoint](./types#trackpoint)>): The track points +* __trackPoints__ (Array<[TrackPoint](./types.md#trackpoint)>): The track points ## `view` A view is retrieved for the first time, has been modified, or a new view has been created. -_Type:_ [View](./types#view) +_Type:_ [View](./types.md#view) ## `deleteView` @@ -90,7 +90,7 @@ _Type:_ `{ id: number }` A type is retrieved for the first time, has been modified, or a new type has been created. -_Type:_ [Type](./types#type) +_Type:_ [Type](./types.md#type) ## `deleteType` @@ -101,15 +101,15 @@ _Type:_ `{ id: number }` ## `history` An entry of the modification history is retrieved for the first time, or a new entry has been created due to something -being modified. Note that this event is only fired when the client has subscribed using [`listenToHistory()`](./methods#listentohistory). - -_Type:_ [historyEntry](./types#historyentry) +being modified. Note that this event is only fired when the client has subscribed using [`listenToHistory()`](./methods.md#listentohistory). + +_Type:_ [historyEntry](./types.md#historyentry) ## `route` A new route has been set. -_Type:_ [Route](./types#route)> with trackpoints for the current bbox. The `routeId` property identifies the route (can be a string or undefined). +_Type:_ [Route](./types.md#route)> with trackpoints for the current bbox. The `routeId` property identifies the route (can be a string or undefined). ## `clearRoute` @@ -119,18 +119,18 @@ _Type:_ `{ routeId: string | undefined }` ## `routePoints` -New track points for the default route (route that has been set using [`setRoute()`](./methods#setroute-data) without a `routeId`) are retrieved after a change of bbox. +New track points for the default route (route that has been set using [`setRoute()`](./methods.md#setroute-data) without a `routeId`) are retrieved after a change of bbox. -_Type:_ Array<[TrackPoint](./types#trackpoint)> +_Type:_ Array<[TrackPoint](./types.md#trackpoint)> ## `routePointsWithId` New track points for a route with a `routeId` are retrieved after a change of bbox. _Type:_ object with the following properties: -* **routeId** (string): The `routeId` that was passed when setting the route using [`setRoute()`](./methods#setroute-data) -* **trackPoints** (`Array<[trackPoint](./types#trackpoint)>`): The additional track points for the route - +* **routeId** (string): The `routeId` that was passed when setting the route using [`setRoute()`](./methods.md#setroute-data) +* **trackPoints** (`Array<[trackPoint](./types.md#trackpoint)>`): The additional track points for the route + ## `loadStart`, `loadEnd` This event is fired every time some request is sent to the server and when the response has arrived. It can be used to diff --git a/docs/src/developers/client/methods.md b/docs/src/developers/client/methods.md index 38e4918e..42b239a7 100644 --- a/docs/src/developers/client/methods.md +++ b/docs/src/developers/client/methods.md @@ -5,17 +5,17 @@ Connects to the FacilMap server `server` and optionally opens the collaborative map with the ID `padId`. If the pad ID is not set, it can be set later using [`setPadId(padId)`](#setpadid-padid) or using [`createPad(data)`](#createpad-data). -The connection is established in the background, and a `connect` event is fired when it is successful. If a `padId` is specified, a [`padData`](./events#paddata) or [`serverError`](./events#servererror) event will indicate when the map has been opened successfully or unsuccessfully. Note that you can already call methods immediately after constructing the client, causing them to be delayed until the connection is established. +The connection is established in the background, and a `connect` event is fired when it is successful. If a `padId` is specified, a [`padData`](./events.md#paddata) or [`serverError`](./events.md#servererror) event will indicate when the map has been opened successfully or unsuccessfully. Note that you can already call methods immediately after constructing the client, causing them to be delayed until the connection is established. If the connection to the server breaks down, a `disconnect` event will be emitted and socket.io will attempt to reconnect. On successful reconnection, a `reconnect` and `connect` event will be fired. During the interruption, you can still call methods, causing them to be delayed until the connection is reestablished. * `server` (string): The URL of the FacilMap server, for example `https://facilmap.org/`. * `padId` (string, optional): The ID of the collaborative map to open. -* **Events:** Causes a `connect` event to be fired when the connection is established. If `padId` is defined, causes events to be fired with the map settings, all views, all types and all lines (without line points) of the map. If the map with `padId` could not be opened, causes a [`serverError`](./events#servererror) event. +* **Events:** Causes a `connect` event to be fired when the connection is established. If `padId` is defined, causes events to be fired with the map settings, all views, all types and all lines (without line points) of the map. If the map with `padId` could not be opened, causes a [`serverError`](./events.md#servererror) event. ## `on(eventName, function)` -Registers a new [event](./events) handler. +Registers a new [event](./events.md) handler. * `eventName` (string): The name of the event. * `function` (function): The function that should be executed when the event occurs. If the event emits an object, it will be passed to the function as the first parameter. @@ -33,18 +33,18 @@ Opens the collaborative map with the ID `padId`. This method can only be called once, and only if no `padId` was passed to the constructor. If you want to open a different map, you need to create a new instance of the client. -Setting the padId causes the server to send several objects, such as the map settings, all views, and all lines (just metadata, without line points). Each of these objects is sent as an individual [`event`](./events). +Setting the padId causes the server to send several objects, such as the map settings, all views, and all lines (just metadata, without line points). Each of these objects is sent as an individual [`event`](./events.md). * `padId` (string): The ID of the collaborative map to open. Can be a read-only ID, writable ID or admin ID of a map. * **Returns:** A promise that is resolved empty when all objects have been received. -* **Events:** Causes events to be fired with the map settings, all views, all types and all lines (without line points) of the map. If the map could not be opened, causes a [`serverError`](./events#servererror) event. +* **Events:** Causes events to be fired with the map settings, all views, all types and all lines (without line points) of the map. If the map could not be opened, causes a [`serverError`](./events.md#servererror) event. * **Availability:** Only available if no map is opened yet on this client instance. ## `updateBbox(bbox)` Updates the bbox. This will cause all markers, line points and route points within the bbox (except the ones that were already in the previous bbox, if there was one) to be received as individual events. -* __bbox__ ([Bbox](./types#bbox) with zoom): The bbox that objects should be received for. +* __bbox__ ([Bbox](./types.md#bbox) with zoom): The bbox that objects should be received for. * **Returns:** A promise that is resolved empty when all objects have been received. * **Events:** Causes events to be fired with the markers, line points and route points within the bbox. * **Availability:** Always. @@ -53,18 +53,18 @@ Updates the bbox. This will cause all markers, line points and route points with Creates a new collaborative map and opens it. -* `data` ([padData](./types#paddata)): The data of the new map, including the desired read-only, writable and admin ID. +* `data` ([padData](./types.md#paddata)): The data of the new map, including the desired read-only, writable and admin ID. * **Returns:** A promise that is resolved with the new padData when the map has been created. -* **Events:** Causes a [`padData`](./events#paddata) event and other events for objects that have been created on the map (such as the default Marker and Line types). +* **Events:** Causes a [`padData`](./events.md#paddata) event and other events for objects that have been created on the map (such as the default Marker and Line types). * **Availability:** Only if no collaborative map is opened yet. ## `editPad(data)` Update the map settings of the current map. -* `data` ([PadData](./types#paddata)): The data of the map that should be modified. Fields that are not defined will not be modified. To change the default view, set the `defaultViewId` property. The `defaultView` property is ignored. +* `data` ([PadData](./types.md#paddata)): The data of the map that should be modified. Fields that are not defined will not be modified. To change the default view, set the `defaultViewId` property. The `defaultView` property is ignored. * **Returns:** A promise that is resolved with the new padData. -* **Events:** Causes a [`padData`](./events#paddata) event. +* **Events:** Causes a [`padData`](./events.md#paddata) event. * **Availability:** Only if a collaborative map is opened through its admin ID. ## `deletePad()` @@ -72,7 +72,7 @@ Update the map settings of the current map. Delete the current map irrevocably. * **Returns:** A promise that is resolved empty when the map has been deleted. -* **Events:** Causes a [`deletePad`](./events#deletepad) event. +* **Events:** Causes a [`deletePad`](./events.md#deletepad) event. * **Availability:** Only if a collaborative map is opened through its admin ID. ## `listenToHistory()` @@ -82,7 +82,7 @@ received (that describe the modification history until now), and new `history` o something is modified (in addition to the modified object). * **Returns:** A promise that is resolved empty when all history objects have been received. -* **Events:** Causes multiple [`history`](./events#history) events. +* **Events:** Causes multiple [`history`](./events.md#history) events. * **Availability:** Only if a collaborative map is opened through its admin ID. ## `stopListeningToHistory()` @@ -101,7 +101,7 @@ will cause the whole history to be received again (as if you were calling `liste * `data` (`{ id: number }`)): The history object that should be reverted. * **Returns:** A promise that is resolved empty when the command has completed and all new history objects have been received. -* **Events:** Causes multiple [`history`](./events#history) events and an event that reverts the change. +* **Events:** Causes multiple [`history`](./events.md#history) events and an event that reverts the change. * **Availability:** Only if a collaborative map is opened through its admin ID. ## `disconnect()` @@ -118,7 +118,7 @@ Search for places. Does not persist anything on the server, simply serves as a p * `elevation` (boolean): Whether to find out the elevation of the result(s). Will make the search significantly slower. * **Returns:** A promise that is resolved with the following value: * If `data.query` is a URL to a GPX/KML/OSM/GeoJSON file and `loadUrls` is `true`, a string with the content of the file. - * Otherwise an array of [SearchResults](./types#searchresult). + * Otherwise an array of [SearchResults](./types.md#searchresult). * **Events:** None. * **Availability:** Always. @@ -128,7 +128,7 @@ Search for markers and lines inside the map. * `data` (object): An object with the following properties: * `query` (string): The query string -* **Returns:** A promise that is resolved with an array of (stripped down) [Marker](./types#marker) and [Line](./types#line) objects. The objects only contain the `id`, `name`, `typeId`, `lat`/`lon` (for markers), `left`/`top`/`right`/`bottom` (for lines) properties, plus an additional `kind` property that is either `"marker"` or `"line"`. +* **Returns:** A promise that is resolved with an array of (stripped down) [Marker](./types.md#marker) and [Line](./types.md#line) objects. The objects only contain the `id`, `name`, `typeId`, `lat`/`lon` (for markers), `left`/`top`/`right`/`bottom` (for lines) properties, plus an additional `kind` property that is either `"marker"` or `"line"`. * **Events:** None. * **Availability:** Only when a map is opened. @@ -138,27 +138,27 @@ Calculate a route between two or more points. Does not persist anything on the s * `data` (object): An object with the following properties: * `destinations` (array): An array of at least two route points (objects with a `lat` and `lon` property) - * `mode` ([RouteMode](./types#routemode)): the route mode -* **Returns:** A promise that is resolved with a [Route](./types#route)>. + * `mode` ([RouteMode](./types.md#routemode)): the route mode +* **Returns:** A promise that is resolved with a [Route](./types.md#route)>. * **Events:** None. * **Availability:** Always. ## `setRoute(data)` -Calculate a route between two or more points, but but do not return the track points of the route but cache them on the server side and send them according to the client bbox. The route is not persisted on a collaborative map, but is temporarily persisted on the server in the scope one particular client connection only. As long as the route is active, the server will send [`routePoints`](./events#routepoints) events in response to [`updateBbox()`](#updatebbox-bbox) with the track points of the route simplified according to the bbox. The route will stay active until it is cleared using [`clearRoute()`](#clearroute-data) or the connection is closed. +Calculate a route between two or more points, but but do not return the track points of the route but cache them on the server side and send them according to the client bbox. The route is not persisted on a collaborative map, but is temporarily persisted on the server in the scope one particular client connection only. As long as the route is active, the server will send [`routePoints`](./events.md#routepoints) events in response to [`updateBbox()`](#updatebbox-bbox) with the track points of the route simplified according to the bbox. The route will stay active until it is cleared using [`clearRoute()`](#clearroute-data) or the connection is closed. Multiple routes can be active at the same time. They can be distinguished by their `routeId` property, which is a custom string that you can specify when activating a route. A `routeId` needs to be unique in the scope of this client instance, other clients are not affected by it. For backwards compatibility reasons, `undefined` is an acceptable value for `routeId`, but is considered a unique identifier nonetheless. Calling `setRoute()` with a `routeId` of a route that is already active will replace that route. -The metadata of a route whose `routeId` is `undefined` is persisted in the [`route`](./properties#route) property and its track points in `route.trackPoints`. The metadata of a route whose `routeId` is a string is persisted in the [`routes[routeId]`](./properties#routes) property and its track points in `routes[routeId].trackPoints`. +The metadata of a route whose `routeId` is `undefined` is persisted in the [`route`](./properties.md#route) property and its track points in `route.trackPoints`. The metadata of a route whose `routeId` is a string is persisted in the [`routes[routeId]`](./properties.md#routes) property and its track points in `routes[routeId].trackPoints`. * `data` (object): An object with the following properties: * `routePoints` (array): An array of at least two route points (objects with a `lat` and `lon` property) - * `mode` ([RouteMode](./types#routemode)): the route mode + * `mode` ([RouteMode](./types.md#routemode)): the route mode * `routeId` (string or undefined): the custom `routeId` to identify the route -* **Returns:** A promise that is resolved with a [Route](./types#route)> object. -* **Events:** Causes a [`route`](./events#route) and a [`routePoints`](./events#routepoints) event. +* **Returns:** A promise that is resolved with a [Route](./types.md#route)> object. +* **Events:** Causes a [`route`](./events.md#route) and a [`routePoints`](./events.md#routepoints) event. * **Availability:** Always. ## `clearRoute(data)` @@ -168,7 +168,7 @@ Clear a temporary route set via [`setRoute(data)`](#setroute-data). * `data` (object): An object with the following properties: * `routeId` (string or undefined): the custom `routeId` to identify the route * **Returns:** A promise that is resolved empty when the route is cleared. -* **Events:** Causes a [`clearRoute`](./events#clearroute) event. +* **Events:** Causes a [`clearRoute`](./events.md#clearroute) event. * **Availability:** If a route with the specified `routeId` is active. ## `lineToRoute(data)` @@ -178,8 +178,8 @@ Call [`setRoute()`](#setroute-data) with the parameters of an existing line. Sav * `data` (object): An object with the following properties: * `id` (string): The ID of the line * `routeId` (string or undefined): the custom `routeId` to identify the route -* **Returns:** A promise that is resolved with a [Route](./types#route)> object. -* **Events:** Causes a [`route`](./events#route) and a [`routePoints`](./events#routepoints) event. +* **Returns:** A promise that is resolved with a [Route](./types.md#route)> object. +* **Events:** Causes a [`route`](./events.md#route) and a [`routePoints`](./events.md#routepoints) event. * **Availability:** Only if a collaborative map is opened. ## `exportRoute(data)` @@ -201,7 +201,7 @@ Get the marker with the given ID. This is useful if you want to access a specifi * `data` (object): An object with the following properties: * `id` (number): The ID of the marker to load -* **Returns:** A promise that is resolved with a [Marker](./types#marker)>. If the marker is not found, the promise rejects. +* **Returns:** A promise that is resolved with a [Marker](./types.md#marker)>. If the marker is not found, the promise rejects. * **Events:** None. * **Availability:** Only if a collaborative map is opened. @@ -209,18 +209,18 @@ Get the marker with the given ID. This is useful if you want to access a specifi Create a marker. -* `data` ([Marker](./types#marker)): The data of the marker to create. An `id` will be assigned by the server. -* **Returns:** A promise that is resolved with a [Marker](./types#marker)>, with an `id` assigned and possibly its styles modified by the settings of its type. -* **Events:** May trigger a [`marker`](./events#marker) event if the created marker is in the current bbox. +* `data` ([Marker](./types.md#marker)): The data of the marker to create. An `id` will be assigned by the server. +* **Returns:** A promise that is resolved with a [Marker](./types.md#marker)>, with an `id` assigned and possibly its styles modified by the settings of its type. +* **Events:** May trigger a [`marker`](./events.md#marker) event if the created marker is in the current bbox. * **Availability:** Only if a collaborative map is opened using its writable or admin ID. ## `editMarker(data)` Update an existing marker. -* `data` ([Marker](./types#marker)). The new marker data. Fields that are not defined will not be unmodified. Only `id` needs to be defined. -* **Returns:** A promise that is resolved with the updated [Marker](./types#marker). Might have some styles modified due to the settings of its type. -* **Events:** May trigger a [`marker`](./events#marker) event if the updated marker is in the current bbox. +* `data` ([Marker](./types.md#marker)). The new marker data. Fields that are not defined will not be unmodified. Only `id` needs to be defined. +* **Returns:** A promise that is resolved with the updated [Marker](./types.md#marker). Might have some styles modified due to the settings of its type. +* **Events:** May trigger a [`marker`](./events.md#marker) event if the updated marker is in the current bbox. * **Availability:** Only if a collaborative map is opened using its writable or admin ID. ## `deleteMarker(data)` @@ -228,17 +228,17 @@ Update an existing marker. Delete an existing marker * `data` (`{ id: number }`): an object that contains the ID of the marker to be removed -* **Returns:** An promise that is resolved with the deleted [Marker](./types#marker) when the operation has completed. -* **Events:** Causes a [`deleteMarker`](./events#deletemarker) event. +* **Returns:** An promise that is resolved with the deleted [Marker](./types.md#marker) when the operation has completed. +* **Events:** Causes a [`deleteMarker`](./events.md#deletemarker) event. * **Availability:** Only if a collaborative map is opened using its writable or admin ID. ## `getLineTemplate(data)` - + Get a mock line object for a line with the given type. This can be used so that while the user is drawing a new line, that line already has the right style. * `data` (`{ typeId: number }`): An object containing the type ID -* **Returns:** A promise that is resolved with a mock [Line](./types#line) with the styles of this type. +* **Returns:** A promise that is resolved with a mock [Line](./types.md#line) with the styles of this type. * **Events:** None. * **Availability:** Only if a collaborative map is opened. @@ -246,18 +246,18 @@ that line already has the right style. Create a line. -* `data` ([Line](./types#line)): The data of the line to create. An `id` will be assigned by the server. -* **Returns:** A promise that is resolved with a [Line](./types#line), with an `id` assigned and possibly its styles modified by the settings of its type. -* **Events:** Causes a [`line`](./events#line) event and a [`linePoints`](./events#linepoints) event (if the line is in the current bbox). +* `data` ([Line](./types.md#line)): The data of the line to create. An `id` will be assigned by the server. +* **Returns:** A promise that is resolved with a [Line](./types.md#line), with an `id` assigned and possibly its styles modified by the settings of its type. +* **Events:** Causes a [`line`](./events.md#line) event and a [`linePoints`](./events.md#linepoints) event (if the line is in the current bbox). * **Availability:** Only if a collaborative map is opened using its writable or admin ID. ## `editLine(data)` Update an existing line. -* `data` ([line](./types#line)). The new line data. Fields that are not defined will not be unmodified. Only `id` needs to be defined. -* **Returns:** A promise that is resolved with the update [Line](./types#line). Might have some styles modified due to the settings of its type. -* **Events:** Causes a [`line`](./events#line) event and possibly a [`linePoints`](./events#linepoints) event (if the route mode was changed and the line is in the current bbox). +* `data` ([line](./types.md#line)). The new line data. Fields that are not defined will not be unmodified. Only `id` needs to be defined. +* **Returns:** A promise that is resolved with the update [Line](./types.md#line). Might have some styles modified due to the settings of its type. +* **Events:** Causes a [`line`](./events.md#line) event and possibly a [`linePoints`](./events.md#linepoints) event (if the route mode was changed and the line is in the current bbox). * **Availability:** Only if a collaborative map is opened using its writable or admin ID. ## `deleteLine(data)` @@ -265,8 +265,8 @@ Update an existing line. Delete an existing line * `data` (`{id: }`): An object that contains the ID of the line to be removed -* **Returns:** A promise that is resolved with the deleted [Line](./types#line) when the operation has completed. -* **Events:** Causes a [`deleteLine`](./events#deleteline) event. +* **Returns:** A promise that is resolved with the deleted [Line](./types.md#line) when the operation has completed. +* **Events:** Causes a [`deleteLine`](./events.md#deleteline) event. * **Availability:** Only if a collaborative map is opened using its writable or admin ID. ## `exportLine(data)` @@ -286,18 +286,18 @@ Export a line. Create a type. -* `data` ([Type](./types#type)): The data of the type to create. An `id` will be assigned by the server. -* **Returns:** A promise that is resolved with the created [Type](./types#type)>, with an `id` assigned. -* **Events:** Causes a [`type`](./events#type) event. +* `data` ([Type](./types.md#type)): The data of the type to create. An `id` will be assigned by the server. +* **Returns:** A promise that is resolved with the created [Type](./types.md#type)>, with an `id` assigned. +* **Events:** Causes a [`type`](./events.md#type) event. * **Availability:** Only if a collaborative map is opened using its admin link. ## `editType(data)` Update an existing type. -* `data` ([type](./types#type)). The new type data. Fields that are not defined will not be unmodified. Only `id` needs to be defined. To rename a field, set the `oldName` property of the field object to the previous name and the `name` property to the new name. To rename a dropdown entry, set the `oldValue` property to the old value and the `value` property to the new value. -* **Returns:** A promise that is resolved with the updated <[Type](./types#type)>. -* **Events:** Causes a [`type`](./events#type) event. If the update causes the styles of existing markers or lines to change, events for those are triggered as well. +* `data` ([type](./types.md#type)). The new type data. Fields that are not defined will not be unmodified. Only `id` needs to be defined. To rename a field, set the `oldName` property of the field object to the previous name and the `name` property to the new name. To rename a dropdown entry, set the `oldValue` property to the old value and the `value` property to the new value. +* **Returns:** A promise that is resolved with the updated <[Type](./types.md#type)>. +* **Events:** Causes a [`type`](./events.md#type) event. If the update causes the styles of existing markers or lines to change, events for those are triggered as well. * **Availability:** Only if a collaborative map is opened using its admin link. ## `deleteType(data)` @@ -305,26 +305,26 @@ Update an existing type. Delete an existing type * `data` (`{id: }`): An object that contains the ID of the type to be removed -* **Returns:** A promise that is resolved with the deleted [Type](./types#type) when the operation has completed. If there are any objects on the map that still use this type, the promise rejects. -* **Events:** Causes a [`deleteType`](./events#deletetype) event. +* **Returns:** A promise that is resolved with the deleted [Type](./types.md#type) when the operation has completed. If there are any objects on the map that still use this type, the promise rejects. +* **Events:** Causes a [`deleteType`](./events.md#deletetype) event. * **Availability:** Only if a collaborative map is opened using its admin link. ## `addView(data)` Create a view. -* `data` ([view](./types#view)): The data of the view to create. An `id` will be assigned by the server -* **Returns:** A promise that is resolved with the created <[View](./types#view)>), with an `id` assigned. -* **Events:** Causes a [`view`](./events#view) event. +* `data` ([view](./types.md#view)): The data of the view to create. An `id` will be assigned by the server +* **Returns:** A promise that is resolved with the created <[View](./types.md#view)>), with an `id` assigned. +* **Events:** Causes a [`view`](./events.md#view) event. * **Availability:** Only if a collaborative map is opened using its admin link. ## `editView(data)` Update an existing view. -* `data` ([view](./types#view)). The new view data. Fields that are not defined will not be unmodified. Only `id` needs to be defined. -* **Returns:** A promise that is resolved with the updated <[View](./types#view)>). -* **Events:** Causes a [`view`](./events#view) event. +* `data` ([view](./types.md#view)). The new view data. Fields that are not defined will not be unmodified. Only `id` needs to be defined. +* **Returns:** A promise that is resolved with the updated <[View](./types.md#view)>). +* **Events:** Causes a [`view`](./events.md#view) event. * **Availability:** Only if a collaborative map is opened using its admin link. ## `deleteView(data)` @@ -333,13 +333,13 @@ Delete an existing view * `data` (`{id: }`): An object that contains the ID of the view to be removed * **Returns:** A promise that is resolved when the operation has completed. -* **Events:** Causes a [`deleteView`](./events#deleteview) event. +* **Events:** Causes a [`deleteView`](./events.md#deleteview) event. * **Availability:** Only if a collaborative map is opened using its admin link. ## `geoip()` Returns an approximate location for the IP address of the client. -* **Returns:** A promise that is resolved to a [bounding box](./types#bbox) (without zoom) that includes the location of the client. If no location can be determined, the promise is resolved with `undefined`. +* **Returns:** A promise that is resolved to a [bounding box](./types.md#bbox) (without zoom) that includes the location of the client. If no location can be determined, the promise is resolved with `undefined`. * **Events:** None. * **Availability:** Always. \ No newline at end of file diff --git a/docs/src/developers/client/properties.md b/docs/src/developers/client/properties.md index b07382ab..3cc2a156 100644 --- a/docs/src/developers/client/properties.md +++ b/docs/src/developers/client/properties.md @@ -29,23 +29,23 @@ client.on("marker", (marker) => { The ID of the collaborative map that the client is connected to. Can be the read-only, writable or admin ID of an existing map. -Note that the ID can be changed in the settings. If in case of a [`padData`](./events#paddata) event, the ID of the pad has changed, this property is updated automatically. +Note that the ID can be changed in the settings. If in case of a [`padData`](./events.md#paddata) event, the ID of the pad has changed, this property is updated automatically. -_Set:_ when calling [`setPadId`](./methods#setpadid-padid) and in response to a [`padData`](./events#paddata) event.\ +_Set:_ when calling [`setPadId`](./methods.md#setpadid-padid) and in response to a [`padData`](./events.md#paddata) event.\ _Type:_ string ## `readonly` `true` if the map has been opened using its read-only ID. `false` if the map is writable. -_Set:_ during [`setPadId`](./methods#setpadid-padid).\ +_Set:_ during [`setPadId`](./methods.md#setpadid-padid).\ _Type:_ boolean ## `writable` `2` if the map has been opened using its admin ID, `1` if if has been opened using the writable ID, `0` if the map is read-only. -_Set:_ during [`setPadId`](./methods#setpadid-padid).\ +_Set:_ during [`setPadId`](./methods.md#setpadid-padid).\ _Type:_ number @@ -53,70 +53,70 @@ _Type:_ number `true` if the map was deleted while this client was connected to it. -_Set:_ in response to a [`deletePad`](./events#deletepad) event.\ +_Set:_ in response to a [`deletePad`](./events.md#deletepad) event.\ _Type:_ boolean ## `padData` The current settings of the map. `writeId` and/or `adminId` is null if if has been opened using another ID than the admin ID. -_Set:_ in response to a [`padData`](./events#paddata) event.\ -_Type:_ [PadData](./types#paddata) +_Set:_ in response to a [`padData`](./events.md#paddata) event.\ +_Type:_ [PadData](./types.md#paddata) ## `markers` All markers that have been retrieved so far. -_Set:_ in response to [`marker`](./events#marker) and [`deleteMarker`](./events#deletemarker) events.\ -_Type:_ [{ [markerId: number]: Marker }](./types#marker) +_Set:_ in response to [`marker`](./events.md#marker) and [`deleteMarker`](./events.md#deletemarker) events.\ +_Type:_ [{ [markerId: number]: Marker }](./types.md#marker) ## `lines` All lines of the map along with the track points that have been retrieved so far. -_Set:_ in response to [`line`](./events#line), [`linePoints`](./events#linepoints) and [`deleteLine`](./events#deleteline) events.\ -_Type:_ [{ [lineId: number]: Line }](./types#line) (with track points) +_Set:_ in response to [`line`](./events.md#line), [`linePoints`](./events.md#linepoints) and [`deleteLine`](./events.md#deleteline) events.\ +_Type:_ [{ [lineId: number]: Line }](./types.md#line) (with track points) ## `views` All views of the map. -_Set:_ in response to [`view`](./events#view) and [`deleteView`](./events#deleteview) events.\ -_Type:_ [{ [viewId: number]: View }](./types#view) +_Set:_ in response to [`view`](./events.md#view) and [`deleteView`](./events.md#deleteview) events.\ +_Type:_ [{ [viewId: number]: View }](./types.md#view) ## `types` All types of the map. -_Set:_ in response to [`type`](./events#type) and [`deleteType`](./events#deletetype) events.\ -_Type:_ [{ [typeId: number]: Type }](./types#type) +_Set:_ in response to [`type`](./events.md#type) and [`deleteType`](./events.md#deletetype) events.\ +_Type:_ [{ [typeId: number]: Type }](./types.md#type) ## `history` -All history entries that have been retrieved so far. Note that you have to subscribe to the history using [`listenToHistory()`](./methods#listentohistory). +All history entries that have been retrieved so far. Note that you have to subscribe to the history using [`listenToHistory()`](./methods.md#listentohistory). -_Set:_ in response to [`history`](./events#history) events.\ -_Type:_ [{ [entryId: number]: HistoryEntry }](./types#historyentry) +_Set:_ in response to [`history`](./events.md#history) events.\ +_Type:_ [{ [entryId: number]: HistoryEntry }](./types.md#historyentry) ## `route` -Details and track points (simplified for the current bbox) for the active route set using [`setRoute()`](./methods#setroute-data) with `routeId` set to `undefined`, or `undefined` if no such route is active. +Details and track points (simplified for the current bbox) for the active route set using [`setRoute()`](./methods.md#setroute-data) with `routeId` set to `undefined`, or `undefined` if no such route is active. -_Set:_ during [`setRoute()`](./methods#setroute-data) and in response to [`routePoints`](./events#routepoints) events.\ -_Type:_ [`Route`](./types#route) +_Set:_ during [`setRoute()`](./methods.md#setroute-data) and in response to [`routePoints`](./events.md#routepoints) events.\ +_Type:_ [`Route`](./types.md#route) ## `routes` -Details and track points (simplified for the current bbox) for the active routes set using [`setRoute()`](./methods#setroute-data) with `routeId` set to a string. +Details and track points (simplified for the current bbox) for the active routes set using [`setRoute()`](./methods.md#setroute-data) with `routeId` set to a string. -_Set:_ during [`setRoute()`](./methods#setroute-data) and in response to [`routePoints`](./events#routepoints) events.\ -_Type:_ [{ [routeId: string]: Route }](./types#route) +_Set:_ during [`setRoute()`](./methods.md#setroute-data) and in response to [`routePoints`](./events.md#routepoints) events.\ +_Type:_ [{ [routeId: string]: Route }](./types.md#route) ## `serverError` -If the opening the map failed ([`setPadId(padId)`](./methods#setpadid-padid) promise got rejected), the error message is stored in this property. +If the opening the map failed ([`setPadId(padId)`](./methods.md#setpadid-padid) promise got rejected), the error message is stored in this property. -_Set:_ in response to a [`serverError`](./events#servererror) event (fired during [`setPadId`](./methods#setpadid-padid)).\ +_Set:_ in response to a [`serverError`](./events.md#servererror) event (fired during [`setPadId`](./methods.md#setpadid-padid)).\ _Type:_ Error ## `loading` diff --git a/docs/src/developers/client/types.md b/docs/src/developers/client/types.md index ae37a0bd..867d8a14 100644 --- a/docs/src/developers/client/types.md +++ b/docs/src/developers/client/types.md @@ -10,7 +10,7 @@ A bounding box that describes which part of the map the user is currently viewin * `bottom` (number, min: -90, max: 90): The latitude of the south end of the box * `left` (number, min: -180, max: 180): The longitude of the west end of the box * `right` (number, min: -180, max: 180): The longitude of the east end of the box -* `zoom` (number, min: 1, max: 20): The current zoom level. This is relevant for the density of track points that should be received. +* `zoom` (number, min: 1, max: 20): The current zoom level. This is relevant for the density of track points that should be received. ## Marker @@ -24,7 +24,7 @@ A bounding box that describes which part of the map the user is currently viewin * `shape` (string): The shape name for the marker. Default is an empty string (equivalent to `"drop"`). * `elevation` (number): The elevation of this marker in metres (set by the server) * `typeId` (number): The ID of the type of this marker -* `data` ({ [fieldName: string]: string }): The filled out form fields of the marker. By default, this is a null-prototype object to avoid prototype pollution. Have a look at [marker/line data](./advanced#marker-line-data) for more details. +* `data` ({ [fieldName: string]: string }): The filled out form fields of the marker. By default, this is a null-prototype object to avoid prototype pollution. Have a look at [marker/line data](./advanced.md#marker-line-data) for more details. ## Line @@ -52,7 +52,7 @@ separately through `linePoints` events. * `left`, `top`, `right`, `bottom` (number): The bounding box of the line (set by the server) * `extraInfo` ({ [type: string]: Array<[startIdx: number, endIdx: number, type: number]>> }): Extra details about the route (set by the server). `type` can be for example `steepness`, `surface` or `waytype`. `startIdx` and `endIdx` describe a segment on the trackpoints of the route, the meaning of `type` can be seen in the documentation of [Leaflet.Heightgraph](https://github.com/GIScience/Leaflet.Heightgraph/blob/master/example/mappings.js). * `typeId` (number): The ID of the type of this line -* `data` ({ [fieldName: string]: string }): The filled out form fields of the line. By default, this is a null-prototype object to avoid prototype pollution. Have a look at [marker/line data](./advanced#marker-line-data) for more details. +* `data` ({ [fieldName: string]: string }): The filled out form fields of the line. By default, this is a null-prototype object to avoid prototype pollution. Have a look at [marker/line data](./advanced.md#marker-line-data) for more details. * `trackPoints`: * In the `lines` property of the client, an object of the format [{ [idx: number]: TrackPoint }](#trackpoint) * When creating/updating a line with the routing mode `track`, an array of the format [`TrackPoint[]`](#trackpoint) @@ -113,14 +113,14 @@ their `idx` property. cannot be changed for an individual object * `fields` ([object]): The form fields for this type. Each field has the following properties: * `name` (string): The name of the field. This is at the same time the key in the `data` properties of markers and lines - * `oldName` (string): When renaming a field (using [`editType(data)`](./methods#edittype-data)), specify the former name here + * `oldName` (string): When renaming a field (using [`editType(data)`](./methods.md#edittype-data)), specify the former name here * `type` (string): The type of field, one of `textarea`, `dropdown`, `checkbox`, `input` * `controlColour`, `controlSize`, `controlSymbol`, `controlShape`, `controlWidth` (boolean): If this field is a dropdown, whether the different options set a specific property on the object * `default` (string/boolean): The default value of this field * `options` ([object]): If this field is a dropdown or a checkbox, an array of objects with the following properties. For a checkbox, the array has to have 2 items, the first representing the unchecked and the second the checked state. * `value` (string): The value of this option. - * `oldValue` (string): When renaming a dropdown option (using [`editType(data)`](./methods#edittype-data)), specify the + * `oldValue` (string): When renaming a dropdown option (using [`editType(data)`](./methods.md#edittype-data)), specify the former value here * `colour`, `size`, `shape`, `symbol`, `width` (string/number): The property value if this field controls that property diff --git a/docs/src/developers/leaflet/README.md b/docs/src/developers/leaflet/README.md index 258caebb..55978b2e 100644 --- a/docs/src/developers/leaflet/README.md +++ b/docs/src/developers/leaflet/README.md @@ -6,17 +6,17 @@ The Leaflet components are only useful in combination with a [FacilMap client](. ## Components -* [BboxHandler](./bbox) automatically calls [updateBbox()](../client/methods#updatebbox-bbox) when the position of the map changes. -* [Layers](./layers) provides the layers that FacilMap offers by default and helpers to show them. -* [Markers](./markers) shows the markers of a collaborative map. -* [Lines](./lines) shows the lines of a collaborative map. -* [Route](./route) allows showing a calculated route on the map. -* [Search](./search) renders search results. -* [Icons](./icons) provides methods to draw marker icons and shapes. -* [HashHandler](./hash) hooks up the location hash to the current map view. -* [Views](./views) allow controlling the map view and handling saved views. -* [Filter](./filter) expressions can be used to control which markers/lines are visible on the map. -* [Click listener](./click-listener) is a helper to ask the user to click somewhere on the map. +* [BboxHandler](./bbox.md) automatically calls [updateBbox()](../client/methods.md#updatebbox-bbox) when the position of the map changes. +* [Layers](./layers.md) provides the layers that FacilMap offers by default and helpers to show them. +* [Markers](./markers.md) shows the markers of a collaborative map. +* [Lines](./lines.md) shows the lines of a collaborative map. +* [Route](./route.md) allows showing a calculated route on the map. +* [Search](./search.md) renders search results. +* [Icons](./icons.md) provides methods to draw marker icons and shapes. +* [HashHandler](./hash.md) hooks up the location hash to the current map view. +* [Views](./views.md) allow controlling the map view and handling saved views. +* [Filter](./filter.md) expressions can be used to control which markers/lines are visible on the map. +* [Click listener](./click-listener.md) is a helper to ask the user to click somewhere on the map. ## Setup diff --git a/docs/src/developers/leaflet/bbox.md b/docs/src/developers/leaflet/bbox.md index e95f4886..dac538cd 100644 --- a/docs/src/developers/leaflet/bbox.md +++ b/docs/src/developers/leaflet/bbox.md @@ -5,7 +5,7 @@ The FacilMap client needs to tell the current bounding box and zoom level of the * If a collaborative map is open, the line points in the specified bounding box (simplified for the specified zoom level) * If a calculated route is active, the route points in the specified bounding box (simplified for the specified zoom level). -BboxHandler automatically calls [updateBbox()](../client/methods#updatebbox-bbox) whenever the position of the map changes, either because the user panned the map or because it was changed programmatically. +BboxHandler automatically calls [updateBbox()](../client/methods.md#updatebbox-bbox) whenever the position of the map changes, either because the user panned the map or because it was changed programmatically. ## Usage diff --git a/docs/src/developers/leaflet/filter.md b/docs/src/developers/leaflet/filter.md index 569aca2c..1d1a4cc1 100644 --- a/docs/src/developers/leaflet/filter.md +++ b/docs/src/developers/leaflet/filter.md @@ -5,6 +5,6 @@ Filter expressions in FacilMap can be used to show/hide markers and lines on col facilmap-leaflet injects the following properties and methods into [Leaflet map](https://leafletjs.com/reference.html#map) objects to use filters: * `setFmFilter(filter)`: Set the current filter expression. `filter` is a string with the filter expression or `undefined`. An exception is thrown if the filter expression is invalid. * `fmFilter`: The current filter expression (string or undefined). -* `fmFilterFunc(object, type)`: Returns a boolean that indicates whether the specified object matches the current filter. `object` can be a [Marker](../client/types#marker) or [Line](../client/types#line), and `type` is its [Type](../client/types#type). +* `fmFilterFunc(object, type)`: Returns a boolean that indicates whether the specified object matches the current filter. `object` can be a [Marker](../client/types.md#marker) or [Line](../client/types.md#line), and `type` is its [Type](../client/types.md#type). -When the filter is updated using `setFmFilter()`, the map fires an `fmFilter` event. Other FacilMap Leaflet components ([`MarkersLayer`](./markers), [`LinesLayer`](./lines), [`HashHandler`](./hash)) react to this event and update their state accordingly. \ No newline at end of file +When the filter is updated using `setFmFilter()`, the map fires an `fmFilter` event. Other FacilMap Leaflet components ([`MarkersLayer`](./markers.md), [`LinesLayer`](./lines.md), [`HashHandler`](./hash.md)) react to this event and update their state accordingly. \ No newline at end of file diff --git a/docs/src/developers/leaflet/hash.md b/docs/src/developers/leaflet/hash.md index 47741359..6368f7df 100644 --- a/docs/src/developers/leaflet/hash.md +++ b/docs/src/developers/leaflet/hash.md @@ -6,9 +6,9 @@ FacilMap can store the current map view in the location hash. The details can be `HashHandler` handles the different details encoded in the location hash in the following way: * Longitude, latitude, zoom level: automatically synchronised. -* Active layers: automatically synchronised (using the [FacilMap layer helpers](./layers)). +* Active layers: automatically synchronised (using the [FacilMap layer helpers](./layers.md)). * Search term: needs to be synchronised manually (see [below](#search-term)). -* Active filter: automatically synchronised (using the [filter map extension](./filter)). +* Active filter: automatically synchronised (using the [filter map extension](./filter.md)). `HashHandler` also has support for saved views. If the position of the map is exactly that of a saved view, the location hash will be set to something like `#q=v123`. @@ -27,7 +27,7 @@ const hashHandler = new HashHandler(map, client).enable(); ## HashHandler and initial view -facilmap-leaflet provides helper methods to set the [initial view](./views#initial-view) of a map. However, when opening the map with a specific map view already present in the location hash, loading the initial view would cause unnecessary network requests and jumping of the map if the hash handler would move the map position immediately afterwards. +facilmap-leaflet provides helper methods to set the [initial view](./views.md#initial-view) of a map. However, when opening the map with a specific map view already present in the location hash, loading the initial view would cause unnecessary network requests and jumping of the map if the hash handler would move the map position immediately afterwards. When the hash handler is enabled for the first time, it checks whether a map view is present in the location hash. If there is, it zooms to that view, otherwise it leaves the map position untouched. This means that if the hash handler is enabled on a map whose position is not initialised yet, the position remains uninitialised if no position is present in the location hash. This can be checked by checking whether `map._loaded` is defined or not, and loading the initial view only if it is not. diff --git a/docs/src/developers/leaflet/layers.md b/docs/src/developers/leaflet/layers.md index 0daeaf93..ed4e9d58 100644 --- a/docs/src/developers/leaflet/layers.md +++ b/docs/src/developers/leaflet/layers.md @@ -2,8 +2,8 @@ In Leaflet, a lot of different types of objects are layers internally, for example tile layers, polylines, markers and even tooltips. In the context of FacilMap, there are base layers (tile layers that make up the main map style, only one can be active at a time) and overlays (layers that are shown on top of the base layer). These layers are used in the following way: * The frontend offers the user to change which base layer and which overlays are visible -* [Saved views](./views) contain information about which base layer and which overlays should be visible -* The [location hash](./hash) stores which base layer and which overlays are visible. +* [Saved views](./views.md) contain information about which base layer and which overlays should be visible +* The [location hash](./hash.md) stores which base layer and which overlays are visible. facilmap-leaflet maintains a list of available base layers and overlays. This list is used by the layer picker in the frontend to show the available layers to the user, but it is also used when for views and the location hash to distinguish which layers on a map are FacilMap layers and which are other types of Leaflet layers. diff --git a/docs/src/developers/leaflet/lines.md b/docs/src/developers/leaflet/lines.md index f9484725..143426e2 100644 --- a/docs/src/developers/leaflet/lines.md +++ b/docs/src/developers/leaflet/lines.md @@ -17,7 +17,7 @@ const linesLayer = new LinesLayer(client).addTo(map); `LinesLayer` also has the following features: * Lines get a tooltip with their name. * It automatically reacts to changes. When lines are created, changed or deleted, these changes are reflected on the map. `LinesLayer` can also be added before a collaborative map is opened, and will draw the lines as soon as a map is opened. -* It shows/hides the appropriate lines if a [filter](./filter) is set. +* It shows/hides the appropriate lines if a [filter](./filter.md) is set. ## Handle line clicks @@ -87,4 +87,4 @@ The code that styles lines on FacilMap has been moved into an external module ca ## Hide a line -Calling `linesLayer.hideLine(lineId)` hides a line until `linesLayer.unhideLine(lineId)` is called. The frontend uses this function to temporarily make a line draggable by calling [client.lineToRoute()](../client/methods#linetoroute-data) to convert the line to a route and hiding the line until the dragging has finished. \ No newline at end of file +Calling `linesLayer.hideLine(lineId)` hides a line until `linesLayer.unhideLine(lineId)` is called. The frontend uses this function to temporarily make a line draggable by calling [client.lineToRoute()](../client/methods.md#linetoroute-data) to convert the line to a route and hiding the line until the dragging has finished. \ No newline at end of file diff --git a/docs/src/developers/leaflet/markers.md b/docs/src/developers/leaflet/markers.md index a3714afd..33f96eae 100644 --- a/docs/src/developers/leaflet/markers.md +++ b/docs/src/developers/leaflet/markers.md @@ -18,7 +18,7 @@ const markersLayer = new MarkersLayer(client).addTo(map); * It clusters markers if this has been enabled in the map settings. * Markers get a tooltip with their name. * It automatically reacts to changes. When markers are created, changed or deleted, these changes are reflected on the map. `MarkersLayer` can also be added before a collaborative map is opened, and will draw the markers as soon as a map is opened. -* It shows/hides the appropriate markers if a [filter](./filter) is set. +* It shows/hides the appropriate markers if a [filter](./filter.md) is set. ## Handle marker clicks diff --git a/docs/src/developers/leaflet/route.md b/docs/src/developers/leaflet/route.md index b0235483..06f6d3f2 100644 --- a/docs/src/developers/leaflet/route.md +++ b/docs/src/developers/leaflet/route.md @@ -1,10 +1,10 @@ # Route -Routes in FacilMap are temporarily stored on the server in the scope of one particular client connection, unrelated to any collaborative map that is opened. This makes it possible that only the track points appropriate for the current bounding box and zoom level have to be received by the client, rather than the whole route in all detail. Multiple routes can be active at the same time by specifying a custom `routeId` when calling [setRoute()](../client/methods#setroute-data). +Routes in FacilMap are temporarily stored on the server in the scope of one particular client connection, unrelated to any collaborative map that is opened. This makes it possible that only the track points appropriate for the current bounding box and zoom level have to be received by the client, rather than the whole route in all detail. Multiple routes can be active at the same time by specifying a custom `routeId` when calling [setRoute()](../client/methods.md#setroute-data). ## Show a route -`RouteLayer` renders a route with one particular `routeId` on the map. As long as no route with that `routeId` is active, no route is shown, and as soon as a route is received, it is automatically rendered. An example usage pattern would be that you have one routing form that uses a fixed `routeId`, which would control the active route using [setRoute()](../client/methods#setroute-data) and [clearRoute()](../client/methods#clearroute-data), and there would be one `RouteLayer` for that `routeId` constantly present on the map which would always show the current state of the route. +`RouteLayer` renders a route with one particular `routeId` on the map. As long as no route with that `routeId` is active, no route is shown, and as soon as a route is received, it is automatically rendered. An example usage pattern would be that you have one routing form that uses a fixed `routeId`, which would control the active route using [setRoute()](../client/methods.md#setroute-data) and [clearRoute()](../client/methods.md#clearroute-data), and there would be one `RouteLayer` for that `routeId` constantly present on the map which would always show the current state of the route. The `RouteLayer` constructor accepts the following arguments: * A client instance diff --git a/docs/src/developers/leaflet/search.md b/docs/src/developers/leaflet/search.md index adf5860e..7e749dd7 100644 --- a/docs/src/developers/leaflet/search.md +++ b/docs/src/developers/leaflet/search.md @@ -3,7 +3,7 @@ ## Show search results `SearchResultsLayer` renders search results as markers, lines and polygons on the map. The constructor accepts the following arguments: -* `results`: An array of search results as returned by [client.find()](../client/methods#find-data). You can also leave this `undefined` and add results later using `setResults()`. +* `results`: An array of search results as returned by [client.find()](../client/methods.md#find-data). You can also leave this `undefined` and add results later using `setResults()`. * `options`: An optional object containing the following properties: * `markerColour`: A 6-digit colour to use for search result markers, defaults to `000000` * `markerSize`: The height of search result markers in pixels, defaults to `35` diff --git a/docs/src/developers/leaflet/views.md b/docs/src/developers/leaflet/views.md index becaadc9..ab66d2e0 100644 --- a/docs/src/developers/leaflet/views.md +++ b/docs/src/developers/leaflet/views.md @@ -2,12 +2,12 @@ Views in FacilMap are a particular bounding box on the map, with a particular set of layers visible and possibly an active filter. Views can be saved as part of collaborative maps. More details can be found in the [User guide](../../users/views/). -A view object represents a view. Its shape is documented in the [Client API](../client/types#view). Note that only objects that represent saved views will have an `id`. +A view object represents a view. Its shape is documented in the [Client API](../client/types.md#view). Note that only objects that represent saved views will have an `id`. ## Current view -`getCurrentView(map, includeFilter)` returns a view object that represents the current view of the map. If `includeFilter` is `true`, the current [filter](./filter) is included in the object (if there is one), otherwise it is omitted. +`getCurrentView(map, includeFilter)` returns a view object that represents the current view of the map. If `includeFilter` is `true`, the current [filter](./filter.md) is included in the object (if there is one), otherwise it is omitted. `isAtView(map, view)` returns a boolean that indicates whether the current map view is equal to the view represented by the specified view object. If the `view` object is omitted, the method will indicate whether the current map shows the fallback view (the whole world). @@ -21,7 +21,7 @@ A view object represents a view. Its shape is documented in the [Client API](../ `getInitialView(client)` returns a promise that is resolved with one of the following, in order: * If a collaborative map is open and a default view is configured, that view is returned. -* Otherwise, an attempt is made to guess the position of the user using [geoip](../client/methods#geoip). If a guess could be made, a view object representing the rough area is returned. +* Otherwise, an attempt is made to guess the position of the user using [geoip](../client/methods.md#geoip). If a guess could be made, a view object representing the rough area is returned. * Otherwise, `undefined` is returned. Here is an example how the initial view could be set: diff --git a/docs/src/developers/server/README.md b/docs/src/developers/server/README.md index ca2fda8c..db7b2e84 100644 --- a/docs/src/developers/server/README.md +++ b/docs/src/developers/server/README.md @@ -7,5 +7,5 @@ The FacilMap server is a HTTP server that fulfills the following tasks: * Maintain a connection to a database where collaborative map data and calculated routes are stored. The official FacilMap server is running on [https://facilmap.org/](https://facilmap.org/). If you want, you can run your own FacilMap server using one of these options: -* [Docker](./docker) will run the server in an isolated container. It is easer to set up and more secure, but takes more resources. -* Running the server [standalone](./standalone) takes less resources, but is less secure and takes more steps to set up. \ No newline at end of file +* [Docker](./docker.md) will run the server in an isolated container. It is easer to set up and more secure, but takes more resources. +* Running the server [standalone](./standalone.md) takes less resources, but is less secure and takes more steps to set up. \ No newline at end of file diff --git a/docs/src/developers/server/docker.md b/docs/src/developers/server/docker.md index 33ed0b56..67cf7cef 100644 --- a/docs/src/developers/server/docker.md +++ b/docs/src/developers/server/docker.md @@ -4,7 +4,7 @@ This manual assumes that you have docker set up on your system. -The FacilMap server is available as [`facilmap/facilmap`](https://hub.docker.com/r/facilmap/facilmap/) on Docker Hub. The [configuration](./config) can be defined using environment variables. The container will expose a HTTP server on port 8080, which you should put behind a reverse proxy such as [nginx-proxy](https://hub.docker.com/r/jwilder/nginx-proxy) or [traefik](https://traefik.io/traefik/) for HTTPS support. +The FacilMap server is available as [`facilmap/facilmap`](https://hub.docker.com/r/facilmap/facilmap/) on Docker Hub. The [configuration](./config.md) can be defined using environment variables. The container will expose a HTTP server on port 8080, which you should put behind a reverse proxy such as [nginx-proxy](https://hub.docker.com/r/jwilder/nginx-proxy) or [traefik](https://traefik.io/traefik/) for HTTPS support. FacilMap needs a database supported by [Sequelize](https://sequelize.org/master/) to run, it is recommended to use MySQL/MariaDB. When creating a database for FacilMap, make sure to use the `utf8mb4` charset/collation to make sure that characters from all languages can be used on a map. By default, MySQL/MariaDB uses the `latin1` charset, which mostly supports only basic latin characters. When you start the FacilMap server for the first time, the necessary tables are created using the charset of the database. @@ -32,7 +32,7 @@ services: MAPBOX_TOKEN: # Get an API key on https://www.mapbox.com/signup/ (needed for routing) MAPZEN_TOKEN: # Get an API key on https://mapzen.com/developers/sign_up (needed for elevation info) MAXMIND_USER_ID: # Sign up here https://www.maxmind.com/en/geolite2/signup (needed for geoip lookup to show initial map state) - MAXMIND_LICENSE_KEY: + MAXMIND_LICENSE_KEY: restart: unless-stopped db: image: mariadb diff --git a/docs/src/developers/server/standalone.md b/docs/src/developers/server/standalone.md index 173617aa..2a453f15 100644 --- a/docs/src/developers/server/standalone.md +++ b/docs/src/developers/server/standalone.md @@ -11,7 +11,7 @@ A bundled version of the FacilMap server is published on NPM as [facilmap-server 1. If you don’t have a global NPM prefix set up yet, run `npm config set prefix ~/.local`. This will install npm packages into `~/.local/bin`, rather than trying to install them into `/usr/local/bin`. 2. Install facilmap-server by running `npm install -g facilmap-server` -3. Create a `config.env` file based on [`config.env.example`](https://github.com/FacilMap/facilmap/blob/master/config.env.example) and to adjust the [configuration](./config). +3. Create a `config.env` file based on [`config.env.example`](https://github.com/FacilMap/facilmap/blob/master/config.env.example) and to adjust the [configuration](./config.md). 4. Start the FacilMap server by running `~/.local/bin/facilmap-server dotenv_config_path=config.env`. FacilMap will need write access to the directory `~/.local/lib/node_modules/facilmap-server/cache`. All other files and directories can be read-only. To harden the FacilMap installation, make the whole installation folder owned by root, but create the cache directory and make it owned by the facilmap user. @@ -26,7 +26,7 @@ To run the latest state from the [FacilMap repository](https://github.com/FacilM 2. Clone the [FacilMap repository](https://github.com/FacilMap/facilmap). 3. Run `yarn install` in the root folder of this repository to install the dependencies. 4. Run `yarn build` to create the JS bundles. -5. Copy `config.env.example` to `config.env` and adjust the [configuration](./config). +5. Copy `config.env.example` to `config.env` and adjust the [configuration](./config.md). 6. Inside the `server` directory, run `yarn server`. This will automatically set up the database structure and start the server. -You can also run `yarn dev-server`, which will automatically rebuild the frontend bundle when the code is changed. See [dev setup](../development/dev-setup) for more information. \ No newline at end of file +You can also run `yarn dev-server`, which will automatically rebuild the frontend bundle when the code is changed. See [dev setup](../development/dev-setup.md) for more information. \ No newline at end of file