jQuery tWism

A clickable SVG maps jQuery plugin

Why does this exist

Because sometimes, I just want to add a quick map to a project without making my life complicated.

How stable is it?

This is version: 0.4.5. Consider it at the release candidate stage, though I've used it in production. If you find any bugs, fork this repo and/or let me know!

Browser support?

Modern browsers down to IE9 is the goal.

It seems like this would work for any SVG

Well, it works for any SVG that has IDs on the clickable regions. I made it for rolling out quick maps, though. You should probably use D3.js or Raphael if you want a robust, tested library for manipulating vector graphics.

Quick Instructions

Include jQuery and the jQuery twism plugin:

<script src="http://code.jquery.com/jquery.js"></script>
<script src="jquery.twism.js"></script>

Create a container:

<div id="worldmap"></div>

Initialize the plugin on said container:

$('#worldmap').twism();

Complete Documentation

Usage

selector.twism([method], [options], [callback]);

Methods:

• create (default) - create a map
• destroy - remove a map
• setCountry - change one country's options

For instance:

$('#worldmap').twism("destroy");

To edit an individual country:

$('#worldmap').twism("setCountry", {
  name: 'us',
  color: 'rgba(255,0,0,1)' //any CSS color should work
}, function() {
  alert('Color changed to red.')
})

The create and setCountry commands take options and all take a callback.

An example with a method, option, and callback:

$('#worldmap').twism("create", {
	map: "world",
	border: "red",
    individualCountrySettings: [{
        name: "cn",
    	color: "red"
	}, {
		name: "fr",
		color: "blue"
	}, {
		name: "us",
		color: "white"
	}]
}, function() {
	alert("Callback!");
});

Options

Pick a map (options: usa, world, or custom; default is world)

map: "world"

If you do a custom map type, provide a URL

customMap: 'maps/Blank_US_Map.svg'

Include Antarctica on the world map? (default: false)

antarctica: true

U.S. Territories?

territories: true

Map labels (usa only)?

labels: true

Map label attributes (usa only)

labelAttributes: { color:  'white', font:  'Helvetica',fontSize: '15', backgroundColor: 'blue'}

P.R.C. Territories? (i.e., treat Taiwan, HK, and Macao as one China, default: true)

littleRedBook: false,

Set a default background color of countries (default: #A9DA8A, can be used with setCountry)

color: "#A9DA8A"

Set the default color for the country borders (default: white, can be used with setCountry)

border: "white"

Set the border width (default: 2, can be used with setCountry):

borderWidth: 2

Set the background color (default: "#4af")

backgroundColor: "white"

Set a hover color (default: #BB0029, can be used with setCountry)

hoverColor: "#BB0029"

Set the hover border (default: "yellow", can be used with setCountry)

hoverBorder: "yellow"

Set the height (leaving it blank tries to get the parent div height):

height: 300px

Set the width (leaving it blank tries to get the parent div width):

width: 500px

Set a click event function (default alerts with the country code, if you put an argument on the function, it'll return the ID attribute of the region, can be used with setCountry)

click: function(country) {
	alert(country);
}

Disable any regions (array of ID attributes or 2-digit country/state codes in the default world/USA maps)

dispableCountries: ["cn","ca","nz"]

Hide any regions (array of ID attributes or 2-digit country/state codes in the default world/USA maps)

hideCountries: ["cn","ca","nz"]

Change the colors for one or more map regions:

individualCountrySettings: [
	{
		name: "us",
		color: "white",
		border: "green"
		borderWidth: 5
	},
	{
		name: "fr",
		color: "blue",
		border: "orange"
		borderWidth: 10
	},
]