#### Thank you

Thank you for purchasing this product. If you have any questions that are beyond the scope of this documentation, please feel free to email us.

#### About the item

WeatherSlider is a gorgeous weather widget that you can easily add to your site. It supports multiple units of measurement, time and date formats, geolocation and custom location search for your visitors. It’s device friendly by supporting responsive mode, touch gestures on mobile devices, and CSS3 transitions for optimal performance. It has tons of options to entirely customize the appearance and behavior of your weather widgets at the smallest detail.

#### Features

- 48 different weather types with a powerful weather API
- Showing current weather and 3 day weather forecast (mouse over the weather info box)
- Beautiful CSS3 animations with jQuery fallback
- Responsive size from 240×200 to 1300×600 pixels (content, images and font size also auto resizing!)
- Multiple (unlimited) locations in one slider
- Multiple (unlimited) sliders on your site with unique settings!
- Custom Location Search Bar (users can type their custom location)
- Auto-Slideshow and Auto-Refresh features (optional)
- Geolocation feature
- 12 or 24 hour time format
- Touch Control for mobile devices (tested under iOS)
- Keyboard navigation (optional)
- Language support
- Supports all major browsers
- Detailed documentation
- Layered graphic elements included in .PSD format
- Free support and free future updates

#### Compatibility

- Requires at least jQuery 1.7. Working with 1.10.x or 2.x versions. Please note that jQuery 2.x is no more compatible with IE7 and 8.
- Compatible with Chrome, Firefox, Safari, IE7+, Opera and mobile browsers

#### Important! (flickering issue)

If you are experiencing flickering issues with jQuery 1.x during the transitions please use jQuery 1.11.1 or newer.

In old browsers some animations (for example fading the transparent PNGs) are missing, but the plugin is fully functional.

#### Third party credits

We are extremely grateful for the people working on the projects below. These guys are making our lives much easier, thus we can focus on building high quality products.

Project | Homepage | Comment
--- | --- | ---
jQuery | jquery.com | The most popular JavaScript library for building complex web apps.
World Weather Online | worldweatheronline.com | Global weather forecast and weather API provider
Google Maps API | developers.google.com | Free maps API from Google

#### 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.

#### Changes in version 2.6.7

- Added example PHP file for server-side caching. See instructions in file `/extras/weatherslider-cache-extension.php`, which is part of the ZIP file you can download from CodeCanyon.

#### Changes in version 2.6.6

- Fixed some issues with WWO Premium API
- Changed the following default settings:
  - PremiumAPI: true
  - WWOAPIVersion: 1
  - useHTTPS: true

#### Changes in version 2.6.4

- Fixed some issues with WWO API Version 2

#### Changes in version 2.6.3

- Reporting WWO API error messages
- Added WWOAPIVersion option to set the API version

If you've registered a FREE API key before November 2014, you may need to set the new `WWOAPIVersion` option to be `1` after the update. This change should not affect premium API users.

#### Changes in version 2.6.2

- Added HTTPS / SSL support

#### Changes in version 2.6.0

- Added support for Premium World Weather Online APIs
- Redesigned documentation with clearer language

#### Changes in previous versions

2.5.0

- A new Geolocation feature as MaxMind discontinued to support their free Javascript API

2.4.0

- Support for the new World Weather Online API
  IMPORTANT: if you are upgrading from previous versions of WeatherSlider, the plugin will need a new World Weather Online API key due to some changes in WWO API.
  You can register for a new API key here: https://developer.worldweatheronline.com/auth/register

2.3.0

- Imrpovement: Improved CSS overrides to prevent the theme applying global CSS style settings on the slider and its elements
- Bug fix: fixed an issue in IE9-10 and Opera that caused the animations to stop in a certain point

2.2

- Added feature: option to show always the weather forecast
- Added feature: option to show always the custom location search box
- Improvement: added jQuery 1.9 compatibility (the plugin needs now jQuery 1.7+)
- Fixed: 12 hour time format
- Fixed: infobox positioning issue
- Fixed: animations under Opera

2.1

- Added feature: option to display custom location name
- Added feature: option to hide the widget background
- Improvement: you can now remove your custom location by erasing the search field

2.0

- Updated, reliable geolocation feature (powered by MaxMind)
- Multi-language support
- Custom Location Search Bar (users can type their custom location)
- Auto-Slideshow and Auto-Refresh features (optional)
- Added a lot of customization options (forecast or weather informations can be switched off)
- Added support for 12 hour time format
- More intelligent weather information box sizing
- Fixed 'one location touch' bug
- Fixed degree symbol

1.2

- added touch control for mobile devices
- added geolocation feature
- daytime bugfix
- switched-off animation bugfixes

1.0

- first release

#### If you get stuck...

Before contacting us, please make sure that you:

- read this documentation carefully
- and browsed the FAQ of the item.

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

site | you can find here...
--- | ---
The website of the item | demo sliders and examples
Codecanyon item page | the latest version of the plugin
Codecanyon discussion | an item discussion topic where you can ask your questions if you get stuck
FAQ of the item | a detailed FAQ with answers for the most commonly asked questions and reported issues