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
```
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
```
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
```
Now, anywhere on your page, you can add a `facilmap` element:
```html
```
`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
```
To keep the current map view saved in the browser’s URL bar, add the `fm-hash` component:
```html
```
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
```
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
```
### `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.