43 |
44 | ```
45 |
46 | 2. Methods
47 | ----------------
48 |
49 | ``` javascript
50 | $(".myBackgroundImage").cover([Object options]);
51 | ```
52 |
53 | > ####Initialize / Update Options
54 | >
55 | > Initialize the jQuery Cover plugin on a set of Images.
56 | >
57 | > Optional you can pass an object with options (see below) to the function.
58 | >
59 | > Also you can change options with this at any time after initialisation.
60 |
61 | -------------------------
62 |
63 | ``` javascript
64 | $(".myBackgroundImage").cover("update");
65 | ```
66 |
67 | > #### Update
68 | >
69 | > Tests the aspect ratio of the container against the aspect ratio of the image and updates the display of the image if necessary.
70 |
71 | -------------------------
72 |
73 | ``` javascript
74 | $(".myBackgroundImage").cover("bindCallback", Function);
75 | ```
76 |
77 | > #### Bind a Callback/Event
78 | >
79 | > Registers or binds a callback function to a certain event. (see below).
80 |
81 |
82 | 3. Options
83 | ----------------
84 |
85 | Options can be set or changed by passing an object to the cover() function. This can be done on initialisation or afterwards to change any value.
86 |
87 | Here are all the possibile options (set to their __default values__):
88 |
89 | ``` javascript
90 | $(".myBackgroundImage").cover({
91 | backgroundPosition:"center",
92 | checkWindowResize:true,
93 | loadHidden:true,
94 | callbacks: {}
95 | });
96 | ```
97 |
98 | ###Option Details
99 |
100 | ``` javascript
101 | backgroundPosition: String Default: "center"
102 | ```
103 |
104 | > Works similar to the CSS property ``background-position``.
105 | >
106 | > Can be any of the following: __"center"__, __"top"__, __"right"__, __"bottom"__, __"left"__
107 | >
108 | > And also a combination of two like: __"top left"__ or __"bottom left"__.
109 |
110 | -------------------------
111 |
112 | ``` javascript
113 | checkWindowResize: boolean Default: true
114 | ```
115 |
116 | > If true the plugin will automatically call ``$(".myBackgroundImage").cover("update");`` on window resize.
117 |
118 | -------------------------
119 |
120 | ``` javascript
121 | loadHidden: boolean Default: true
122 | ```
123 |
124 | > If true the image is hidden until its displayed properly. This prevents some jittering.
125 |
126 | -------------------------
127 |
128 | ``` javascript
129 | callbacks: { Default: {}
130 | "callbackName": Function(callback function)
131 | Object (multiple callback functions)
132 | Array (multiple callback functions)
133 | }
134 | ```
135 |
136 |
137 | > Allows to register callback functions during initialisation.
138 | >
139 | > To learn more about the available callbacks look at the Callbacks/Events chapter below.
140 |
141 | -------------------------
142 |
143 | 4. Callbacks/Events
144 | ----------------
145 |
146 | During the runtime of the plugin a bunch of callbacks are fired.
147 |
148 | Callbacks can be registered by adding the functions to the options object or by calling the "bindCallback" method.
149 |
150 | Every callback function receives the _data_ object as first parameter while the following parameters can change.
151 |
152 | By returning __false__ in the callback the pluging cancels the current event and stopps its action.
153 |
154 | This is a list of all the callbacks that are available at the moment (to find them in the code search for _#CALLBACK_):
155 |
156 | ``` javascript
157 | "preLoading" function(data) Context: $(".myBackgroundImage")
158 | ```
159 |
160 | > Called on initialisation before the image is loaded.
161 |
162 | -------------------------
163 |
164 | ``` javascript
165 | "postLoading" function(data) Context: $(".myBackgroundImage")
166 | ```
167 |
168 | > Called on initialisation after the image is loaded.
169 |
170 | -------------------------
171 |
172 | ``` javascript
173 | "ratioSwitch" function(data) Context: $(".myBackgroundImage")
174 | ```
175 |
176 | > Called when the display style of the image changes to either be ``width:100%`` or ``height:100%``.
177 |
178 |
179 | ###Add New Callback
180 |
181 | If you need a new callback that is missing, feel free to add it in the code!
182 | Just put the following at the place you need the call:
183 |
184 | ``` javascript
185 | [context].cover("_triggerCallback","myCallbackName" [,parameterOne, parameterTwo, ...]);
186 | ```
187 |
188 | Notice that the new callback will come with all the features of the default ones:
189 | * The _data_ object will always be passed as the first parameter. (And you can add as many additional parameters as you wish.)
190 | * return __false__ will stop the further execution of the acutal event.
191 |
192 | __When you added a new callback, tell me about it! So I can consider adding it to the default callbacks.__
193 |
--------------------------------------------------------------------------------
/jquery.cover.js:
--------------------------------------------------------------------------------
1 | /*!
2 | * jQuery Cover plugin - v1.0.0 (https://github.com/greenish/jquery-cover)
3 | *
4 | * Copyright (c) 2011 Philipp Adrian (www.philippadrian.com)
5 | *
6 | * The MIT Licence (http://opensource.org/licenses/MIT)
7 | *
8 | * Permission is hereby granted, free of charge, to any person obtaining a copy
9 | * of this software and associated documentation files (the "Software"), to deal
10 | * in the Software without restriction, including without limitation the rights
11 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
12 | * copies of the Software, and to permit persons to whom the Software is
13 | * furnished to do so, subject to the following conditions:
14 |
15 | * The above copyright notice and this permission notice shall be included in
16 | * all copies or substantial portions of the Software.
17 |
18 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
24 | * THE SOFTWARE.
25 | */
26 |
27 | (function($) {
28 | ////////////////////////////////////////////////////////////////////////////////
29 | var cover=$.fn.cover = function (method){
30 | var call, args;
31 | if(typeof(method) === 'object' || !method) {
32 | args=arguments;
33 | call="_init";
34 | }
35 | else if(cover[method]) {
36 | args=Array.prototype.slice.call(arguments,1);
37 | call=method;
38 | }
39 | else throw "Error: The method \""+method+"\" doesn't exist in jQuery Cover";
40 |
41 | return $(this).each(function(){
42 | // Make sure to select the image (and not a wrapper)
43 | var img=$(this).is("img") ? $(this) : $("img", this),
44 | data = img.data("data");
45 |
46 | // IF already initialized -> update options.
47 | if(call == "_init" && data) {
48 | cover._opts(data, method, true);
49 | return;
50 | }
51 | data = data || {
52 | self:$(this),
53 | callbacks : []
54 | };
55 |
56 | if(call=="_init") {
57 | data.opts=method=="_init"?Array.prototype.slice.call(arguments,1):method;
58 | args=[data];
59 | }
60 | else args=[data].concat(args);
61 | img.data("data", data);
62 | if(call=="_triggerCallback") return cover[call].apply(img, args);
63 | else try {
64 | cover[call].apply(img, args);
65 | }
66 | catch(err){
67 | if(err!="callbackReturnedFalse") throw err;
68 | }
69 | });
70 | };
71 | $.extend(cover, {
72 | interval:false,
73 | ////////////////////////////////////////////////////////////////////////////////
74 | _init : function (data) {
75 |
76 | // Extends defaults into opts.
77 | var opts=cover._opts(data, data.opts, true);
78 | data.img = new Image();
79 |
80 | // binding callbacks to make them available.
81 | for(var callbacks in opts.callbacks) cover.bindCallback(data,callbacks,opts.callbacks[callbacks]);
82 |
83 | //if currentSrc is undefined (old browsers), use the src attribute
84 | if ( typeof data.self.prop("currentSrc") === "undefined" ) data.img.src = data.self.attr("src");
85 | else data.img.src = data.self.prop("currentSrc") ;//modern browser : use loaded image
86 |
87 | //console.log(data.img.src );
88 |
89 | data.self.wrap($("
41 |