kopia lustrzana https://github.com/FacilMap/facilmap
185 wiersze
6.3 KiB
Markdown
185 wiersze
6.3 KiB
Markdown
Embedding FacilMap into a website
|
||
=================================
|
||
|
||
Using an iframe
|
||
---------------
|
||
|
||
It is perfectly fine to embed a map from [facilmap.org](https://facilmap.org/) into an iframe.
|
||
|
||
```html
|
||
<iframe style="height: 500px; width: 100%; border: none;" src="https://facilmap.org/mymap"></iframe>
|
||
```
|
||
|
||
If you use a map ID that does not exist yet, the “Create Collaborative Map” dialog will be opened when accessing the
|
||
map.
|
||
|
||
Directly into a page
|
||
--------------------
|
||
|
||
Install facilmap-frontend as a dependency using npm or yarn:
|
||
|
||
```bash
|
||
npm install --save facilmap-frontend
|
||
```
|
||
|
||
or
|
||
|
||
```bash
|
||
yarn add facilmap-frontend
|
||
```
|
||
|
||
or load the client directly from facilmap.org:
|
||
|
||
```html
|
||
<script src="https://facilmap.org/frontend.js"></script>
|
||
```
|
||
|
||
If you application is using Webpack, require the dependency like this:
|
||
|
||
```js
|
||
import 'facilmap-frontend';
|
||
```
|
||
|
||
Note that for this you will have to look into the [webpack.config.js](./webpack.config.js) file and configure your
|
||
loaders in a similar way. To include the whole bundle with all the dependencies, use this instead:
|
||
|
||
```js
|
||
import 'facilmap-frontend/build/frontend';
|
||
```
|
||
|
||
Now, if your web application is already using Angular JS, add `facilmap` as a dependency:
|
||
|
||
```js
|
||
angular.module("myApp", ["facilmap"]);
|
||
```
|
||
|
||
Otherwise, bootstrap FacilMap like this:
|
||
|
||
```html
|
||
<!DOCTYPE html>
|
||
<html ng-app="facilmap">
|
||
```
|
||
|
||
Now, anywhere on your page, you can add a `facilmap` element:
|
||
|
||
```html
|
||
<facilmap fm-server-url="https://facilmap.org/" fm-map-id="mymap"></facilmap>
|
||
```
|
||
|
||
`fm-map-id` is the map ID as it would appear on `https://facilmap.org/`**`mymap`**. It can be a read-only or read-write ID.
|
||
|
||
By default, the search bar, toolbox and legend are added to the map. Alternatively, you can specify your own selection
|
||
of components by adding them to the element:
|
||
|
||
```html
|
||
<facilmap fm-server-url="https://facilmap.org/" fm-map-id="mymap">
|
||
<fm-toolbox></fm-toolbox>
|
||
<fm-search></fm-search>
|
||
<fm-legend></fm-legend>
|
||
</facilmap>
|
||
```
|
||
|
||
To keep the current map view saved in the browser’s URL bar, add the `fm-hash` component:
|
||
|
||
```html
|
||
<facilmap fm-server-url="https://facilmap.org/" fm-map-id="mymap" fm-hash></facilmap>
|
||
```
|
||
|
||
|
||
Development
|
||
===========
|
||
|
||
Build it yourself
|
||
-----------------
|
||
|
||
Make sure to have yarn installed. Install the dependencies using `yarn run deps` and bundle the JavaScript
|
||
by running `yarn run build`.
|
||
|
||
A better way to develop the frontend is to start facilmap-server in dev mode. It will set up a webpack-dev-server that
|
||
automatically recompiles the frontend when a file changes, and even delays reloads until compilation has finished.
|
||
|
||
Create an extension
|
||
-------------------
|
||
|
||
The `facilmap` directive exports several useful objects that can be used to write own UI components or features that
|
||
extend the map.
|
||
|
||
### Create a directive
|
||
|
||
Create an element directive like this:
|
||
|
||
```javascript
|
||
fm.app.directive("myFacilmapExtension", function() {
|
||
return {
|
||
restrict: "E",
|
||
require: "^facilmap",
|
||
scope: {},
|
||
link: function(scope, element, attrs, facilmapController) {
|
||
// Do something here
|
||
}
|
||
};
|
||
});
|
||
```
|
||
|
||
This component can then be added to the map like this:
|
||
|
||
```html
|
||
<facilmap fm-server-url="https://facilmap.org/" fm-map-id="mymap">
|
||
<my-facilmap-extension></my-facilmap-extension>
|
||
</facilmap>
|
||
```
|
||
|
||
Or create an attribute directive like this:
|
||
|
||
```javascript
|
||
fm.app.directive("myFacilmapExtension", function() {
|
||
return {
|
||
restrict: "A",
|
||
require: "facilmap",
|
||
scope: {},
|
||
link: function(scope, element, attrs, facilmapController) {
|
||
// Do something here
|
||
}
|
||
};
|
||
});
|
||
```
|
||
|
||
This component can then be added to the map like this:
|
||
|
||
```html
|
||
<facilmap fm-server-url="https://facilmap.org/" fm-map-id="mymap" my-facilmap-extension></facilmap>
|
||
```
|
||
|
||
### `facilmapController`
|
||
|
||
`facilmapController` contains, among others, these methods and properties:
|
||
|
||
* `client`: An instance of `facilmap-client` that automatically starts a digest cycle in any of its methods and has these
|
||
additional methods/properties:
|
||
* `setFilter(filter)`: Sets the current filter expression
|
||
* `filterExpr`: The current filter expression
|
||
* `filterFunc(object)`: Runs the current filter expression against the specified marker/line
|
||
* `mapEvents`: An angular scope that acts as an event emitter, broadcasting the following events:
|
||
* `longmousedown`: The user has held the mouse at one point on the map for more than 1 second. A Leaflet `LatLng`
|
||
object is passed as parameter.
|
||
* `layerchange`: The selection of visible layers has changed
|
||
* `map`: The Leaflet map object. When adding layers, add the `fmName` and `fmKey` options to them to make them work with
|
||
the toolbox.
|
||
* `getCurrentView(addFilter)`: Returns a view object for the current map view. If `addFilter` is true, the current filter
|
||
is added to it.
|
||
* `displayView(view)`: Pan the map to the specified view
|
||
* `addClickListener(listener, moveListener)`: Wait for one click to the map. The `listener` function will receive a
|
||
`{lat, lon}` object with the position of the click. The `moveListener`
|
||
function will receive a `{lat, lon}` object on every mouse move until the
|
||
click. Returns a `{cancel}` object, where `cancel` is a method to cancel
|
||
the listener.
|
||
* `getLayerInfo()`: Returns a `{base, overlay}` object with arrays that contain information about the layers that the
|
||
map contains as `{visibility, name, permalinkName, attribution}` objects.
|
||
* `showLayer(key, show)`: Makes a layer (in)visible. `key` is the `fmKey` option of the layer, `show` indicates whether
|
||
the layer should be shown or hidden.
|
||
* `loadStart()`, `loadEnd()`: Something starts/finishes loading. A loading indicator will be shown as long as `loadStart()`
|
||
has been called more often than `loadEnd()`.
|
||
* `messages.showMessage(type, message, buttons, lifetime, onclose)`: Show a message. `type` is `success`, `info`, `warning`
|
||
or `danger`, `message` is the message text, `buttons` is an array of `{url, click, label}` objects (`url` is the button
|
||
href, `click` is the click handler), `lifetime` the lifetime in milliseconds if specified, `onclose` a close handler.
|
||
Returns a `{close}` object with a method to close the message. |