jqvmap

repository·master·Indexed 23 days ago

A jQuery-based vector map plugin for data visualization, version 1.5.1. It allows for map customization, region styling, and the use of pins to mark geographic areas. The library includes a Python-based CLI tool (jqvmap.py) for creating custom maps from Shapefiles using GDAL/OGR, Shapely, and Booleano.

Tokens: 5.1K
Snippets: 3
Records: 19
Agent score: 80%

What's inside jqvmap

Use pins to mark regions
master
Pins can be placed on regions using the pins and pinMode options.
- pinMode: 'content' (Default): The pins object contains stringified HTML (e.g., <img src="..." />).
- pinMode: 'id': The pins object contains the id attribute of existing HTML DOM elements. Note that when using 'id', the elements are transferred (moved) from their original position to the map, not copied.
Note: Pins are placed at the center of the bounding rectangle of the country, which may not always land directly on the country shape (e.g., the US pin may land in the ocean between the mainland and Alaska).
https://github.com/10bestdesign/jqvmap/blob/master/README.md
Install required Python packages
master
Once Python and GDAL binaries are installed, install the necessary Python dependencies using pip and easy_install:
```
sudo easy_install GDAL
pip install shapely
pip install booleano
```
https://github.com/10bestdesign/jqvmap/blob/master/create/README.md
Create a custom JQVMap using a JSON configuration
master
1. Prepare Source Data: Download a Shapefile (e.g., from Natural Earth or GADM) and place the unzipped directory into the ./create/source folder.
2. Identify Fields: Find the column names for the ISO Code (e.g., iso_a3) and the English Name (e.g., name_long) within your Shapefile's data (often found in .dbf, .csv, or .xml files). These will be used for code_field and name_field.
3. Create Config: Create a JSON file in ./create/config defining the read_data and write_data steps.
4. Run Generator: Execute the jqvmap.py script pointing to your config file.
Output files will be generated in the ./create/output folder.
```
[
  {
    "name": "read_data",
    "file_name": "./source/some-folder/some-file.shp"
  },
  {
    "name": "write_data",
    "format": "jqvmap",
    "file_name": "./output/jquery.vmap.my-map.js",
    "params": {
      "code_field": "iso_column",
      "name_field": "name_column",
      "name": "my-map"
    }
  }
]
```
https://github.com/10bestdesign/jqvmap/blob/master/create/README.md

Install and initialize JQVMap

master

To use JQVMap, include the JQVMap CSS and JavaScript files from the ./dist folder, along with jQuery and the specific map JavaScript file you wish to load (e.g., jquery.vmap.world.js).

Initialize the map by calling .vectorMap({ map: 'map_name' }) on a target container element. The map parameter must match the name of the loaded map file (e.g., world_en, usa_en, europe_en, or germany_en).

<html
  <head>
    <title>JQVMap - World Map</title>
    <link href="../dist/jqvmap.css" media="screen" rel="stylesheet" type="text/css">

    <script type="text/javascript" src="http://code.jquery.com/jquery-1.11.3.min.js"></script>
    <script type="text/javascript" src="../dist/jquery.vmap.js"></script>
    <script type="text/javascript" src="../dist/maps/jquery.vmap.world.js" charset="utf-8"></script>

    <script type="text/javascript">
    jQuery(document).ready(function() {
      jQuery('#vmap').vectorMap({ map: 'world_en' });
    });
    </script>
  </head>
  <body
    <div id="vmap" style="width: 600px; height: 400px;"></div
  </body
</html>

Requirements for creating custom JQVMaps
master
To create custom maps, you must be comfortable using a Terminal and Python. The following software and packages are required:
1. Python (v2.7+)
2. GDAL/OGR Binaries (OS specific)
3. GDAL (Python package)
4. Shapely (Python package)
5. Booleano (Python package)
https://github.com/10bestdesign/jqvmap/blob/master/create/README.md
Update map settings dynamically
master
Most configuration options (except callbacks) can be updated after the map has been initialized using the .vectorMap('set', 'optionName', value) syntax.
To add or manage callbacks after initialization, use standard jQuery .bind() methods with the specific JQVMap event names.
https://github.com/10bestdesign/jqvmap/blob/master/README.md
Set up the environment for complex maps
master
To prevent issues when creating complex maps, you must set the OGR_ENABLE_PARTIAL_REPROJECTION environment variable to TRUE.
Run this in your terminal session:
```
export OGR_ENABLE_PARTIAL_REPROJECTION=TRUE
```
To make this permanent, add the line to your shell profile (e.g., .bash_profile, .profile, or .zshrc) and then run source <your_profile_file>.
https://github.com/10bestdesign/jqvmap/blob/master/create/README.md
Install GDAL/OGR binaries
master
Install the GDAL/OGR binaries based on your operating system:
macOS: Download and install the GDAL 1.11 Complete DMG package. Alternatively, if using Homebrew:
```
brew update
brew install gdal
```
Windows: Use the Maptools MS4W installer to obtain the necessary binaries.
https://github.com/10bestdesign/jqvmap/blob/master/create/README.md
Configure JQVMap settings
master
You can customize the appearance and behavior of the map by passing an options object to .vectorMap().
Key configuration options include:
- map: The map to load (e.g., 'world_en').
- backgroundColor: CSS compatible background color.
- borderColor, borderOpacity, borderWidth: Styling for region outlines.
- color: Default color for map regions.
- colors: An object where keys are ISO 3166-1 alpha-2 country codes (lowercase) and values are colors.
- enableZoom: Boolean to enable/disable zoom (defaults to true).
- hoverColor, hoverOpacity: Styling for regions when hovered.
- scaleColors: An array of hex colors used for data visualization scaling.
- selectedColor, selectedRegions: Styling and pre-selection for regions.
- showTooltip, showLabels: Boolean to toggle tooltips or ISO labels.
- pins: An object mapping country codes to pin content.
- pinMode: Determines if pins contains HTML strings ('content') or DOM element IDs ('id').
```
jQuery('#vmap').vectorMap(
{
    map: 'world_en',
    backgroundColor: '#a5bfdd',
    borderColor: '#818181',
    borderOpacity: 0.25,
    borderWidth: 1,
    color: '#f4f3f0',
    enableZoom: true,
    hoverColor: '#c9dfaf',
    hoverOpacity: null,
    normalizeFunction: 'linear',
    scaleColors: ['#b6d6ff', '#005ace'],
    selectedColor: '#c9dfaf',
    selectedRegions: null,
    showTooltip: true,
    onRegionClick: function(element, code, region)
    {
        var message = 'You clicked "'
            + region
            + '" which has the code: ' 
            + code.toUpperCase();

        alert(message);
    }
});
```
https://github.com/10bestdesign/jqvmap/blob/master/README.md

