Mapper.js

mapper.js is a JQuery UI plugin that easily draws and styles geographical areas on Google Maps.

It has built-in support for mapping South African geographical areas, but can easily be adapted to others.

Mapper.js

To use mapper.js, you need to include the following scripts in your page:

JQuery, JQueryUI & Google Maps Scripts

<script src="//code.jquery.com/jquery-2.0.3.min.js" type="text/javascript"></script>
<script src="//code.jquery.com/ui/1.10.3/jquery-ui.js" type="text/javascript"></script>
<script src="https://maps.googleapis.com/maps/api/js?sensor=false"></script>

Mapper.js

You will need to download mapper.js and include it in your website, such as:

<script src="mapper.js" type="text/javascript"></script>

Then simply use JQuery to create a widget on a div element:

// html
<div id="map"></div>
// javascript (once page has loaded)
$("#map").mapper({
    // options...
});

The div will be rendered by Google via the plugin as a map, and the plugin will add the appropriate geographical areas (polygons).

mapper.js requires a few other files to be in the same directory: provinces.js, districts.js, municipalities.js and the wards files: wards.js, wards-ec.js, wards-fs.js, wards-gt.js, wards-kzn.js, wards-lp.js, wards-mp.js, wards-nc.js, wards-nw.js and, wards-wc.js. These files contain the boundary data required by mapper.js to draw the shapes on Google Maps. The wards have been split into 9 files, one for each province, to reduce the file size further.

Note that these files contain data for South African boundaries. The data has been simplified to reduce the size of the files.

Examples

Several examples of the mapper.js plugin are shown below.

Example 1

Simplest usage

Draw all the provinces using the most basic settings.

$("#map1").mapper({
    drawAll: true,
    dataType: "provinces"
});

Example 2

Selected geographical areas

Draw specific provinces using the default style settings.

$("#map2").mapper({
    dataType: "provinces",
    data: [
        { id: "Limpopo" },
        { id: "Gauteng" }
    ]
});

Note that the map will automatically zoom to the bounds of the selected geographical areas.

Example 3

Override default styles

Draw certain provinces, overriding the default styles.

$("#map3").mapper({
    dataType: "provinces",
    data: [
        { id: "Western Cape" },
        { id: "Eastern Cape" },
        { id: "Gauteng" }
    ],
    fillColor: "blue",
    fillOpacity: 0.85,
    strokeColor: "red",
    strokeWidth: 5,
    strokeOpacity: 1
});

Example 4

Custom styles for each geographical area

Draw provinces with their own customized styles.

$("#map4").mapper({
    dataType: "provinces",
    data: [
        { id: "Western Cape", fillColor: "#0000ff", strokeColor: "#ffffff" },
        { id: "Eastern Cape", fillColor: "#00ff00", strokeColor: "#ffff00" },
        { id: "Northern Cape", fillColor: "#0099ff", strokeColor: "#555555" },
        { id: "North West", fillColor: "#ff00ff", strokeColor: "#ff0000" },
        { id: "Mpumalanga", fillColor: "cyan", strokeColor: "#ffff00" },
        { id: "Limpopo", fillColor: "#000000", strokeColor: "#0077ff" },
        { id: "Gauteng", fillColor: "gold", strokeColor: "black" },
        { id: "Free State", fillColor: "orange", strokeColor: "purple" },
        { id: "KwaZulu-Natal", fillColor: "darkgreen", strokeColor: "pink" }
    ]
});

Example 5

Districts

Draw districts in the Western Cape.

$("#map5").mapper({
    dataType: "districts",
    data: [
        { id: "CPT", fillColor: "#0099ff", strokeColor: "#555555" },
        { id: "DC1", fillColor: "#000000", strokeColor: "#0077ff" },
        { id: "DC2", fillColor: "#0000ff", strokeColor: "#ffffff" },
        { id: "DC3", fillColor: "cyan", strokeColor: "#ffff00" },
        { id: "DC4", fillColor: "#ff00ff", strokeColor: "#ff0000" },
        { id: "DC5", fillColor: "darkgreen", strokeColor: "#ffff00" }
    ]
});

Example 6

Municipalities

Draw municipalities in the West Coast DM.

$("#map6").mapper({
    dataType: "municipalities",
    data: [
        { id: "WC011", fillColor: "#0099ff", strokeColor: "#555555" },
        { id: "WC012", fillColor: "#000000", strokeColor: "#0077ff" },
        { id: "WC013", fillColor: "#0000ff", strokeColor: "#ffffff" },
        { id: "WC014", fillColor: "darkgreen", strokeColor: "#ffff00" },
        { id: "WC015", fillColor: "#ff00ff", strokeColor: "#ff0000" }
    ]
});

Example 7

Wards

Draw wards in the City of Cape Town.

