GeoJSON API

Introduction

The GeoJSON API is provided as a library to convert GeoJSON to and from MapML. The GeoJSON API can be added to any document as long as it is preceded by the mampl-viewer module, i.e.

<!doctype html>
<html lang="en">
    <head>
        <script type="module" src="mapml.js"></script>
        <script src="lib/geojson.js"></script>
    </head>
    <body>
        ...
    </body>
</html>    

GeoJSON To MapML

Function	Returns	Description
`geojson2mapml(<Object \| String> json, <Object>options)`	A MapML `<map-layer>` element.	Convert a GeoJSON feature or feature collection string or object to MapML `<map-layer>` containing one or more `<map-feature>` elements.

tip

Check out this application using the geojson2mapml API!

Parameters

Parameter	Description
<String	Object> json
<Object> options	A set of key/value pairs that customize the output MapML layer. All options are optional and described below.

Options

<Object> A set of key/value pairs that customize the output MapML layer. All options are optional and detailed below.

Option	Type	Default	Description
`label`	<String>	`json.name`, `json.title` or "Layer"	Sets the output layer's label.
`projection`	<String>	`OSMTILE`	Sets the output layer's projection. Defined values include: `OSMTILE`, `CBMTILE`, `WGS84`, and `APSTILE`.
`caption`	<String \| Function>	Uses the `label` value	A function that accepts the feature JSON and returns a string, OR a string that is the name of a property to be mapped to the featurecaption. If a matching property is not found, the string provided will be used as the feature caption value. See basic options usage for an example.
`properties`	<Function \| String \| HTMLElement>	Properties will be mapped to an HTML table.	Specifies how the properties are mapped. <Function> - A function that accepts one argument - the GeoJSON feature object - and which must return an HTMLElement that becomes the single child element of the <map-properties> element. <String> - A string that will be parsed and used as the single child element of the `<map-properties>` element for all features. <HTMLElement> - an element that will be used as the single child element of `<map-properties>` element for all features. See basic options usage for an example.
`geometryFunction`	<Function>	MapML geometry will mirror the GeoJSON geometry value	<Function> A function to modify the generated descendants of `<map-geometry>` which can add classes, hyperlinks and span's to the instance. Plain `<map-geometry>` element will be created by default. The function accepts two arguments: The generated child element of `<map-geometry>` and the feature json object to return a modified child element of the `<map-geometry>` element. See basic options usage for an example.

Examples

Basic options usage

Showcasing how use each option.

label
projection
caption
properties
geometryFunction

geojson2mapml label option
geojson2mapml(json, {label: "Downtown Ottawa"});

geojson2mapml projection option
geojson2mapml(json, {projection: "CBMTILE"});

geojson2mapml caption option - function-valued
// caption function
geojson2mapml(json, {caption: function(feature) {
    return feature.properties.desc + ", not a Polygon";
    }
});
// caption option string value referencing a property name
geojson2mapml(json, {caption: "desc"});

geojson2mapml properties option - function-valued
// properties function
geojson2mapml(json, {properties: function(feature) {
    let parser = new DOMParser();
    return parser.parseFromString("<h1>" + feature.properties.desc + "'s property</h1>", "text/html").body.firstChild;
    }
});
// properties option - string valued - make sure you sanitize user-supplied strings
geojson2mapml(json, {properties: "<p>This property was inserted using a properties string</p>"});

geojson2mapml geometryFunction option
let options = {
                geometryFunction: function (g, f) {
                  g.setAttribute("class", f.properties.class);
                  return g;}
              };
geojson2mapml(json, options);

Options string

An example showcasing how strings can be used to set label, projection, caption and properties options.

let json = {
    "name": "Default Name",
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [-75.6916809,45.4186964]
    },
    "properties": {"desc": "This is a Point"}
};

// GeoJSON To MapML
let output = geojson2mapml(json, {label: "Example 1", projection: "CBMTILE", caption: "desc", properties: "<h3>This is a property heading</h3>"});

Click to view the output HTMLElement

<map-layer label="Example 1" checked="">
   <map-meta name="projection" content="CBMTILE"></map-meta>
   <map-meta name="cs" content="gcrs"></map-meta>
   <map-feature>
      <map-featurecaption>This is a Point</map-featurecaption>
      <map-geometry>
         <map-point>
            <map-coordinates>-75.6916809 45.4186964</map-coordinates>
         </map-point>
      </map-geometry>
      <map-properties>
         <h3>This is a property heading</h3>
      </map-properties>
   </map-feature>
</map-layer>

Options function

An example showcasing how functions can be used to set caption and properties options.

let json = {
    "name": "Default Name",
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [-75.6916809,45.4186964]
    },
    "properties": {"desc": "This is a Point"}
};

// function to set caption
let cap = function c(j) {
  let str = "This point is located at: (" + j.geometry.coordinates[0] + ", " + j.geometry.coordinates[1] + ").";
  return str;
}

// function to set properties
let prop = function f(p) {
  let parser = new DOMParser();
  return parser.parseFromString("<h1>" + p.properties.desc + "'s property</h1>", "text/html").body.firstChild;
}

// GeoJSON To MapML
let output = geojson2mapml(json, {label: "Example 2", caption: cap, properties: prop});

Click to view the output HTMLElement

<map-layer label="Example 2" checked="">
   <map-meta name="projection" content="OSMTILE"></map-meta>
   <map-meta name="cs" content="gcrs"></map-meta>
   <map-feature>
      <map-featurecaption>This point is located at: (-75.6916809, 45.4186964).</map-featurecaption>
      <map-geometry>
         <map-point>
            <map-coordinates>-75.6916809 45.4186964</map-coordinates>
         </map-point>
      </map-geometry>
      <map-properties>
         <h1>This is a Point's property</h1>
      </map-properties>
   </map-feature>