Call JQVMap functions

master

You can trigger specific map actions using the .vectorMap('functionName', ...args) syntax.

Function	Description
`zoomIn`	Zooms the map in one step.
`zoomOut`	Zooms the map out one step.
`getPinId(cc)`	Returns the `id` attribute of the pin on country code `cc`.
`getPin(cc)`	Returns the stringified HTML of the pin on country code `cc`.
`getPins()`	Returns an associative JSON string of all pins.
`removePin(cc)`	Removes the pin from country code `cc`.
`removePins()`	Removes all pins from the map.

Handle JQVMap callbacks and events
master
JQVMap provides several callback hooks that can be defined during initialization or bound later via jQuery.
Initialization Callbacks
- onLoad(event, map): Called when the map is loading.
- onLabelShow(event, label, code): Called before a label is shown. You can call event.preventDefault() to hide it.
- onRegionOver(event, code, region): Called when the mouse enters a region.
- onRegionOut(event, code, region): Called when the mouse leaves a region.
- onRegionClick(event, code, region): Called when a region is clicked. Use $(event.currentTarget).data('mapObject').isMoving to check if the click was interrupted by a map drag.
- onRegionSelect(event, code, region): Called when a region is selected.
- onRegionDeselect(event, code, region): Called when a region is deselected.
- onResize(event, width, height): Called when the map is resized.
jQuery Event Binding
You can also bind to these events using standard jQuery .on() or .bind() with these names:
- load.jqvmap
- labelShow.jqvmap
- regionMouseOver.jqvmap
- regionMouseOut.jqvmap
- regionClick.jqvmap
- resize.jqvmap
- drag (Standard jQuery event)
- zoomIn (Standard jQuery event)
- zoomOut (Standard jQuery event)
https://github.com/10bestdesign/jqvmap/blob/master/README.md

Region codes for RUSSIA scope

master

The following codes are used for the RUSSIA map scope:

Code	Region
CH	Chukotka Autonomous Okrug
KA	Kamchatka Krai
MA	Magadan Oblast
SA	Sakha Republic
AM	Amur Oblast
PR	Primorsky Krai
EU	Jewish Autonomous Oblast
HA	Khabarovsk Krai
SH	Sakhalin Oblast
OM	Omsk Oblast
NV	Novosibirsk Oblast
AL	Altai Krai
LT	Altai Republic
TV	Tuva Republic
HK	Republic of Khakassia
KM	Kemerovo Oblast
TM	Tomsk Oblast
ZB	Zabaykalsky Krai
BR	Buryat Republic
IR	Irkutsk Oblast
KR	Krasnoyarsk Krai
YA	Yamalo-Nenets Autonomous Okrug
HT	Khanty–Mansi Autonomous Okrug
TU	Tyumen Oblast
KU	Kurgan Oblast
CL	Chelyabinsk Oblast
SV	Sverdlovsk Oblast
AR	Arkhangelsk Oblast
NE	Nenets Autonomous Okrug
KO	Komi Republic
MU	Murmansk Oblast
VO	Vologda Oblast
NO	Novgorod Oblast
PS	Pskov Oblast
LE	Leningrad Oblast
KL	Republic of Karelia
KN	Kaliningrad Oblast
DA	Republic of Dagestan
ST	Stavropol Krai
SO	Republic of North Ossetia–Alania
KB	Kabardino-Balkar Republic
KH	Karachay–Cherkess Republic
CC	Chechen Republic
IN	Republic of Ingushetia
AD	Republic of Adygea
KS	Krasnodar Krai
RO	Rostov Oblast
KK	Republic of Kalmykia
AS	Astrakhan Oblast
VL	Volgograd Oblast
TR	Tver Oblast
SM	Smolensk Oblast
BN	Bryansk Oblast
KY	Kursk Oblast
BL	Belgorod Oblast
OR	Oryol Oblast
KJ	Kaluga Oblast
TL	Tula Oblast
LP	Lipetsk Oblast
MC	Moscow Oblast
RZ	Ryazan Oblast
TB	Tambov Oblast
VM	Vladimir Oblast
IV	Ivanovo Oblast
YR	Yaroslavl Oblast
KT	Kostroma Oblast
NN	Nizhny Novgorod Oblast
MR	Republic of Mordovia
PZ	Penza Oblast
SR	Saratov Oblast
SS	Samara Oblast
OB	Orenburg Oblast
BS	Republic of Bashkortostan
UL	Ulyanovsk Oblast
CU	Chuvash Republic
TA	Republic of Tatarstan
ML	Mari El Republic
UD	Udmurt Republic
KI	Kirov Oblast
PE	Perm Krai
VN	Voronezh Oblast

jqvmap

What's inside jqvmap

Initialization Callbacks

jQuery Event Binding