meshviewer/README.md

[![Build Status](https://travis-ci.org/ffrgb/meshviewer.svg?branch=develop&style=flat-square)](https://travis-ci.org/ffrgb/meshviewer)

### Main differences to https://github.com/ffnord/meshviewer
#### Some features are maybe merged

- Add modes - For example add a night layer and style
- Updates selected node or list (incl. image stats cache-breaker) - not only overview tables
- Node filter is implemented
- Zoom level if you click a node (`nodeZoom`) - Zoom level 22 available, but it is to close for a click
- Formatted Code
- Translation support - https://crowdin.com/project/meshviewer - Contact us for new languages
- Grunt inline for some css and js - less requests
- Icon font with only needed icons
- Upgrade to grunt v1.x (Tested with Node.js 4 LTS,6 LTS,7 Linux,OSX,W**)
  - Inline some css and js
- Remove bower in favour of npm/yarn
  - Load only  moment.js without languages - Languages included in translations
  - Remove unneeded components (es6-shim, tablesort, numeraljs, leaflet-providers, jshashes)
- Rbush v2 - performance boost in last versions. (Positions labels and clients on the map)
- Right click open layermenu
- Remove ruby dependency
- FixedCenter is required
- Rewrite Scss, SASS lint and variables for easy customization/adjustments
- Improved cross browser/device support THX@BrowserStack
- Leaflet with patch to avoid IE/Edge crashes
- Add yarn package manager in favor of npm (npm still works)
- Configurable reverse geocoding server
- [A lot more in commit history](https://github.com/ffrgb/meshviewer/commits/develop)

# Demo (embedded):

https://regensburg.freifunk.net/netz/karte/

# Screenshots

> TODO new uptodate images

# Dependencies

- yarn
- grunt-cli

# Installing dependencies

### npm is still possible, but yarn is much faster https://yarnpkg.com/

Install yarn package-manager:

    Chosse your OS and install yarn https://yarnpkg.com/en/docs/install

Execute these commands on your server as a normal user to prepare the dependencies:

    git clone https://github.com/ffrgb/meshviewer.git
    cd meshviewer
    yarn
    # Only needed when no global grunt exists
    yarn global add grunt-cli

# Building

Just run the following command from the meshviewer directory:

    grunt

This will generate `build/` containing all required files.

## Development

Use `grunt serve` for development.

## Support/Help

- IRC: irc.hackint.org #freifunkRGB
- Feel free to open an issue for a problem or a idea.

# Configure

Change `config.json`to match your community.


## Customize style

Start your development and edit files in `scss/custom/`. Additional information in comments.

## dataPath (string/array)

`dataPath` can be either a string containing the address of a Nodes.json v2 compatible backend (e.g. ffmap backend) or an array containing multiple addresses.
Don't forget the trailing slash!
Also, proxying the data through a webserver will allow GZip and thus will greatly reduce bandwidth consumption.
It may help with firewall problems too.

## siteName (string)

Change this to match your communities' name. It will be used in various places.

## maxAge (integer)

Nodes being online for less than maxAge days are considered "new". Likewise,
nodes being offline for more than than maxAge days are considered "lost".

## maxAgeAlert (integer)

Nodes being offline for more than than maxAge days are considered "lost".
Lost will be splitted in alert and lost.

## nodeZoom (integer)

Max level to be applied by clicking a node or open a node. With value `18` near by buildings and streets should be visible.
Interesting if one of configured map provider has zoom-level under `18`.

## labelZoom (integer)

Min. level for node labels shown on the map. Labels aren't shown in first zoom levels and need performance.

## clientZoom (integer)

Min. level to set starting layer for client dots on map.

## nodeInfobox

#### contact (bool)

Setting this to `false` will hide contact information for nodes.

#### hardwareUsage (bool)

Setting this to `false` will hide bars of memory usage and load avg for nodes.

## mapLayers (List)

A list of objects describing map layers. Each object has at least `name`, `url` and `config` properties. [Example layers and configuration](http://leaflet-extras.github.io/leaflet-providers/preview/) (map against config.json).

### Additional arguments

#### mode (string)

Allows to load a additional style for a night mode or similar use case. Possible are inline style or link. 
Inline avoids re-rendering and maybe issues with label-layer update. Important are class "css-mode mode-name" and media "not".

_Default is night.css inline in index.html_

```html
 <link rel="stylesheet" class="css-mode mode-name" media="not" href="mode-name.css">
```

or

```html
<style class="css-mode mode-name" media="not">
   <inline src="mode-name.css" />
</style>
```

#### start (integer)

Start a time range to put this mapLayer on first position.

#### end (integer)

End a time range for first map. Stops sort this mapLayer.

## fixedCenter (array[array, array])

Choose a rectangle that must be displayed on the map. Set 2 Locations and everything between will displayed.

Examples for `fixedCenter`:

      // Set a visible frame
      "fixedCenter": [
        [
          49.3522,
          11.7752
        ],
        [
          48.7480,
          12.8917
        ]
      ],

## nodeInfos (array, optional)

This option allows to show node statistics depending on following case-sensitive parameters:

- `name` caption of statistics segment in infobox
- `href` absolute or relative URL to statistics image
- `thumbnail` absolute or relative URL to thumbnail image,
  can be the same like `href`
- `caption` is shown, if `thumbnail` is not present (no thumbnail in infobox)

To insert current node-id in either `href`, `thumbnail` or `caption`
you can use the case-sensitive template string `{NODE_ID}`, `{NODE_NAME}`, `{LOCALE}` and `{TIME}` as cache-breaker.

Examples for `nodeInfos`:

    "nodeInfos": [

      { "name": "Clientstatistik",
        "href": "stats/dashboard/db/node-byid?var-nodeid={NODE_ID}",
        "thumbnail": "stats/render/dashboard-solo/db/node-byid?panelId=1&fullscreen&theme=light&width=600&height=300&var-nodeid={NODE_ID}&var-host={NODE_NAME}&_t={TIME}",
        "caption": "Knoten {NODE_ID}"
      },
      { "name": "Uptime",
        "href": "stats/dashboard/db/node-byid?var-nodeid={NODE_ID}",
        "thumbnail": "stats/render/dashboard-solo/db/node-byid?panelId=2&fullscreen&theme=light&width=600&height=300&var-nodeid={NODE_ID}&_t={TIME}",
        "caption": "Knoten {NODE_ID}"
      }
    ]

In order to have statistics images available, you have to set up an instance of each [Prometheus](http://prometheus.io/) and [Grafana](http://grafana.org/).

## globalInfos (array, optional)

This option allows to show global statistics on statistics page depending on following case-sensitive parameters:

- `name` caption of statistics segment in infobox
- `href` absolute or relative URL to statistics image
- `thumbnail` absolute or relative URL to thumbnail image,
  can be the same like `href`
- `caption` is shown, if `thumbnail` is not present (no thumbnail in infobox)

In contrast to `nodeInfos` there is no template substitution in  `href`, `thumbnail` or `caption`.

Examples for `globalInfos` using Grafana server rendering:

    "globalInfos": [
      { "name": "Wochenstatistik",
        "href": "stats/render/render/dashboard-solo/db/global?panelId=1&fullscreen&theme=light&width=600&height=300",
        "thumbnail": "nodes/globalGraph.png",
        "caption": "Bild mit Wochenstatistik"
      }
    ]

## linkInfos (array, optional)

This option allows to show link statistics depending on the following case-sensitive parameters:

- `name` caption of statistics segment in infobox
- `href` absolute or relative URL to statistics image
- `thumbnail` absolute or relative URL to thumbnail image,
  can be the same like `href`
- `caption` is shown, if `thumbnail` is not present (no thumbnail in infobox)

To insert the source or target node-id in either `href`, `thumbnail` or `caption`
you can use the case-sensitive template strings `{SOURCE_ID}`, `{TARGET_ID}`, `{SOURCE_NAME}`, `{TARGET_NAME}`, `{LOCALE}` and `{TIME}` as cache-breaker.

    "linkInfos": [
      { "href": "stats/dashboard/db/links?var-source={SOURCE_ID}&var-target={TARGET_ID}",
        "thumbnail": "stats/render/dashboard-solo/db/links?panelId=1&fullscreen&theme=light&width=800&height=600&var-source={SOURCE_ID}&var-target={TARGET_ID}&_t={TIME}"
      }
    ]

## siteNames (array, optional)

In this array name definitions for site statistics and node info can be saved. This requires one object for each site code. This object must contain:

- `site` the site code
- `name` the defined written name for this site code

If neither `siteNames` nor `showSites` are set, site statistics and node info won't be displayed

Example for `siteNames`:

    "siteNames": [
      { "site": "ffhl", "name": "Lübeck" },
      { "site": "ffeh", "name": "Entenhausen" ),
      { "site": "ffgt", "name": "Gothamcity" },
      { "site": "ffal", "name": "Atlantis" }
    ]
    
    
## supportedLocale (array)

Add supported locale (with matching language file in locales/*.json) and it will be matched against the browser language setting. Fallback is the first language in the array.

Example for `supportedLocale`:

    "supportedLocale": [
      "en",
      "de",
      "fr"
    ]
    
## cacheBreaker (string)

Will be replaced in every build to avoid missing or outdated language strings, because language.json isn't up to date.

_Fixed value (y0z)._

## Sponsoring / Supporting
- [BrowserStack](https://www.browserstack.com/) for providing a awesome testing service for hundreds of browsers
- [Travis CI](https://travis-ci.org/) for testing every push and pull request
- [Crowdin](https://crowdin.com/) for providing easy non-developer translation environment

These tools need a lot of infrastructure behind and don't charge open source software