Installation

Reminder:

This project uses Leafletjs, and as a result all the docuemnted Leaflet methods, properties and event listeners are also usable here.

Warning:

This project uses Wikimedia's jQuery.i18n plugin for localization, for this and other reasons, you're going to need to serve your project locally.

Installing Map.ir Web SDK is quite simple and straightforward.

CSS:

Add the following stylesheets to your document's head tag:

If you're planning to create a multi-lingual Single Page App (SPA), then you'll need to make a few modifications:

Tips:

  • All the CSS variables are kept inside vars.css. You can use this file to customize colors and sizes.
  • app.css contains the rest of the styles that Map.ir Web SDK requires.

Javascript:

Similarly, add the scripts below to the bottom of your html document, before closeing the body tag:

Tips:

  • Map.ir Web SDK is jQuery 3.2+ dependant.
  • jquery.env.js contains a javascript object of configurations and endpoints that the SDK requires to perform correctly. There, you can also define new modes for your app to run. However, It's recommended that you leave this file alone if you're not exactly sure what you're doing there.
  • All the shapes and marker styles are defined in s.map.styles.js. You can change them to customize polygons, polylines and markers if you don't wish to use the default styles.
  • s.map.js is the SDK core.

Getting started

Basic map:

Creating a basic map is pretty easy. You begin with calling the Map.ir Web SDK jQuery plugin:


var map = $.sMap({
	element: '#map',
	presets: {
		latlng: {
			lat: 35.70,
			lng: 51.47,
		},
		zoom: 6,
	},
});
										

The plugin returns a map object you can use later in your app.

Tips:

  • The element property holds the CSS selector of the element you'd like to append the map into. You should set the width and height of this element using CSS.
  • The presets property contains the geolocation of your map's center point and your desired zoom level onces it's done loading.

But that is not all. One more little step and our basic map will be all set:


$.sMap.layers.static.build({
	layers: {
		base: {
			default: {
				server: 'https://map.ir/shiveh',
				layers: 'Shiveh:ShivehGSLD256',
				format: 'image/png',
			},
		},
	},
});
										

What just happened?

First we created a map view, then set a static base layer for our map to show.
Don't panic just yet, we'll learn more about this as we move on.

Stand-alone Demo

Calling modules:

Creating a map view was easy, but how about enabling a few extra features?

Guess what these codes do:


$.sMap.logo.implement();
$.sMap.zoomControl.implement();
$.sMap.fullscreen.implement();
$.sMap.userLocation.implement();
										

The code is pretty self-explanatory, but here are a few free hints:

Tips:

  • logo, zoomControl, fullscreen and userLocation are the sub-modules you can call if you have the required privillages and have their files added to your document beforehand too.
  • The implement method is a common way to tell sub-modules to append their DOM elements to your map view.
  • Sub-modules might come with their own options, like the static layers sub-module we called earlier. (more on that in the future)
Stand-alone Demo

SPA vs. custom layouts

Technically, you can both create an SPA with Map.ir Web SDK, or create a layout and append a map to one of the elements, but while most sub-modules can be used in both cases, for some of them it only makes sense to be enabled if you're developing a Single Page App.

Take dynamicUrl for instance:


$.sMap.dynamicUrl({
	marker: true,
});
										

warning:

dynamicUrl uses the pushState method of HTML5 history object to update browser's address bar every time users move the map or zoom in/out.
Enabling this feature on a map that is put in a news website, for example, might cause unwanted results. Imagine an article's url changing every time user moves the map!

Creating a single page map and implementing a map view into an element in a layout are generally the same, with a few exceptions.

Single Page Apps:

A quick example:

Don't forget to set height and width of your map:


html, body {
	width: 100vw;
	height: 100vh;
	overflow: hidden;
	margin: 0;
	padding: 0;
	font-size: 10px;
}

#map {
	width: 100vw;
	height: 100vh;
}
										

And finally, call the SDK and sub-modules of your choosing:


var map = $.sMap({
	element: '#map',
	presets: {
		latlng: {
			lat: 32,
			lng: 52,
		},
		zoom: 6,
	},
});

