├── .bowerrc
├── .gitignore
├── Gruntfile.js
├── bower.json
├── license.txt
├── package.json
├── project.json
├── readme.rst
├── src
├── index.html
├── leaflet-map
│ ├── _template.html
│ ├── config-parser.js
│ ├── factories
│ │ ├── geojson.js
│ │ ├── markers.js
│ │ ├── tiles.js
│ │ └── tilesets.js
│ ├── factory.js
│ ├── leaflet-map.js
│ ├── leaflet-map.less
│ └── parsers
│ │ ├── geo-json.js
│ │ ├── map-marker.js
│ │ ├── map-options.js
│ │ └── tile-layer.js
└── states.geo.json
└── tasks
├── build.js
├── bundle.js
├── connect.js
├── lib
├── browserify-less.js
├── browserify-template.js
└── npm-less.js
├── publish.js
└── watch.js
/.bowerrc:
--------------------------------------------------------------------------------
1 | {
2 | "directory": "src/lib"
3 | }
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules/
2 | build/
3 | temp/
4 | src/lib/
5 | auth.json
6 | package-lock.json
--------------------------------------------------------------------------------
/Gruntfile.js:
--------------------------------------------------------------------------------
1 | module.exports = function(grunt) {
2 |
3 | //load tasks
4 | grunt.loadTasks("./tasks");
5 |
6 | grunt.registerTask("default", ["bundle", "build", "connect", "watch"]);
7 |
8 | };
9 |
--------------------------------------------------------------------------------
/bower.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "component-leaflet-map",
3 | "version": "0.0.5",
4 | "homepage": "https://github.com/seattletimes/component-leaflet-map",
5 | "authors": [
6 | "The Seattle Times"
7 | ],
8 | "license": "MIT",
9 | "ignore": [
10 | "**/.*",
11 | "node_modules",
12 | "bower_components",
13 | "src/lib",
14 | "test",
15 | "tests"
16 | ],
17 | "dependencies": {
18 | "document-register-element": "~0.1.6"
19 | }
20 | }
21 |
--------------------------------------------------------------------------------
/license.txt:
--------------------------------------------------------------------------------
1 | This program is free software: you can redistribute it and/or modify
2 | it under the terms of the GNU General Public License as published by
3 | the Free Software Foundation, either version 3 of the License, or
4 | (at your option) any later version.
5 |
6 | This program is distributed in the hope that it will be useful,
7 | but WITHOUT ANY WARRANTY; without even the implied warranty of
8 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
9 | GNU General Public License for more details.
10 |
11 | You should have received a copy of the GNU General Public License
12 | along with this program. If not, see .
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "component-leaflet-map",
3 | "description": "A reusable DSL for creating maps with Leaflet",
4 | "version": "0.0.20",
5 | "author": "Thomas Wilburn",
6 | "repository": {
7 | "type": "git",
8 | "url": "https://github.com/seattletimes/component-leaflet-map.git"
9 | },
10 | "main": "src/leaflet-map/leaflet-map",
11 | "dependencies": {
12 | "component-responsive-frame": "^1.4.2",
13 | "dot": "^1.0.2",
14 | "leaflet": "^1.7.1",
15 | "less": "^2.0.0",
16 | "resolve": "^1.1.6"
17 | },
18 | "devDependencies": {
19 | "async": "^0.9.0",
20 | "aws-sdk": "^2.0.0-rc.19",
21 | "browserify": "^16.5.0",
22 | "chalk": "^0.5.1",
23 | "exorcist": "^0.1.6",
24 | "grunt": "^1.0.4",
25 | "grunt-contrib-connect": "^2.0.0",
26 | "grunt-contrib-watch": "^1.1.0",
27 | "mime": "^1.2.11",
28 | "shelljs": "^0.3.0",
29 | "through2": "^0.6.3"
30 | },
31 | "browser": {
32 | "leaflet": "leaflet/dist/leaflet.js"
33 | },
34 | "browserify": {
35 | "transform": [
36 | "./tasks/lib/browserify-template",
37 | "./tasks/lib/browserify-less"
38 | ]
39 | }
40 | }
41 |
--------------------------------------------------------------------------------
/project.json:
--------------------------------------------------------------------------------
1 | {
2 | "s3": {
3 | "live": {
4 | "bucket": "apps.seattletimes.com",
5 | "path": "tags/leaflet-map"
6 | }
7 | }
8 | }
9 |
--------------------------------------------------------------------------------
/readme.rst:
--------------------------------------------------------------------------------
1 | component-leaflet-map
2 | =====================
3 |
4 | A custom element for instantiating Leaflet maps and feeding them data. When finished, usage will look something like this::
5 |
6 |
7 |
8 | Popup text!
9 |
10 | OR GEOJSON DATA GOES HERE
11 |
12 |
13 |
14 |
15 |
16 | { "stroke": false, "fillOpacity": 0.6 }
17 |
18 |
19 | I'm templated, with values from {{FEATURE_PROPERTY}} injected automatically!
20 |
21 |
22 |
23 |
24 | GeoJSON represents the most significant portion of ```` development, with the ability to automatically color and bind popups to the vector layer. The templating for popups is extremely primitive and only supports direct string value substitution (no loops, no expressions, no formatters), but this covers most of the required cases and provides predictable results for users. More advanced users will probably want to go through the ``map`` and ``leaflet`` properties exposed on the element anyway.
25 |
26 | Any elements with an ID will be made available after instantiation on the element's ``lookup`` property. For example, in the code above, we could manipulate the map marker via ``document.querySelector("leaflet-map").lookup.findMe``. Tile layers and GeoJSON layers are also available for manipulation this way.
27 |
28 | Currently, custom elements are upgraded asynchronously, which means that their contents may be momentarily visible in the DOM, especially if you have a lot of GeoJSON or configuration embedded. However, once the element has been upgraded, it will add a ``ready`` attribute for styling. The following CSS rule can be used to prevent a flash of unstyled content (FOUC)::
29 |
30 | leaflet-map:not([ready]) { display: none }
31 |
32 | ```` is built on top of our `component template `_.
33 |
34 | Elements
35 | ========
36 |
37 | The Leaflet map is configured and initialized with a domain-specific language built out of custom tags, on the working assumption that it's easier to write HTML than it is to write JavaScript. The following tags are supported for setting up the map. Once it's initialized, you can access the map itself through the ``map`` property on the ```` element, and you can also get access to Leaflet itself through the ``leaflet`` property.
38 |
39 | The ```` element itself exposes several configuration properties via attributes, including:
40 |
41 | * ``lat`` and ``lng`` - center the map on the specified coordinate
42 | * ``zoom``
43 | * ``fixed`` - disables zoom and pan functionality
44 |
45 | \
46 | --------------
47 |
48 | Tile layers can be initialized in two ways. You can set them up manually, by providing the ``url`` and ``subdomains`` attributes, or you can set ``layer`` to one of the following values in order to use a preset basemap. Many of the ``esri`` layers come in two parts: one for the background, and one for the labels, which makes it easier to create maps without distracting text details when adding data.
49 |
50 | * ``lite`` - Stamen Toner Lite
51 | * ``background`` - Stamen Toner Background
52 | * ``toner`` - Stamen Toner
53 | * ``watercolor`` - Stamen Watercolor
54 | * ``terrain`` - Stamen Terrain
55 | * ``esriStreets``
56 | * ``esriTopographic``
57 | * ``esriOceans``
58 | * ``esriOceansLabels``
59 | * ``esriNationalGeographic``
60 | * ``esriDarkGray``
61 | * ``esriDarkGrayLabels``
62 | * ``esriGray``
63 | * ``esriGrayLabels``
64 | * ``esriImagery``
65 | * ``esriImageryLabels``
66 | * ``esriImageryTransportation``
67 | * ``esriShadedRelief``
68 | * ``esriShadedReliefLabels``
69 | * ``esriTerrain``
70 | * ``esriTerrainLabels``
71 | * ``cartoPositron``
72 | * ``cartoPositronBlank`` - No labels
73 | * ``cartoDarkMatter``
74 | * ``cartoDarkMatterBlank`` - No labels
75 |
76 | ```` also supports the ``opacity`` attribute, in order to overlay basemaps on top of each other.
77 |
78 | \
79 | --------------
80 |
81 | Set the position of the map marker using the ``lat`` and ``lng`` attributes. Any classes on the ```` element will be set on the resulting Leaflet DivIcon marker. Content inside a ```` is bound to its popup. This makes these elements combine powerfully with EJS template loops, like so::
82 |
83 | <% data.forEach(function(item) { %>
84 |
85 |
<%= item.title %>
86 |
<%= item.description %>
87 |
88 | <% }); %>
89 |
90 | \
91 | ------------
92 |
93 | The most complicated element, ```` uses several sub-elements to load and annotate GeoJSON files. You can provide the GeoJSON directly, using a ```` element (this is the template's default) or load it via AJAX by specifying a ``src`` attribute on the ````.
94 |
95 | The ```` element should contain strict JSON (e.g. all decimals should have leading zeros, property names should be double quoted, etc.) matching Leaflet's `path style options `_. These styles will be overridden/supplemented by any coloring specified in the ```` element, which is keyed via the ``property`` attribute to the properties hash on each GeoJSON feature.
96 |
97 | ```` allows you to bind HTML to the GeoJSON layer with some very simple templating, substituting in any property from the feature. Loops, conditionals, and formatting are not supported yet, so make sure your GeoJSON contains properly-formatted data to be used in the popup.
98 |
99 | \
100 | ---------------
101 |
102 | In addition to the options exposed as ```` attributes, you can also set the configuration object for the map directly, by providing JSON matching the `Leaflet map options hash `_.
103 |
104 | Behind the scenes
105 | =================
106 |
107 | The element breaks down its startup process into two parts, both of which take place during the custom element's ``createdCallback``.
108 |
109 | 1. Configuration parsing
110 | 2. Layer factories
111 |
112 | In the first step, the element and its contents are processed by the modules in the ``parsers`` directory. Tags inside the element are processed as a domain-specific language for various map features (they are not full-fledged custom elements). The parser modules are called with the config object as ``this`` and passed any elements inside the ```` that match the selectors defined in ``config-parser.js``, so that they can add their results to the configuration.
113 |
114 | The map and the configuration object are then passed to the factory module, which calls individual layer factories to consume the configuration and attach their layers to the map. Factories are also passed a reference to the custom element, so that they can perform any higher-level manipulation (such as attaching references to its ``lookup`` property when a layer has an ID attribute).
115 |
116 | At the end of startup, the ```` element will also have two properties available for consumption by external scripts: ``map`` contains the Leaflet instance inside the element, and ``leaflet`` contains the actual library, in case additional layers or utility functions need to be called.
117 |
--------------------------------------------------------------------------------
/src/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
28 |
29 |
30 |