Registering an API key
Before you can use the plugin, WeatherSlider requires a World Weather Online API key. You can get it for free and it only takes
a couple of seconds. Please click on the following URL and register for your own API key: http://developer.worldweatheronline.com/signup.aspx.
World Weather Online, the weather data provider that we’re working with, has changed its terms of service and will suspend free API signups. As of April 5th, WWO will no longer issue free API keys, thus new customers can only use this plugin with a premium subscription (which has a 60 day trial period). Current users with already registered API keys will not be affected, the plugin will continue to work as before. We’re currently looking into this situation and try to find a way to offer a solution without additional costs.
Thank you for your understanding.
Keep your API key close once you've received the registration email. Later in this guide we will use it to set up sliders.
Including resource files
To get started you need to copy the necessary resource files to your assets folder and include them to your pages. You can use the following example, you need to insert these lines in the <head> section of your site.
Considering performance, you can put the script tags at the footer of your pages before the closing </body> tag.
<!-- WeatherSlider styles -->
<link rel="stylesheet" href="../weatherslider/css/weatherslider.css" type="text/css">
<!-- jQuery with jQuery Easing JS & background-position animation plugin -->
<script src="../weatherslider/jQuery/jquery.js" type="text/javascript"></script>
<script src="../weatherslider/jQuery/jquery-easing.js" type="text/javascript"></script>
<script src="../weatherslider/jQuery/jquery-animate-background-position.js" type="text/javascript"></script>
<!-- You will need the following line ONLY if you are using GEOLOCATION -->
<script src="https://maps.googleapis.com/maps/api/js?sensor=false&language=en" type="text/javascript"></script>
<!-- WeatherSlider from Kreatura Media -->
<script src="../weatherslider/js/weatherslider.kreaturamedia.jquery.js" type="text/javascript"></script>
Including resources
Make sure to enter the corrent path for these files depending on the location of the weatherslider folder on your server.
jQuery is an external library. Make sure to not insert a duplicate version, as your site is likely use one already.
Creating the slider element
Next, you have to define an element for the slider within the <body> section of a page. The example code below won't do much, it's just a containment element, and it will be filled with its contents later in this guide.
The initial size of the slider is defined in the style attribute. You can change those values between 240x200 and 1300x600 pixels to specify your preferred dimensions as well as enter your own CSS code for custom styling. Also, notice the id attribute. We will use its value (weatherslider) as a reference throughout this guide.
<div id="weatherslider" style="width: 600px; height: 300px;">
<!-- The locations of your slider will be here -->
</div>
Adding a slider on a page
To add locations you only need to create span tags with class name ws-location in a container element. The number of span tags is not limited, but you have to add at least one.
<div id="weatherslider">
<span class="ws-location">New York, US</span>
<span class="ws-location">Olenegorsk, Russia</span>
<span class="ws-location">Sydney, Australia</span>
<span class="ws-location">Kinshasa, Kongo</span>
<span class="ws-location">Rome, Italy</span>
<span class="ws-location">Zurich, Switzerland</span>
</div>
Example slider markup
Using the Geolocation feature
The Geolocation feature enables your visitors to see weather information for their own location. Just add the special location name GEOLOCATION to your slider, the plugin will handle the rest for you.
<div id="weatherslider">
<span class="ws-location">GEOLOCATION</span>
<span class="ws-location">Sydney, Australia</span>
<span class="ws-location">Rome, Italy</span>
</div>
Example of using the Geolocation feature
Custom Location Names
The location name in the examples so far is used by the plugin to both find the right place and display its name in the widget. However, you can provide a custom location name to be displayed if it's necessary by adding the title attribute to the span tags. In the example below WeatherSlider will get the weather conditions of New York but it will display My Location as location name.
<div id="weatherslider">
<span title="My Location" class="ws-location">New York, US</span>
</div>
Specifying a custom location name
Slider setup
You should initialize the slider plugin by calling the weatherSlider() method on the target element. Since we used the ID weatherslider in our previous samples, we get that by jQuery and initialize WeatherSlider on that element. See the following example:
<script type="text/javascript">
// Running the code when the document is ready
$(document).ready(function(){
// Calling WeatherSlider on the target element with adding custom slider options
$('#weatherslider').weatherSlider({
WWOAPIKey: 'your_api_key',
premiumAPIKey: false,
imgPath: '../weatherslider/img/'
// Other options goes here. Please make sure that you didn't forget
// to add a comma to the line endings except the last line!
});
});
</script>
Initializing the plugin
This code is usually placed after the closing </body> tag, but the most important thing is that it must be placed after the included resource script files.
Remove the <script> wrapper element if you will use this code in an external JavaScript file.
Setting up your API key
Notice the options we used in the above example. These are the required settings for the plugin to work. You must enter your own API key by replacing the "your_api_key" placeholder in the WWOAPIKey option. Also, set the premiumAPIKey option to true if it's a key for WWO's premium service.
List of the available slider options
| Required properties |
Values |
Defaults |
Description |
| WWOAPIKey |
'your_api_key' |
N/A |
Enter your API key by signing up for WWO's free service on https://developer.worldweatheronline.com/auth/register. |
| WWOAPIVersion |
<num> |
1 |
Free API keys registered before November 2014 and all Premium API keys require setting the API version to be 1. Free API keys registered after November 2014 require setting the API version to 2. |
| premiumAPIKey |
true or false |
true |
Set this option to false if you have an old Free API key. |
| useHTTPS |
true or false |
true |
Enables secure connections on HTTPS sites. |
| imgPath |
'your_path' |
'../weatherslider/img/' |
Path to WeatherSlider's images folder. Note, that you must use the slash at the end of the path. |
| Weather & Time settings |
Values |
Defaults |
Description |
| measurement |
'metric' or 'imperial ' |
'metric' |
Your preferred unit of the measurement. |
| timeFormat |
12 or 24 |
12 |
You can switch between 12 and 24 hour time format. |
| daytime |
[number, number] |
[7,19] |
The script tries automatically determine day/night cycles. If fails, it will revert back to the specified hours you can specify separating with a comma. |
| windyWeather |
<num> |
18 |
WeatherSlider will use a special animation if the current wind speed goes beyond than the one you've specified in kmph. |
| icyTemp |
<num> |
-2 |
WeatherSlider will show an icy layer in the widget if the current temperature is lower than the value you've specified in Celsius. |
| SlideShow |
Values |
Defaults |
Description |
| slideDelay |
<num> |
0 |
Enter a value greater than zero to enable automatic location switching in the widget. This value is in milliseconds, so the value 5000 means that WeatherSlider will wait 5 seconds before swapping to the next location in the slider. |
| refreshInterval |
<num> |
0 |
Enter a value greater than zero to enable periodically updating the weather informations in the widget. This value is in milliseconds, so the value 300 000 will update the weather info in every 5 minutes. |
| keybNav |
true or false |
true |
You can navigate through your locations in the widget by using the left and right arrow keys on your keyboard. |
| touchNav |
true or false |
true |
Enables the swipe gesture on mobile devices to navigate between locations in the widget. |
| Appearance |
Values |
Defaults |
Description |
| hideBackground |
true or false |
false |
You can show / hide the background of the widget. |
| enableSearchField |
true or false |
true |
With enabled search field your users can enter their own locations. |
| alwaysShowSearch |
true or false |
false |
By enabling this option the search field will always be visible. |
| enableWeatherInfo |
true or false |
true |
Shows / hides the weather information box. |
| enableForecast |
true or false |
true |
Shows / hides the 3 days forecast when you hover over the information box. |
| alwaysShowForecast |
true or false |
false |
By enabling this option the forecast information will always be visible. |
| CSSanimations |
true or false |
true |
Using CSS3 animations can drastically improve performance in modern web browsers, especially on mobile devices. |
| JSanimations |
true or false |
true |
By disabling this and the CSS3 animations the plugin won't animate snow, rain, wind and lightnings. |
| infoDuration |
<num> |
450 |
The animation duration when the information box appears. This value in milliseconds, so the value 1000 means one second. |
| infoEasingType |
['easingin','easingout'] |
['easeOutBack','easeInBack'] |
The preferred animation easings of the infobox. See examples. |
| reduction |
<num> or 'auto' |
'auto' |
The script automatically scales everything (graphic elements, font sizes, etc) depending on the width and height of the container. Use 'auto' or override it with a number between 0 and 1. |
| Contents of the information box |
Values |
Defaults |
Description |
| showLoc |
true or false |
true |
Shows / hides the current location. |
| showTime |
true or false |
true |
Shows / hides the current time. |
| showCond |
true or false |
true |
Shows / hides the current weather conditions. |
| showTemp |
true or false |
true |
Shows / hides the current temperature. |
| showLow |
true or false |
true |
Shows / hides low temperature. |
| showHigh |
true or false |
true |
Shows / hides high temperature. |
| showHum |
true or false |
true |
Shows / hides humidity. |
| showPrec |
true or false |
true |
Shows / hides precipitation. |
| showWind |
true or false |
true |
Shows / hides wind. |
| showPress |
true or false |
true |
Shows / hides pressure. |
| showVis |
true or false |
true |
Shows / hides visibility. |
| showFDay |
true or false |
true |
Shows / hides the name of the day in the forecast. |
| showFCond |
true or false |
true |
Shows / hides weather conditions in the forecast. |
| showFLow |
true or false |
true |
Shows / hides low temperature in the forecast. |
| showFHigh |
true or false |
true |
Shows / hides high temperature in the forecast. |
| Animation settings |
Values |
Defaults |
Description |
| snow |
true or false |
true |
Enables / disables the snowing animation. |
| rain |
true or false |
true |
Enables / disables the raining animation. |
| wind |
true or false |
true |
Enables / disables the "Windy weather" animation. |
| lightnings |
true or false |
true |
Enables / disables the lightning animation. |
| windDirection |
'left'
'right'
'auto' |
'auto' |
You can set the direction of the background animation for windy weather. |
Language support
You can find all the editable texts in the uncompressed weatherslider.kreaturamedia.jquery.js file (which also included in the package) in the array named $.weatherSlider.language. You can edit the UI texts and all the weather condition names too.
Working example
We've bundled a working example of WeatherSlider, you can find it in the example folder within the downloaded package. However, please note that we can't provide you a valid API key, so you must open and edit the example.html file in order to make this example work. Once you've managed to make the necessary changes you can open it by clicking here.
You can also see a working example of WeatherSlider by visiting our demo site at https://kreaturamedia.com/weatherslider-premium-jquery-weather-widget/.
Is my location supported?
You can test your location and weather data on WorldWeatherOnline's website.
WeatherSlider keeps saying "getting weather"
Please, make sure about the following things:
- You are using the most-recent version of the plugin
- You get your own API key for the new WWO API
- Your API key is valid and works without problems. You can test it on WWO's developer page.
- Check your account standing by logging in on WWO's developer page.
- You entered your API key properly, without any whitespaces or extra characters.
Multiple widgets on the same page does not work
This is a limitation in the World Weather Online API, it doesn't allow parallel requests at the same time. Caching may help improving cases related to this limitation, but only WWO's premium API solves the problem entirely.
I have exceeded my API usage limit. What should I do?
We are planning to include a simple PHP file in a future update that can help you caching your API results, so your widgets can load faster and decrease the API usage.
I'm receiving security notifications on my HTTPS site
Since version 2.6.2 you can use the "useHTTPS" key in the plugin options, so WeatherSlider will retrieve the weather information over a secure connection. Please read the Slider setup -> List of slider options page for more information about using plugin options.
If you get stuck...
Before contacting us, please make sure that you:
If you didn't find answer to your problem, please ask your question on the item discussion page or send us a private message from our Codecanyon profile page (Search for the "Email kreatura" box on the bottom right - in this case we will reply via email). We can answer your support questions only in these ways (please do not send us email directly).
IMPORTANT! For the fast troubleshooting, please send us detailed informations about the issue and make sure that you don't forget to send us your site url where you are using / want to use the item. Please note, that we cannot troubleshoot from screencast videos or screenshots.
Please take some time until we respond (usually in 24 - 48 hours).
Useful pages