$.sMap.layers.static.build({
	layers: {
		base: {
			default: {
				server: 'https://map.ir/shiveh',
				layers: 'Shiveh:ShivehGSLD256',
				format: 'image/png',
			},
		},
	},
});

$.sMap.logo.implement();

$.sMap.fullscreen.implement();

$.sMap.zoomControl.implement();

$.sMap.userLocation.implement();

$.sMap.dynamicLocation.implement(
	format: 'latlng',
	source: 'mouse',
});
										
Stand-alone Demo

Custom layouts:

You can create a layout and insert a map view into an element:

CSS:


html, body {
	width: 100vw;
	height: 100vh;
	overflow: hidden;
	margin: 0;
	padding: 0;
	font-size: 10px;
}

@media only screen and (min-width: 840px) {
	html, body {
		font-size: 10px;
	}
}

.custom-main{
	float: left;
	width: calc(100% - 220px);
	height: 100vh;
}

#map {
	width: 100%;
	height: 100%;
}

.custom-aside{
	font-family: IRANSans;
	display: flex;
	flex-direction: column;
	float: right;
	width: 220px;
	height: 100vh;
	box-shadow: var(--box-shadow-lg);
}

@media only screen and (min-width: 840px) {
	.custom-main{
		width: calc(100% - 320px);
	}

	.custom-aside{
		width: 320px;
	}
}

.custom-aside .custom-header {
	font-size: 1.8rem;
	color: var(--color-lighter);
	text-align: center;
	background-color: var(--color-primary);
	padding: 0 2rem;
	line-height: 5rem;
	box-shadow: var(--box-shadow-down);
}

.custom-aside .custom-section {
	padding: 1rem;
	flex-grow: 2;
	overflow: auto;
}

.custom-aside .custom-footer {
	font-size: 1.2rem;
	color: var(--color-dark);
	text-align: center;
	background-color: var(--color-light);
	padding: 0 2rem;
	line-height: 4rem;
	box-shadow: var(--box-shadow-up);
}

.custom-aside .custom-footer a {
	text-decoration: none;
	color: var(--color-primary);
}
										

Finally, come the module calls:


var map = $.sMap({
	element: '#map',
	presets: {
		latlng: {
			lat: 35.70,
			lng: 51.47,
		},
		zoom: 6,
	},
});

$.sMap.layers.static.build({
	layers: {
		base: {
			default: {
				server: 'https://map.ir/shiveh',
				layers: 'Shiveh:ShivehNOPOI',
				format: 'image/png',
			},
		},
	},
});

$.sMap.logo.implement();

$.sMap.zoomControl.implement();

$.sMap.userLocation.implement();
										
Stand-alone Demo

Adding Features

Adding a marker:

After creating a map, you can create a marker like this:


$.sMap.features();

$.sMap.features.marker.create({
	name: 'test-marker',
	popup: {
		title: {
			html: 'Title',
			i18n: '',
		},
		description: {
			html: 'Description',
			i18n: '',
		},
	},
	latlng: {
		lat: 37.4,
		lng: 49.7,
	},
	popupOpen: true,
});
										
Stand-alone Demo

Adding a polyline:

After creating a map, you can create a polyline like this:


$.sMap.features();

$.sMap.features.polyline.create({
	name: 'test-polyline',
	popup: {
		title: {
			html: 'Title',
			i18n: '',
		},
		description: {
			html: 'Description',
			i18n: '',
		},
	},
	coordinates: [
		[30, 50],
		[40, 57],
	],
	popupOpen: true,
});
										
Stand-alone Demo

Adding a polygon:

After creating a map, you can create a polygon like this:


$.sMap.features();

$.sMap.features.polygon.create({
	name: 'test-polygon',
	popup: {
		title: {
			html: 'Title',
			i18n: '',
		},
		description: {
			html: 'Description',
			i18n: '',
		},
	},
	coordinates: [
		[35, 55],
		[35, 45],
		[30, 55],
	],
	popupOpen: true,
});
										
Stand-alone Demo

Off you go!

Now, that we can call a warm up to get your engines started.
Why don't you roll up your sleeves and jump into the API Documentation and figure out your way for yourself?
You're a big lad, we have faith in you!