bgStretcher (Background Stretcher) is a jQuery plugin for stretching one or more images proportionally across an entire page or element. When multiple images are supplied, bgStretcher displays them in a configurable slideshow with advanced options. The plugin allows you to add a large image (or a set of images) to the background of your web page and will proportionally resize the image(s) to fill the entire window area.
The plugin will work as a slideshow if multiple images are used. The speed, duration, transition effects, and slide direction are configurable. Available transition options include none, simpleSlide, superSlide and fade. Sequence mode can be set to normal, backwards, or random. Additionally, the resizing of the images can be optionally animated when the container is resized. Class names may also be passed to bgStretcher to define Next & Previous buttons and a pagination element.
bgStretcher plugin is developed by w3Blender.com. Support is available via comments at CodeCanyon.
Past versions of bgStretcher were formerly released on ajaxBlender.com. All downloads and support are now available at CodeCanyon.
|
|
It takes very little time to get started with bgStretcher; simply follow the four steps below. For more information about any of these steps, read the sections that follow.
To add bgStretcher to a page:
<script type="text/javascript" src="js/jquery-1.11.0.min.js"></script> <script type="text/javascript" src="js/jquery-bgstretcher-3.3.0.min.js"></script> <link rel="stylesheet" href="css/bgstretcher.css" />
<script type="text/javascript">
jQuery(function($){
$("body").bgStretcher({
images: ["images/sample-1.jpg", "images/sample-2.jpg"],
imageWidth: 1024,
imageHeight: 768
});
});
</script><script type="text/javascript" src="js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="js/jquery-bgstretcher-3.3.0.min.js"></script>
<link rel="stylesheet" href="css/bgstretcher.css" />
All together:
<head> ... <script type="text/javascript" src="js/jquery-1.11.0.min.js"></script> <script type="text/javascript" src="js/jquery-bgstretcher-3.3.0.min.js"></script> <link rel="stylesheet" href="css/bgstretcher.css" /> ... </head>
bgStretcher is capable of stretching an image vertically and horizontally across the background of an entire page, or across the background of a specific block element. To ensure the image doesn't distort, it is stretched proportionally until the shortest dimension (height or width) reaches the edge of its container. If the image does not have the same aspect ratio as its container, the image may be cut off along the longer portion.
To use the image stretching capability, follow the installation instructions above, and then insert the following script anywhere in your page, after the installation lines. The "images" property must be an array and contain one or more paths to images. Use the same values you would use for the "src" attribute of an image tag. The "imageWidth" and "imageHeight" properties should be set to the pixel (px) width and height of the image you are supplying; they are used to calculate the aspect ratio of the image. If the dimensions are not supplied, they default to 1024 and 768, respectively.
<script type="text/javascript">
jQuery(function($){
$("body").bgStretcher({
images: ["images/sample-1.jpg"],
imageWidth: 1024,
imageHeight: 768
});
});
</script>
Demo: Simple Mode
In addition to stretching an image across the background of an entire page, bgStretcher can also stretch images across the backgrounds of other page elements. You may also change the "anchoring" of the image and the image container.
When bgStretcher runs, it creates a list of images inside of a container element that is then placed on the page. You may set the ID attribute of the container using the "continaerId" option:
<script type="text/javascript">
jQuery(function($){
$("body").bgStretcher({
images: ["images/sample-1.jpg"],
imageWidth: 1024,
imageHeight: 768,
containerId: "bgStretcher"
});
});
</script>
The above code will stretch an image across the background of the whole page. You can also make bgStretcher work on other page elements. Simply select the element with jQuery and call bgStretcher like you would when adding it to the <body> tag. For example, this code will initialize bgStretcher on a <div> with the class "example":
<script type="text/javascript">
jQuery(function($){
$("div.example").bgStretcher({
images: ["images/sample-1.jpg"],
imageWidth: 1024,
imageHeight: 768
});
});
</script>
Demo: Inside of a DIV Element
Background images can be anchored horizontally and vertically relative to their container element. The default value for the "anchoring" option is "left top".
<script type="text/javascript">
jQuery(function($){
$("body").bgStretcher({
images: ["images/sample-1.jpg"],
imageWidth: 1024,
imageHeight: 768,
anchoring: "right bottom"
});
});
</script>
Using the "maxWidth" and "maxHeight" options, you can limit the width and/or height of the stretched images. These options set the height and width of the container element, and the images are stretched to fit.
<script type="text/javascript">
jQuery(function($){
$("body").bgStretcher({
images: ["images/sample-1.jpg"],
imageWidth: 1024,
imageHeight: 768,
maxWidth: 500,
maxHeight: 500
});
});
</script>
bgStretcher will resize images proportionally by default. This means that images will not distort when they are resized because they maintain their aspect ratio. You may turn proportional resizing off by setting the "resizeProportionally" option to false.
<script type="text/javascript">
jQuery(function($){
$("body").bgStretcher({
images: ["images/sample-1.jpg"],
imageWidth: 1024,
imageHeight: 768,
resizeProportionally: false
});
});
</script>
Demo: Non-Proportional Resize
bgStretcher also offers the option of animating images when the container is resized (such as when the window is resized by the user). The option is off by default, and can be enabled by setting "resizeAnimate" to true. Please note that this may slow down your users PC if your images are very large.
<script type="text/javascript">
jQuery(function($){
$("body").bgStretcher({
images: ["images/sample-1.jpg"],
imageWidth: 1024,
imageHeight: 768,
resizeAnimate: true
});
});
</script>
bgStretcher can also work as a slideshow! Simply supply multiple images and bgStretcher will turn them into a stunning slideshow for the background of your web page.
Use bgStretcher the same way you would when stretching just one image, but supply a list of images instead. This will automatically initiate bgStretcher in slideshow mode.
<script type="text/javascript">
jQuery(function($){
$("body").bgStretcher({
images: ["images/sample-1.jpg", "images/sample-2.jpg", "images/sample-3.jpg"],
imageWidth: 1024,
imageHeight: 768
});
});
</script>
Demo: Simple Slideshow
You may also optionally disable the slideshow functionality by setting the "slideShow" option to false.
<script type="text/javascript">
jQuery(function($){
$("body").bgStretcher({
images: ["images/sample-1.jpg", "images/sample-2.jpg", "images/sample-3.jpg"],
imageWidth: 1024,
imageHeight: 768,
slideShow: false
});
});
</script>
The slideshow functionality of bgStretcher has many options and effects. You may adjust the timing of the slideshow, specify one of multiple transition effects, sequence modes, and directions, and assign navigation butttons and a pagination element for user naviation.
bgStretcher provides three types of transition effects, or can be set to use no transition effect. The three effects are "simpleSlide", "superSlide", and "fade". Simply set the "transitionEffect" option to your preferred transition effect type. The default transition effect is "simpleSlide"
<script type="text/javascript">
jQuery(function($){
$("body").bgStretcher({
images: ["images/sample-1.jpg", "images/sample-2.jpg", "images/sample-3.jpg"],
imageWidth: 1024,
imageHeight: 768,
transitionEffect: "superSlide"
});
});
</script>
Demos: simpleSlide superSlide fade
You may add next and previous buttons, as well as a pagination element, to bgStretcher by adding the elements to your page and specifying their IDs when initializing bgStretcher. By default, the "buttonNext", "buttonPrev", and the "pagination" options are set to empty strings ("").
To set the next and previous buttons, use the following code. Please note that you must include the # symbol before the element's ID for this to work correctly.
<script type="text/javascript">
jQuery(function($){
$("body").bgStretcher({
images: ["images/sample-1.jpg", "images/sample-2.jpg", "images/sample-3.jpg"],
imageWidth: 1024,
imageHeight: 768,
buttonNext: "#next-button",
buttonPrev: "#previous-button"
});
});
</script>
To add pagination to bgStretcher, specify the ID of the element you wish the pagination to appear in. bgStretcher will create a numbered list, representing the images in the slideshow set.
<script type="text/javascript">
jQuery(function($){
$("body").bgStretcher({
images: ["images/sample-1.jpg", "images/sample-2.jpg", "images/sample-3.jpg"],
imageWidth: 1024,
imageHeight: 768,
pagination: "#page-numbers"
});
});
</script>
The above code will output something similar to the following HTML:
<div id="page-numbers">
<ul>
<li class="showPage"><a href="javascript:;">1</a></li>
<li><a href="javascript:;">2</a></li>
<li><a href="javascript:;">3</a></li>
</ul>
</div>
The duration an image is displayed and the speed of the transition effect can be set when initializing bgStretcher.
Use the "nextSlideDelay" option to set the duration an image is displayed. The default value is 3000 milliseconds (3 seconds).
<script type="text/javascript">
jQuery(function($){
$("body").bgStretcher({
images: ["images/sample-1.jpg", "images/sample-2.jpg", "images/sample-3.jpg"],
imageWidth: 1024,
imageHeight: 768,
nextSlideDelay: 5000 // 5 seconds
});
});
</script>
Use the "slideShowSpeed" option to set the speed of the transition effect. The default value is "normal", and it can be set to any jQuery string value ("fast", "normal", "slow") or an integer measured in milliseconds.
<script type="text/javascript">
jQuery(function($){
$("body").bgStretcher({
images: ["images/sample-1.jpg", "images/sample-2.jpg", "images/sample-3.jpg"],
imageWidth: 1024,
imageHeight: 768,
slideShowSpeed: "fast"
});
});
</script>
bgStretcher lets you specify a sequence mode so that your images can be displayed in forward, backward, or random order. Set the "sequenceMode" option to "normal", "back", or "random" to change the display order. The default value is "normal".
Note: "random" mode does not work if you supply next/previous buttons or pagination, or if the "transitionEffect" option is set to simpleSlide.
<script type="text/javascript">
jQuery(function($){
$("body").bgStretcher({
images: ["images/sample-1.jpg", "images/sample-2.jpg", "images/sample-3.jpg"],
imageWidth: 1024,
imageHeight: 768,
transitionEffect: "superSlide",
sequenceMode: "random"
});
});
</script>
When bgStretcher is in "simpleSlide" or "superSlide" mode, you may specify cardinal directions to adjust the direction the slides move when they transition. The default is north, "N".
Possible Values:Demo: Simple Slideshow
<script type="text/javascript">
jQuery(function($){
$("body").bgStretcher({
images: ["images/sample-1.jpg", "images/sample-2.jpg", "images/sample-3.jpg"],
imageWidth: 1024,
imageHeight: 768,
slideDirection: "E"
});
});
</script>
If bgStretcher is in "superSlide" mode, you may also supply these additional values:
Demo: Super Slideshow
<script type="text/javascript">
jQuery(function($){
$("body").bgStretcher({
images: ["images/sample-1.jpg", "images/sample-2.jpg", "images/sample-3.jpg"],
imageWidth: 1024,
imageHeight: 768,
transitionEffect: "superSlide",
slideDirection: "NE"
});
});
</script>
If you need to run a function after the transition of each slide completes, you can pass a callback function to bgStretcher during intialization. Set the "sliderCallbackFunc" option to an anonymous function, or a reference to a function, to have that function fire when image transitions complete.
<script type="text/javascript">
jQuery(function($){
$("body").bgStretcher({
images: ["images/sample-1.jpg", "images/sample-2.jpg", "images/sample-3.jpg"],
imageWidth: 1024,
imageHeight: 768,
sliderCallbackFunc: function() {
// Do something after image transition.
}
});
});
</script>
| Configuration Option | Default Value | Description |
|---|---|---|
| anchoring | "left top" | Sets the anchor of the bgStretcher container in relation to the window or parent element. For example, 'bottom right' would anchor the bottom, right corner of the bgStretcher container to the bottom, right corner of the parent element. |
| anchoringImg | "left top" | Sets the anchor of bgStretcher images in relation to the container. For example, 'bottom right' would anchor the bottom, right corner of the images to the bottom, right corner of the container element. |
| buttonNext | "" | Next button CSS class name. |
| buttonPrev | "" | Previous button CSS class name. |
| containerId | "bgStretcher" | bgStretcher will automatically build a structure for the images list in a DOM tree. This parameter defines the ID for the structure's container. Try inspecting the tree with developer tools to get an idea of how it's constructed. |
| images | [] – an empty array | An array containing the list of images to be displayed as the page or element's background. |
| content | [] – an empty array | An array containing the list of text/html values to be displayed for each slide. The number if items in this array should be exactly the same as "images" array. |
| imageWidth | 1024 | Original image width. (Used for calculating the image aspect ratio) |
| imageHeight | 768 | Original image height. (Used for calculating the image aspect ratio) |
| maxWidth | "auto" | Maximum image width. The container will not be wider than the maxWidth. |
| maxHeight | "auto" | Maximum image height. The container will not be taller than the maxHeight. |
| nextSlideDelay | 3000 – 3 seconds | Sets the delay before the next slide is displayed (the duration an image is displayed). Possible Values: Integer measured in milliseconds. |
| pagination | "" | CSS selector for pagination element. |
| preloadImages | false | Causes bgStretcher to (invisably) inject the images into the page to be downloaded by the browser instead of downloading them as they are called by the script. The script continues to run whether the images have downloaded fully or not. |
| resizeAnimate | false | Indicates whether background image(s) will animate when they're resized. (Be careful, this may slow down some PCs if your images are large.) |
| resizeProportionally | true | Indicates whether the background image(s) will be resized proportionally (with a fixed aspect ratio) or not (possibly distorting them to fit the screen). |
| sequenceMode | "normal" | If the images array contains multiple values and the slide show is enabled, this option defines the order in which images will be displayed.
Note: "random" does not work when transitionEffect is set to "simpleSlide" |
| slideDirection | "N" | Sets the direction in which images slide when the "transitionEffect" option is set to "simpleSlide" or "superSlide". If you use the "superSlide" option you may also use the following values: "NW" - north west, "NE" - north east, "SW" - south west, "SE" - south east.
|
| sliderCallbackFunc | null | Name of the callback function that is called when a slide finishes changing. |
| slideShow | true | Enables or disables slideshow functionality. This option does not have an effect when there is only one image. |
| slideShowSpeed | "normal" | Sets the speed of the image transition. Possible Values: Integer measured in milliseconds or jQuery string value ("fast", "normal", "slow"). |
| startElementIndex | 0 | Index of the starting image when multiple images are supplied for a slideshow. |
| displayFirstImageOnce | false | If true then the first image in the slideshow will be displayed once only. |
| transitionEffect | "fade" | Sets the effect to use for transitions Possible Values:
|
| Method Name | Description |
|---|---|
| $(elementId).bgStretcher.play() | Resumes slideshow. |
| $(elementId).bgStretcher.pause() | Pauses slideshow. |
| $(elementId).bgStretcher.sliderDestroy() | Completely destroys slider. |
bgStretcher is fully supported by w3Blender. Support can be obtained by posting a comment to the bgStretcher CodeCanyon page, by emailing w3Blender at support@w3Blender.com, or by going to the w3Blender.com home page and clicking "Live Chat".
Photos in preview are from http://www.pixabay.com