#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 recommended. Register here to obtain an OpenWeatherMap API key for your application.

See demo. The demo is a work in progress, so please mind the 'minimalistic' design/layout at this stage, and visit it often to check on improvements :).

The current version of this plugin is 1.5.4.

#Instructions

##Installation of Required Dependencies Before installing, make sure you have also installed the following required dependencies: JQuery, ~~jsonproxy, and URIjs~~. You can do so via Bower, NPM, or plain old download.

For version 1.5.0+, jsonproxy was removed as it was constantly down. This was used to handle Cross Origin Resource Sharing (CORS) requests especially for HTTPS sites. Another more stable solution will be built in at a later date. For the time being, https://proxy.hackeryou.com is the proxy being used in this plugin. If you would like to know more about CORS, visit https://www.w3.org/TR/cors/.

###Using Bower

bower install jquery --save

###Using Node Package Manager (NPM)

npm install jquery --save

##Installation of Plugin

###Using Bower

You can install this package by executing the following in your shell:

bower install open-weather-updated

The above will install the latest package version.

The package will install in 'bower_components' directory, unless specified by your .bowerrc file.

If installing the script via Bower, include the script, along with JQuery, URIjs, and jsonproxy like so:

<script src="bower_components/jquery/dist/jquery.min.js"></script>
<script src="bower_components/URIjs/src/URI.min.js"></script>
<script src="bower_components/jsonproxy/jsonp.js"></script>
<script src="bower_components/open-weather-updated/build/openWeather.min.js"></script>

###Using Node Package Manager (NPM)

If you prefer to install your packages/plugins using NPM, you can do so with the following command:

npm install open-weather-updated

By default, this will install the plugin in your 'node_modules' directory, unless specified differently.

You can include the plugin like so:

<script src="node_modules/jquery/dist/jquery.min.js"></script>
<script src="node_modules/URIjs/src/URI.min.js"></script>
<script src="node_modules/jsonproxy/jsonp.js"></script>
<script src="node_modules/open-weather-updated/build/openWeather.min.js"></script>

###Install Manually

Download and extract this repository to the root of your web application.

For example, if I was to take this approach,I would download this repository to a 'js/libraries' folder.

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

<script src="js/libraries/jquery/dist/jquery.min.js"></script>
<script src="js/libraries/URIjs/src/URI.min.js"></script>
<script src="js/libraries/jsonproxy/jsonp.js"></script>
<script src="js/libraries/open-weather-updated/build/openWeather.min.js"></script>

###Basic Use

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: 'Dunedin,NZ'
});

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:

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.

##Custom Background Images

If you enable this feature, your web page's background image will be set to one appropriate to the current weather condition.

For example, if it was a rainy day, the image 'images/weather/backgrounds/day/rain.png' will be set as the main page background.

For this to work, you will need to define a directory structure in the root of your website's file-system for 'day' and 'night' background images. An example is: 'images/weather/backgrounds/day', 'images/weather/backgrounds/night'.

The 'customBackgroundImages' attribute in the example (at the bottom of the README.md) must be set like so:

$('.weather-temperature').openWeather({
	city: 'Dunedin,NZ',
	customBackgroundImages: 'path/to/weather/background/images/folder/'

});

For example, if I stored the day/night backgrounds in the 'images/weather/backgrounds' folder, this will be set to:

$('.weather-temperature').openWeather({
	city: 'Dunedin,NZ',
	customBackgroundImages: 'images/weather/backgrounds/'

});

In each 'day' and night' folders described above, custom background images must be named as follows:

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

####Options

#####key: integer

#####lang: string

#####city: "city name, country / province/ state"

#####lat: integer

#####lng: integer

#####placeTarget: "id / class / element"

#####units: "metric / imperial / standard"

#####shortDescriptionTarget: "id / class / element"

#####descriptionTarget: "id / class / element"

#####minTemperatureTarget: "id / class / element"

#####maxTemperatureTarget: "id / class / element"

#####windSpeedTarget: "id / class / element"

#####windSpeedUnit: "Kph / Mph / mps"

#####windDirectionUnit: "degrees / compass"

#####clickConvertWindDirection: "true / false"

#####clickConvertTemperature: "true / false"

#####clickConvertWindSpeed: "true / false"

#####humidityTarget: "id / class / element"

#####sunriseTarget: "id / class / element"

#####sunsetTarget: "id / class / element"

#####iconTarget: "id / class / element"

#####customIcons: "path"

#####timeLastUpdatedTarget: "id /class / element"

#####success: function() {}

#####error: function() {}

####Example:

$('.weather-temperature').openWeather({
    key: 'YOUR-OPENWEATHERMAP-API-KEY',
    units: 'metric',
    lang: 'en',
    city: 'Dunedin,Otago,NZ',
    placeTarget: '.weather-place',
    shortDescriptionTarget: '.short-weather-description',
    descriptionTarget: '.weather-description',
    minTemperatureTarget: '.weather-min-temperature',
    maxTemperatureTarget: '.weather-max-temperature',
    windSpeedTarget: '.weather-wind-speed',
    windSpeedUnit: 'Kph',
    windDirectionUnit: 'compass',
    clickConvertWindSpeed: true,
    clickConvertTemperature: true,
    clickConvertWindDirection: true,
    windDirectionTarget: '.weather-wind-direction',
    humidityTarget: '.weather-humidity',
    sunriseTarget: '.weather-sunrise',
    sunsetTarget: '.weather-sunset',
    iconTarget: '.weather-icon',
    customIcons: '/img/icons/weather/',
    customBackgroundImages: 'images/weather/backgrounds/',
    lat: coords.latitude != null ? coords.latitude : null,
    lng: coords.longitude != null ? coords.longitude : null,
    timeLastUpdatedTarget: '.weather-time-last-updated',
    success: function() {

        $('.weather-wrapper').show();
        $('.short-weather-description').hide();

        var forecast = $('.weather-description').text();
        $('.weather-description').text(forecast.charAt(0).toUpperCase() + forecast.slice(1).toLowerCase());

    },
    error: function(message) {
        console.log(message);
    }
});