Description

Imgslider is a jQuery plugin that simplifies the animation of images when hovered. Ideal for featured posts, banner ads, popular products, etc.

Features

Please Note: There are several key areas within the Live Preview where I'm running HTML encryption. Rest assured, the full version that you receive has no encryption.

Change Log

10/19/2010 - Added support for jQuery Easing Plugin. Instructions can be found below.

Plugin Options

Option Default Value Description
top 0px Slide image downwards
right 0px Slide image to the right
bottom 0px slide image upwards
left 0px slide image to the left
duration 200 How long to run the animation (in milliseconds)
easeIn false Beginning animation effect (easeOutBounce, easeOutElastic, etc.) - Easing options
easeOut false Ending animation effect (easeOutBounce, easeOutElastic, etc.) - Easing options

Negative values can also be used. For example, giving "top" a value of -100px will slide the image upwards.

How to Use

Please view the "example.html" file for a demonstration. Please see below for instructions on how to use the easing options.

These instructions will guide you through the process of adding the plugin to a new HTML page. This plugin can easily be added to any dynamically generated content or existing website. The exact method for implementing this code may vary depending on your usage.

Getting Started

Below is the bare minimum needed in order to get things running. Detailed instructions follow below.

			<!-- Include required JS files -->
			<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
			<script type="text/javascript" src="jquery.imgslide.js"></script>
			<script type="text/javascript">
			$(function(){
				<!-- assign imgslide to an image -->
				$('#id-name').imgslide();
			});
			</script>

1. Create HTML File

Open up your favorite text editor (notepad++, Coda, Dreamweaver, etc.) and create a new HTML file. Add the following code:

			<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
			<html xmlns="http://www.w3.org/1999/xhtml">
			<head>
				<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
				<title></title>
			</head>
			<body>
			</body>
			</html>

2. Add HTML Code

Let's add the necessary HTML for our images. Add the following code between the two body tags.

			<div id="wrapper">
				<div id="demo1"><a href="#"><img src="http://envato.dagrander.com/img/imgslide/banner-ad.png" alt="" /></a></div>
			</div>

3. Style with CSS

Next we need to add a bit of CSS to style the HTML. Paste the following code into a separate file and name it "style.css". Save the file in the same folder as the HTML file you created above.

			#wrapper div {
				position:relative;
				overflow:hidden;
				}
			div img {
				position:absolute;
				}
			/* Demo 1 */
			#demo1 {
				width:296px;
				height:130px;
				border:1px solid #999;
				}

The jQuery animation from the plugin uses CSS absolute positioning. Therefore, we need to ensure that "position:relative" is applied to the images containing element. In this case, it's a regular div tag. We also need to apply "position:absolute" to the image itself.

We then set the width and height of the images containing div since only a portion of each image is viewable when the page loads. Adding "overflow:hidden" hides any part of the image that exceeds the width and height. This essentially creates a window in which we can slide in the hidden areas of the image, creating the desired animated effect.

The remaining CSS in the "example.html" file is purely for aesthetics and isn't required to use the plugin.

4. Link to CSS

Now that we have our CSS file, we need to link to it from within the HTML file. Paste the following code between the two head tags.

			<link href="style.css" rel="stylesheet" type="text/css" media="screen" />

5. Adding the JavaScript

The JavaScript files must be added in order for the plugin to work. Copy the "jquery.imgslide.js" file to the same folder as the HTML file. Place the following code in the HTML file between the two head tags.

			<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
			<script type="text/javascript" src="jquery.imgslide.js"></script>
			<script type="text/javascript">
				$(function(){
					$('#demo1 img').imgslide({
						top: '-130px'
					});
				});
			</script>

Notice that I've linked to the jQuery library file through Google's CDN. You can read more about this here - http://code.google.com/apis/ajaxlibs/.

If you remember from the HTML content added earlier, the image tag was given a CSS ID selector of "#demo1". This will be used to assign the plugin.

To animate the image, we use the following code:

			$('#demo1').imgslide({
				top: '-130px'
			});

This will slide the image upwards 130px.

6.Easing Options

The jQuery Easing Plugin provides a list of useful easing effects which can be applied to our ImgSlider plugin. A few additional steps are needed, so let's get started.

After following steps 1 - 5 above, we need to download the latest version of the plugin from the author's website. Place the file in the same directory as the "jquery.imgslide.js" file. The default file name as of this writing is "jquery.easing.1.3.js".

Next, we need to add a link to the "jquery.easing.1.3.js" file within our HTML file. Be sure to add it between the two existing script tags.

			<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
			<script type="text/javascript" src="jquery.easing.1.3.js"></script>
			<script type="text/javascript" src="jquery.imgslide.js"></script>

The last step is to pass in the easing options to the ImgSlide plugin. Find the following code in your HTML file:

			$('#demo1').imgslide({
				top: '-130px'
			});

and replace it with:

			$('#demo1').imgslide({
				top: '-130px',
				easeIn: 'easeOutBounce',
				easeOut: 'easeOutBounce'
			});

(Notice there are commas after the first two options)

That's it! The easeIn option allows you to define an easing effect for the beginning animation (on mouseover). Conversly, the easeOut option allows you to define an easing effect for the ending animation (on mouseout). The easing options can either be at the beginning or end of an animation. For example, "easeInBounce" will happen just before the image slides, whereas "easeOutBounce" happens just after the slide has completed. Please refer to "Demo 5" in "example.html" for a visual example.

EaseIn and easeOut options can be used independently from each other. For example, if you would only like an animation at the end, we can simply use this (omitting the easeIn option):

			$('#demo1').imgslide({
				top: '-130px',
				easeOut: 'easeOutBounce'
			});

7. Enjoy!

That's it! You've now successfully used the plugin. For more examples, please refer to "example.html".

If it's just not working for you, please see below for a list of common problems. And don't forget to look at the source code of the examples.

8. Troubleshooting

Please check to make sure you've done the following:

  1. Ensure you have linked to both the jQuery library and plugin files, and that the paths are correct.
  2. Calling the plugin must be placed within the Document Ready function. More information can be found here - jQuery Document Ready
  3. Check that there are no missing or extra characters (commas, semicolons, etc) within your JavaScript.
  4. Make sure you've linked to the CSS file and that you have the necessary CSS explained above.
  5. When calling a class, be sure to use $('.class-name').imgslide();
  6. When calling an id, use $('#id-name').imgslide();

You may also wish to use Firebug to debug your code. It's an excellent addon for Firefox that I highly recommend. More information can be obtained here - http://getfirebug.com/

If you are still having problems, please contact me through the Envato Marketplace. My username is dagrander.