</map-layer>

Default options

An example showcasing default output when no options are provided.

let json = {
 "title": "Point Geometry",
 "bbox": [-75.916809, 45.886964, -75.516809, 45.26964],
 "type": "FeatureCollection",
 "features": [{
     "type": "Feature",
     "geometry": {
         "type": "Point",
         "coordinates": [-75.6916809, 45.4186964]
     },
     "properties": {
         "prop0": "This is a Point"
     }
 }]
};

// GeoJSON To MapML
let output = geojson2mapml(json);

Click to view the output HTMLElement

<map-layer label="Point Geometry" checked="">
   <map-meta name="extent" content="top-left-longitude=-75.916809, top-left-latitude=45.886964, bottom-right-longitude=-75.516809,bottom-right-latitude=45.26964"></map-meta>
   <map-meta name="projection" content="OSMTILE"></map-meta>
   <map-meta name="cs" content="gcrs"></map-meta>
   <map-feature>
      <map-featurecaption>Point Geometry</map-featurecaption>
      <map-geometry>
         <map-point>
            <map-coordinates>-75.6916809 45.4186964</map-coordinates>
         </map-point>
      </map-geometry>
      <map-properties>
         <table>
            <thead>
               <tr>
                  <th role="columnheader" scope="col">Property name</th>
                  <th role="columnheader" scope="col">Property value</th>
               </tr>
            </thead>
            <tbody>
               <tr>
                  <th scope="row">prop0</th>
                  <td itemprop="prop0">This is a Point</td>
               </tr>
            </tbody>
         </table>
      </map-properties>
   </map-feature>
</map-layer>

MapML To GeoJSON

Function	Returns	Description
`mapml2geojson(<HTMLLayerElement> element, <Object> options)`	A JavaScript (GeoJSON) feature collection object	This function transforms the `<feature>` element children of a `<map-layer>` element to a GeoJSON FeatureCollection object. You supply options to control the transformation. This function must be used inside a windows.onload event.

caution

mapml2geojson must be called inside a windows.onload event to work properly. i.e.

window.onload = (event) => {
  mapml2geojson(json);
};

Parameters

Parameter	Description
<HTMLLayerElement> element	A `<map-layer>` element.
<Object> options	You supply parameters via an options object with predefined option names.

Options

<Object> A set of key/value pairs that customize the output GeoJSON object. All are optional and detailed below.

Option	Type	Default	Description
`propertyFunction`	<Function>	n/a	A function you supply that maps the features' `<map-properties>` element to a GeoJSON "properties" member, since only you know the markup design in your `<map-properties>` value. If you don't supply this option, a default function will attempt to reverse a `<table>` child of the `<map-properties>` element, as if that table was generated by the default properties option function from geojson2mapml.
`transform`	<Boolean>	`true`	Transform `<map-coordinates>` values to `gcrs` (longitude,latitude) values, if they are not already so. GeoJSON recommends using WGS 84 longitude,latitude coordinates, so this is the default behaviour.

Notes

mapml2geojson, by default, will transform coordinates to gcrs before serialization, if necessary. Note that all geographic CRS are not equivalent, and the interpretation of such coordinates is not guaranteed to conform to WGS 84 / GPS coordinates, and therefore may not conform to the GeoJSON recommendation, which requires longitude,latitude coordinates that are encoded as WGS 84. The projection engine used to implement this conversion is not capable of transforming coordinates from one ellipsoid to another, and so the resulting JSON SHOULD (somehow, tbd) be tagged with the datum in use by the projection of the layer.

Examples

Default options

An example showcasing default GeoJSON output when no options are provided.

<map-layer label="Point Geometry" checked="">
   <map-meta name="extent" content="top-left-longitude=-75.916809, top-left-latitude=45.886964, bottom-right-longitude=-75.516809,bottom-right-latitude=45.26964"></map-meta>
   <map-meta name="projection" content="OSMTILE"></map-meta>
   <map-meta name="cs" content="gcrs"></map-meta>
   <map-feature>
      <map-featurecaption>Point Geometry</map-featurecaption>
      <map-geometry>
         <map-point>
            <map-coordinates>-75.6916809 45.4186964</map-coordinates>
         </map-point>
      </map-geometry>
      <map-properties>
         <table>
            <thead>
               <tr>
                  <th role="columnheader" scope="col">Property name</th>
                  <th role="columnheader" scope="col">Property value</th>
               </tr>
            </thead>
            <tbody>
               <tr>
                  <th scope="row">prop0</th>
                  <td itemprop="prop0">This is a Point</td>
               </tr>
            </tbody>
         </table>
      </map-properties>
   </map-feature>
</map-layer>
<script>
window.onload = (event) => {
   let output = mapml2geojson(document.querySelector('map-layer'))
};
</script>

Click to view the output GeoJSON

{
 "title": "Point Geometry",
 "bbox": [-75.916809, 45.886964, -75.516809, 45.26964],
 "type": "FeatureCollection",
 "features": [{
     "type": "Feature",
     "geometry": {
         "type": "Point",
         "coordinates": [-75.6916809, 45.4186964]
     },
     "properties": {
         "prop0": "This is a Point"
     }
 }]
}

Introduction​

GeoJSON To MapML​

Parameters​

Options​

Examples​

Basic options usage​

Options string​

Options function​

Default options​

MapML To GeoJSON​

Parameters​

Options​

Notes​

Examples​

Default options​

Introduction

GeoJSON To MapML

Parameters

Options

Examples

Basic options usage

Options string

Options function

Default options

MapML To GeoJSON

Parameters

Options

Notes

Examples

Default options