imclab / open-weather

A simple, lightweight jQuery plugin used to display the current weather of any city using the free OpenWeatherMap API.

#Open Weather

A simple, lightweight jQuery plugin used to display the current weather of any city using the free OpenWeatherMap API.

This plugin allows you to display the location, the current temperature, the current low temperature, the current high temperature, a description of the current weather, a weather icon, the humidity level, the wind speed, the time the sun will rise, and the time the sun will set.

An API key is not required but it is reccomended. Register here to obtain an OpenWeatherMap API key for your application.

See demo

##Instructions

Include jQuery and the plugin in the head or footer of your page.

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
    
<script src="/js/plugins/openWeather.js"></script>

The only default output is the current temperature.

To display the current temperature, create an element on your page where the current temperature will be displayed.

<div class="weather-temperature"></div>

Initialize the plugin targeting the class, ID or element that you've created with either the 'city' option or 'lat' and 'lng' options set.

$('.weather-temperature').openWeather({
	city: 'Toronto,ON'
});

OR

$('.weather-temperature').openWeather({
	lat: 30,
	lng: 25
});

##Custom Icons

The OpenWeatherMap API returns their own set of icons, however, if you don't want to use them, the plugin also allows you to use 6 custom icons for both day and night, so 12 in total. Custom icons must be named as follows:

<p>clear.png</p>

<p>clouds.png</p>

<p>rain.png</p>

<p>snow.png</p>

<p>storm.png</p>

<p>mist.png</p>

To use custom icons create a directory where the icons will live and inside of that directory create two more directories, "day" and "night."

/img/icons/weather/day/
/img/icons/weather/night/

Place your custom icons inside the "day" and "night" directories and initialize the plugin using the customIcons option.

$('.weather-temperature').openWeather({
	city: 'Toronto,ON',
	customIcons: '/img/icons/weather/'
});

* Note that if you are using custom icons you must include all 12 images.

####Options

key: integer
A string that defines the OpenWeatherMap API key for your application (default: null).

lang: string
A string that defines the language (default: 'en').
(English - en, Russian - ru, Italian - it, Spanish - sp, Ukrainian - ua, German - de, Portuguese - pt, Romanian - ro, Polish - pl, Finnish - fi, Dutch - nl, French - fr, Bulgarian - bg, Swedish - se, Chinese Traditional - zh_tw, Chinese Simplified - zh_cn, Turkish - tr)

city: "city name, country / province/ state"
A string that defines the city (default: null).

lat: integer
An integer that defines the latitude (default: null).

lng: integer
An integer that defines the longitude (default: null).

placeTarget: "id / class / element"
A string that defines the ID, class or element that will contain the location name (default: null).

units: "c / f"
A string that defines the type of units (default: 'c').

descriptionTarget: "id / class / element"
A string that defines the ID, class or element that will contain the weather description (default: null).

minTemperatureTarget: "id / class / element"
A string that defines the ID, class or element that will contain the minimum temperature (default: null).

maxTemperatureTarget: "id / class / element"
A string that defines the ID, class or element that will contain the maximum temperature (default: null).

windSpeedTarget: "id / class / element"
A string that defines the ID, class or element that will contain the wind speed (default: null).

humidityTarget: "id / class / element"
A string that defines the ID, class or element that will contain the humidity (default: null).

sunriseTarget: "id / class / element"
A string that defines the ID, class or element that will contain the time of sunrise (default: null).

sunsetTarget: "id / class / element"
A string that defines the ID, class or element that will contain the time of sunset (default: null).

iconTarget: "id / class / element"
A string that defines the ID, class or element that will contain the icon image (default: null).

customIcons: "path"
A string that defines the path to the custom icons (default: null).

success: function() {}
A function that runs after the plugin has successfully retrieved weather data. (default: function()).

error: function() {}
A function that runs if there was an error retrieving weather data. (default: function(message)).

#####Example:

$(function() {

	$('.weather-temperature').openWeather({
		lang: 'ru',
		city: 'Toronto, ON',
		placeTarget: '.weather-place',
		units: 'f',
		descriptionTarget: '.weather-description',
		minTemperatureTarget: '.weather-min-temperature',
		maxTemperatureTarget: '.weather-max-temperature',
		windSpeedTarget: '.weather-wind-speed',
		humidityTarget: '.weather-humidity',
		sunriseTarget: '.weather-sunrise',
		sunsetTarget: '.weather-sunset',
		iconTarget: '.weather-icon',
		customIcons: '/img/icons/weather/',
		success: function() {
			$('.weather-temperature').show();
		},
		error: function(message) {
			console.log(message);
		}
	});
	
});