$("#map7").mapper({
    dataType: "wards",
    data: [
        { id: "19100001", fillColor: "red" }, { id: "19100002", fillColor: "blue" }, { id: "19100003", fillColor: "green" }, { id: "19100004", fillColor: "yellow" }, { id: "19100005", fillColor: "brown" }, { id: "19100006", fillColor: "gold" }, { id: "19100007", fillColor: "purple" }, { id: "19100008", fillColor: "cyan" }, { id: "19100009", fillColor: "coral" }, { id: "19100010", fillColor: "aqua" }, { id: "19100011", fillColor: "black" }, { id: "19100012", fillColor: "crimson" }, { id: "19100013", fillColor: "gray" }, { id: "19100014", fillColor: "khaki" }, { id: "19100015", fillColor: "magenta" },
        { id: "19100016" }, { id: "19100017" }, { id: "19100018" }, { id: "19100019" }, { id: "19100020" }, { id: "19100021" }, { id: "19100022" }, { id: "19100023" }, { id: "19100024" }, { id: "19100025" }, { id: "19100026" },
        { id: "19100027" }, { id: "19100028" }, { id: "19100029" }, { id: "19100030" }, { id: "19100031" }, { id: "19100032" }, { id: "19100033" }, { id: "19100034" }, { id: "19100035" }, { id: "19100036" }, { id: "19100037" },
        { id: "19100038" }, { id: "19100039" }, { id: "19100040" }, { id: "19100041" }, { id: "19100042" }, { id: "19100043" }, { id: "19100044" }, { id: "19100045" }, { id: "19100046" }, { id: "19100047" }, { id: "19100048" },
        { id: "19100049" }, { id: "19100050" }, { id: "19100051" }, { id: "19100052" }, { id: "19100053" }, { id: "19100054" }, { id: "19100055" }, { id: "19100056" }, { id: "19100057" }, { id: "19100058" }, { id: "19100059" },
        { id: "19100060" }, { id: "19100061" }, { id: "19100062" }, { id: "19100063" }, { id: "19100064" }, { id: "19100065" }, { id: "19100066" }, { id: "19100067" }, { id: "19100068" }, { id: "19100069" }, { id: "19100070" },
        { id: "19100071" }, { id: "19100072" }, { id: "19100073" }, { id: "19100074" }, { id: "19100075" }, { id: "19100076" }, { id: "19100077" }, { id: "19100078" }, { id: "19100079" }, { id: "19100080" }, { id: "19100081" },
        { id: "19100082" }, { id: "19100083" }, { id: "19100084" }, { id: "19100085" }, { id: "19100086" }, { id: "19100087" }, { id: "19100088" }, { id: "19100089" }, { id: "19100090" }, { id: "19100091" }, { id: "19100092" },
        { id: "19100093" }, { id: "19100094" }, { id: "19100095" }, { id: "19100096" }, { id: "19100097" }, { id: "19100098" }, { id: "19100099" }, { id: "19100100" }, { id: "19100101" }, { id: "19100102" }, { id: "19100103" },
        { id: "19100104" }, { id: "19100105" }, { id: "19100106" }, { id: "19100107" }, { id: "19100108" }, { id: "19100109" }, { id: "19100110" }, { id: "19100111" }
    ],
    province: "Western Cape"
});

Note that the province option was supplied in the example above. This allows mapper.js to only download the wards for that province, which reduces the size of the data file required. If all wards are required on the map, omit the province option and supply the option allowAllWards: true.

Example 8

HTML popups on clicking a geographical area

Add a popup info window on the click event of a geographical area.

$("#map8").mapper({
    dataType: "provinces",
    data: [
        { id: "Western Cape", fillColor: "#0000ff" },
        { id: "Eastern Cape", fillColor: "#00ff00", html: "<strong>Eastern Cape</strong><br>You clicked on me!" },
        { id: "Northern Cape", fillColor: "#0099ff", html: "<strong>Northern Cape</strong><br>You clicked on me!" },
        { id: "North West", fillColor: "#ff00ff", html: "<strong>North West</strong><br>You clicked on me!" },
        { id: "Mpumalanga", fillColor: "cyan", html: "<strong>Mpumalanga</strong><br>You clicked on me!" },
        { id: "Limpopo", fillColor: "#000000", html: "<strong>Limpopo</strong><br>You clicked on me!" },
        { id: "Gauteng", fillColor: "gold", html: "<strong>Gauteng</strong><br>You clicked on me!" },
        { id: "Free State", fillColor: "orange", html: "<strong>Free State</strong><br>You clicked on me!" },
        { id: "KwaZulu-Natal", fillColor: "darkgreen", html: "<strong>KwaZulu-Natal</strong><br>You clicked on me!" }
    ]
});

Example 9

Add a click event handler

Add a click event handler to the geographical areas.

$("#map9").mapper({
    dataType: "provinces",
    data: [
        { id: "Western Cape", fillColor: "#0000ff" },
        { id: "Eastern Cape", fillColor: "#00ff00" },
        { id: "Northern Cape", fillColor: "#0099ff" },
        { id: "North West", fillColor: "#ff00ff" },
        { id: "Mpumalanga", fillColor: "cyan" },
        { id: "Limpopo", fillColor: "#000000" },
        { id: "Gauteng", fillColor: "gold" },
        { id: "Free State", fillColor: "orange" },
        { id: "KwaZulu-Natal", fillColor: "darkgreen" }
    ],
    click: function (event) {
        alert("I was clicked!\n"
            + "I am: " + this.id + "\n"
            + "I am one of the: " + this.dataType + "\n"
            + "The time of the clicking was: " + (new Date()).toString());
    }
});

Note that you have access to the clicked polygon in the click event via the this keyword. The polygon also has the id and dataType option attached to it.

Licensing

Please refer to the Github repository for licensing information, at www.github.com/capesean/mapper.

Contact

Please contact me on Twitter at @capesean