3 |
4 |
5 |
6 | jQuery Animations with automatic CSS3 transitions when possible
8 | jquery.animate-enhanced plugin
66 | Extend $.animate() to detect CSS transitions for Webkit, Mozilla and Opera and convert animations automatically. Compatible with IE6+
67 |
68 | Properties supported: (more to come)
69 |
70 | left/right : using translate(x, y) or translate3d(x, y, z)
71 | top/bottom : using translate(x, y) or translate3d(x, y, z)
72 | opacity
73 | width
74 | height
75 |
76 |
77 | New features in v1.0:
78 |
79 | Animation 'queue' support (including .delay())
80 | Context issues fixed on callback(); 'this' = element passed in
81 | $.translate() method to calculate x/y transforms from CSS3 Matrix
82 | Support for $.fn.stop([clearQueue, jumpToEnd, leaveTransforms])
83 | Tweaks for jQuery 1.4.3
84 | Enhance 'width' and 'height' properties
85 | Compatible with .fadeIn(), .fadeOut(), .slideUp(), .slideDown() and slideToggle()
86 | jQuery shortcuts ("fast", "slow")
87 | Use relative values (+= / -=) for animations
88 | Use strings, numbers, 'px' values and the plugin will sanitize them
89 | Callback function is now optional (bug from previous version)
90 | Apply animations to any number of elements and CSS3/DOM animations will take care of themselves
91 | Multiple bug fixes
92 | Licensed under MIT License
93 |
94 |
95 |
96 |
97 |
98 | Note that any properties not mentioned above will simply be handled by the standard jQuery $.animate() method. This plugin adds new functionality without taking any away. Requires jQuery 1.3.2+
99 |
100 | Demo
101 | The animation types can be used in any combination, and with any number of elements. See 3 different types below:
102 |
103 |
104 |
Animate with CSS3 (leaveTransforms:false)
105 |
108 |
Animate with CSS3 (leaveTransforms:true)
109 |
112 |
Animate with DOM (avoidTransforms:true)
113 |
Animate
116 |
117 | Awaiting button click...
118 |
119 |
120 |
121 | What it does
122 | The plugin will analyse the properties you're animating on, and select the most appropriate method for the browser in use. This means your transitions on left, top and opacity will convert to a CSS3 transition on Webkit & Mozilla agents that support it, and Opera 10.50+. If the user is on a browser that has no CSS3 transitions, this plugin knows about it and won't get involved. Silent degradation :)
123 |
124 | Multiple callback mechanisms are created internally to monitor for DOM manipulation and for all 'transitionend ' CSS3 events to be picked up. This means you have one neat callback() for the whole animation regardless on whether the plugin is using CSS3, DOM, or both for its animations.
125 |
126 | Progressively enhanced CSS3 animations without having to do any browser detection or special CSS, therefore using the same Javascript across your applications and websites.
127 |
128 | As this plugin uses CSS3 translate where available, there is an internal callback mechanism to reset the 'left' and/or 'top' properties so that your layout is unaffected.
129 |
130 | Usage
131 | Usage is identical to the jQuery animate() function , but it comes with 3 new paramaters, which are totally optional and safe to leave untouched for general use:
132 |
133 |
134 | avoidTransforms : (Boolean)
137 |
138 |
139 | useTranslate3d : (Boolean)here's why ).
141 |
142 |
143 |
144 | leaveTransforms : (Boolean)true to skip this functionality.
146 |
147 |
148 |
149 | Download
150 |
154 |
155 | Credits
156 |
161 |
162 | License
163 | Licensed under the MIT License .
164 |
165 |
166 |
167 |
168 |
Comments
169 |
Please DO NOT put bug reports on the comments below. Feel free to report any issues on the Github Issues page.
170 |
171 |
172 |
Please enable JavaScript to view the comments powered by Disqus.
184 | blog comments powered by
185 |
186 |
187 | -1;
448 |
449 |
450 | if (isDirection) {
451 | var meta = enhanceData.meta,
452 | cleanPropertyValue = _cleanValue(e.css(property)) || 0,
453 | stashedProperty = property + '_o';
454 |
455 | offsetPosition = value - cleanPropertyValue;
456 |
457 |
458 | meta[property] = offsetPosition;
459 | meta[stashedProperty] = e.css(property) == 'auto' ? 0 + offsetPosition : cleanPropertyValue + offsetPosition || 0;
460 | enhanceData.meta = meta;
461 |
462 | // fix 0 issue (transition by 0 = nothing)
463 | if (isTranslatable && offsetPosition === 0) {
464 | offsetPosition = 0 - meta[stashedProperty];
465 | meta[property] = offsetPosition;
466 | meta[stashedProperty] = 0;
467 | }
468 | }
469 |
470 | // reapply data and return
471 | return e.data(DATA_KEY, _applyCSSWithPrefix(e, enhanceData, property, duration, easing, offsetPosition, isTransform, isTranslatable, use3D));
472 | }
473 |
474 | /**
475 | @private
476 | @name _applyCSSWithPrefix
477 | @function
478 | @description Helper function to build up CSS properties using the various prefixes
479 | @param {object} [cssProperties] Current CSS object to merge with
480 | @param {string} [property]
481 | @param {integer} [duration]
482 | @param {string} [easing]
483 | @param {variant} [value]
484 | @param {boolean} [isTransform] Is this a CSS transformation?
485 | @param {boolean} [isTranslatable] Is this a CSS translation?
486 | @param {boolean} [use3D] Use translate3d if available?
487 | */
488 | function _applyCSSWithPrefix(e, cssProperties, property, duration, easing, value, isTransform, isTranslatable, use3D) {
489 | var saveOriginal = false,
490 | transform = isTransform === true && isTranslatable === true;
491 |
492 |
493 | cssProperties = cssProperties || {};
494 | if (!cssProperties.original) {
495 | cssProperties.original = {};
496 | saveOriginal = true;
497 | }
498 | cssProperties.properties = cssProperties.properties || {};
499 | cssProperties.secondary = cssProperties.secondary || {};
500 |
501 | var meta = cssProperties.meta,
502 | original = cssProperties.original,
503 | properties = cssProperties.properties,
504 | secondary = cssProperties.secondary;
505 |
506 | for (var i = cssPrefixes.length - 1; i >= 0; i--) {
507 | var tp = cssPrefixes[i] + 'transition-property',
508 | td = cssPrefixes[i] + 'transition-duration',
509 | tf = cssPrefixes[i] + 'transition-timing-function';
510 |
511 | property = (transform ? cssPrefixes[i] + 'transform' : property);
512 |
513 | if (saveOriginal) {
514 | original[tp] = e.css(tp) || '';
515 | original[td] = e.css(td) || '';
516 | original[tf] = e.css(tf) || '';
517 | }
518 |
519 | secondary[property] = transform ? _getTranslation(meta.left, meta.top, use3D) : value;
520 |
521 | properties[tp] = (properties[tp] ? properties[tp] + ',' : '') + property;
522 | properties[td] = (properties[td] ? properties[td] + ',' : '') + duration + 'ms';
523 | properties[tf] = (properties[tf] ? properties[tf] + ',' : '') + easing;
524 | }
525 |
526 | return cssProperties;
527 | }
528 |
529 | /**
530 | @private
531 | @name _isBoxShortcut
532 | @function
533 | @description Shortcut to detect if we need to step away from slideToggle, CSS accelerated transitions (to come later with fx.step support)
534 | @param {object} [prop]
535 | */
536 | function _isBoxShortcut(prop) {
537 | for (var property in prop) {
538 | if ((property == 'width' || property == 'height') && (prop[property] == 'show' || prop[property] == 'hide' || prop[property] == 'toggle')) {
539 | return true;
540 | }
541 | }
542 | return false;
543 | }
544 |
545 |
546 | /**
547 | @private
548 | @name _isEmptyObject
549 | @function
550 | @description Check if object is empty (<1.4 compatibility)
551 | @param {object} [obj]
552 | */
553 | function _isEmptyObject(obj) {
554 | for (var i in obj) {
555 | return false;
556 | }
557 | return true;
558 | }
559 |
560 | /**
561 | * Fetch most appropriate display value for element types
562 | * @see https://github.com/benbarnett/jQuery-Animate-Enhanced/issues/121
563 | * @private
564 | * @param {[type]} tagName [description]
565 | * @return {[type]} [description]
566 | */
567 | function _domElementVisibleDisplayValue(tagName) {
568 | tagName = tagName.toUpperCase();
569 | var displayValues = {
570 | 'LI' : 'list-item',
571 | 'TR' : 'table-row',
572 | 'TD' : 'table-cell',
573 | 'TH' : 'table-cell',
574 | 'CAPTION' : 'table-caption',
575 | 'COL' : 'table-column',
576 | 'COLGROUP' : 'table-column-group',
577 | 'TFOOT' : 'table-footer-group',
578 | 'THEAD' : 'table-header-group',
579 | 'TBODY' : 'table-row-group'
580 | };
581 |
582 | return typeof displayValues[tagName] == 'string' ? displayValues[tagName] : 'block';
583 | }
584 |
585 |
586 | /**
587 | @private
588 | @name _cleanValue
589 | @function
590 | @description Remove 'px' and other artifacts
591 | @param {variant} [val]
592 | */
593 | function _cleanValue(val) {
594 | return parseFloat(val.replace(_getUnit(val), ''));
595 | }
596 |
597 |
598 | function _isValidElement(element) {
599 | var allValid=true;
600 | element.each(function(index, el) {
601 | allValid = allValid && el.ownerDocument;
602 | return allValid;
603 | });
604 | return allValid;
605 | }
606 |
607 | /**
608 | @private
609 | @name _appropriateProperty
610 | @function
611 | @description Function to check if property should be handled by plugin
612 | @param {string} [prop]
613 | @param {variant} [value]
614 | */
615 | function _appropriateProperty(prop, value, element) {
616 | if (!_isValidElement(element)) {
617 | return false;
618 | }
619 |
620 | var is = jQuery.inArray(prop, cssTransitionProperties) > -1;
621 | if ((prop == 'width' || prop == 'height' || prop == 'opacity' || prop == 'left' || prop == 'top') && (parseFloat(value) === parseFloat(element.css(prop)))) is = false;
622 | return is;
623 | }
624 |
625 |
626 | jQuery.extend({
627 | /**
628 | @public
629 | @name toggle3DByDefault
630 | @function
631 | @description Toggle for plugin settings to automatically use translate3d (where available). Usage: $.toggle3DByDefault
632 | */
633 | toggle3DByDefault: function() {
634 | return use3DByDefault = !use3DByDefault;
635 | },
636 |
637 |
638 | /**
639 | @public
640 | @name toggleDisabledByDefault
641 | @function
642 | @description Toggle the plugin to be disabled by default (can be overridden per animation with avoidCSSTransitions)
643 | */
644 | toggleDisabledByDefault: function() {
645 | return pluginDisabledDefault = !pluginDisabledDefault;
646 | },
647 |
648 |
649 | /**
650 | @public
651 | @name setDisabledByDefault
652 | @function
653 | @description Set or unset the 'disabled by default' value
654 | */
655 | setDisabledByDefault: function(newValue) {
656 | return pluginDisabledDefault = newValue;
657 | }
658 | });
659 |
660 |
661 | /**
662 | @public
663 | @name translation
664 | @function
665 | @description Get current X and Y translations
666 | */
667 | jQuery.fn.translation = function() {
668 | if (!this[0]) {
669 | return null;
670 | }
671 |
672 | var elem = this[0],
673 | cStyle = window.getComputedStyle(elem, null),
674 | translation = {
675 | x: 0,
676 | y: 0
677 | };
678 |
679 | if (cStyle) {
680 | for (var i = cssPrefixes.length - 1; i >= 0; i--) {
681 | var transform = cStyle.getPropertyValue(cssPrefixes[i] + 'transform');
682 | if (transform && (/matrix/i).test(transform)) {
683 | var explodedMatrix = transform.replace(/^matrix\(/i, '').split(/, |\)$/g);
684 | translation = {
685 | x: parseInt(explodedMatrix[4], 10),
686 | y: parseInt(explodedMatrix[5], 10)
687 | };
688 |
689 | break;
690 | }
691 | }
692 | }
693 |
694 | return translation;
695 | };
696 |
697 |
698 |
699 | /**
700 | @public
701 | @name jQuery.fn.animate
702 | @function
703 | @description The enhanced jQuery.animate function
704 | @param {string} [property]
705 | @param {string} [speed]
706 | @param {string} [easing]
707 | @param {function} [callback]
708 | */
709 | jQuery.fn.animate = function(prop, speed, easing, callback) {
710 | prop = prop || {};
711 | var isTranslatable = !(typeof prop['bottom'] !== 'undefined' || typeof prop['right'] !== 'undefined'),
712 | optall = jQuery.speed(speed, easing, callback),
713 | callbackQueue = 0,
714 | propertyCallback = function() {
715 | callbackQueue--;
716 | if (callbackQueue === 0) {
717 | // we're done, trigger the user callback
718 | if (typeof optall.complete === 'function') {
719 | optall.complete.apply(this, arguments);
720 | }
721 | }
722 | },
723 | bypassPlugin = (typeof prop['avoidCSSTransitions'] !== 'undefined') ? prop['avoidCSSTransitions'] : pluginDisabledDefault;
724 |
725 | if (bypassPlugin === true || !cssTransitionsSupported || _isEmptyObject(prop) || _isBoxShortcut(prop) || optall.duration <= 0 || optall.step) {
726 | return originalAnimateMethod.apply(this, arguments);
727 | }
728 |
729 | return this[ optall.queue === true ? 'queue' : 'each' ](function() {
730 | var self = jQuery(this),
731 | opt = jQuery.extend({}, optall),
732 | cssCallback = function(e) {
733 | var selfCSSData = self.data(DATA_KEY) || { original: {} },
734 | restore = {};
735 |
736 | if (e.eventPhase != 2) // not at dispatching target (thanks @warappa issue #58)
737 | return;
738 |
739 | // convert translations to left & top for layout
740 | if (prop.leaveTransforms !== true) {
741 | for (var i = cssPrefixes.length - 1; i >= 0; i--) {
742 | restore[cssPrefixes[i] + 'transform'] = '';
743 | }
744 | if (isTranslatable && typeof selfCSSData.meta !== 'undefined') {
745 | for (var j = 0, dir; (dir = directions[j]); ++j) {
746 | var stashedProperty = selfCSSData.meta[dir + '_o'];
747 | if (typeof stashedProperty !== 'undefined') {
748 | restore[dir] = stashedProperty + valUnit;
749 | jQuery(this).css(dir, restore[dir]);
750 | }
751 | }
752 | }
753 | }
754 |
755 | // remove transition timing functions
756 | self.
757 | unbind(transitionEndEvent).
758 | css(selfCSSData.original).
759 | css(restore).
760 | data(DATA_KEY, null);
761 |
762 | // if we used the fadeOut shortcut make sure elements are display:none
763 | if (prop.opacity === 'hide') {
764 | elem = self[0];
765 | if (elem.style) {
766 | display = jQuery.css(elem, 'display');
767 |
768 | if (display !== 'none' && !jQuery._data(elem, 'olddisplay')) {
769 | jQuery._data(elem, 'olddisplay', display);
770 | }
771 | elem.style.display = 'none';
772 | }
773 |
774 | self.css('opacity', '');
775 | }
776 |
777 | // run the main callback function
778 | propertyCallback.call(this);
779 | },
780 | easings = {
781 | bounce: CUBIC_BEZIER_OPEN + '0.0, 0.35, .5, 1.3' + CUBIC_BEZIER_CLOSE,
782 | linear: 'linear',
783 | swing: 'ease-in-out',
784 |
785 | // Penner equation approximations from Matthew Lein's Ceaser: http://matthewlein.com/ceaser/
786 | easeInQuad: CUBIC_BEZIER_OPEN + '0.550, 0.085, 0.680, 0.530' + CUBIC_BEZIER_CLOSE,
787 | easeInCubic: CUBIC_BEZIER_OPEN + '0.550, 0.055, 0.675, 0.190' + CUBIC_BEZIER_CLOSE,
788 | easeInQuart: CUBIC_BEZIER_OPEN + '0.895, 0.030, 0.685, 0.220' + CUBIC_BEZIER_CLOSE,
789 | easeInQuint: CUBIC_BEZIER_OPEN + '0.755, 0.050, 0.855, 0.060' + CUBIC_BEZIER_CLOSE,
790 | easeInSine: CUBIC_BEZIER_OPEN + '0.470, 0.000, 0.745, 0.715' + CUBIC_BEZIER_CLOSE,
791 | easeInExpo: CUBIC_BEZIER_OPEN + '0.950, 0.050, 0.795, 0.035' + CUBIC_BEZIER_CLOSE,
792 | easeInCirc: CUBIC_BEZIER_OPEN + '0.600, 0.040, 0.980, 0.335' + CUBIC_BEZIER_CLOSE,
793 | easeInBack: CUBIC_BEZIER_OPEN + '0.600, -0.280, 0.735, 0.045' + CUBIC_BEZIER_CLOSE,
794 | easeOutQuad: CUBIC_BEZIER_OPEN + '0.250, 0.460, 0.450, 0.940' + CUBIC_BEZIER_CLOSE,
795 | easeOutCubic: CUBIC_BEZIER_OPEN + '0.215, 0.610, 0.355, 1.000' + CUBIC_BEZIER_CLOSE,
796 | easeOutQuart: CUBIC_BEZIER_OPEN + '0.165, 0.840, 0.440, 1.000' + CUBIC_BEZIER_CLOSE,
797 | easeOutQuint: CUBIC_BEZIER_OPEN + '0.230, 1.000, 0.320, 1.000' + CUBIC_BEZIER_CLOSE,
798 | easeOutSine: CUBIC_BEZIER_OPEN + '0.390, 0.575, 0.565, 1.000' + CUBIC_BEZIER_CLOSE,
799 | easeOutExpo: CUBIC_BEZIER_OPEN + '0.190, 1.000, 0.220, 1.000' + CUBIC_BEZIER_CLOSE,
800 | easeOutCirc: CUBIC_BEZIER_OPEN + '0.075, 0.820, 0.165, 1.000' + CUBIC_BEZIER_CLOSE,
801 | easeOutBack: CUBIC_BEZIER_OPEN + '0.175, 0.885, 0.320, 1.275' + CUBIC_BEZIER_CLOSE,
802 | easeInOutQuad: CUBIC_BEZIER_OPEN + '0.455, 0.030, 0.515, 0.955' + CUBIC_BEZIER_CLOSE,
803 | easeInOutCubic: CUBIC_BEZIER_OPEN + '0.645, 0.045, 0.355, 1.000' + CUBIC_BEZIER_CLOSE,
804 | easeInOutQuart: CUBIC_BEZIER_OPEN + '0.770, 0.000, 0.175, 1.000' + CUBIC_BEZIER_CLOSE,
805 | easeInOutQuint: CUBIC_BEZIER_OPEN + '0.860, 0.000, 0.070, 1.000' + CUBIC_BEZIER_CLOSE,
806 | easeInOutSine: CUBIC_BEZIER_OPEN + '0.445, 0.050, 0.550, 0.950' + CUBIC_BEZIER_CLOSE,
807 | easeInOutExpo: CUBIC_BEZIER_OPEN + '1.000, 0.000, 0.000, 1.000' + CUBIC_BEZIER_CLOSE,
808 | easeInOutCirc: CUBIC_BEZIER_OPEN + '0.785, 0.135, 0.150, 0.860' + CUBIC_BEZIER_CLOSE,
809 | easeInOutBack: CUBIC_BEZIER_OPEN + '0.680, -0.550, 0.265, 1.550' + CUBIC_BEZIER_CLOSE
810 | },
811 | domProperties = {},
812 | cssEasing = easings[opt.easing || 'swing'] ? easings[opt.easing || 'swing'] : opt.easing || 'swing';
813 |
814 | // seperate out the properties for the relevant animation functions
815 | for (var p in prop) {
816 | if (jQuery.inArray(p, pluginOptions) === -1) {
817 | var isDirection = jQuery.inArray(p, directions) > -1,
818 | cleanVal = _interpretValue(self, prop[p], p, (isDirection && prop.avoidTransforms !== true));
819 |
820 |
821 | if (/**prop.avoidTransforms !== true && **/_appropriateProperty(p, cleanVal, self)) {
822 | _applyCSSTransition(
823 | self,
824 | p,
825 | opt.duration,
826 | cssEasing,
827 | cleanVal, //isDirection && prop.avoidTransforms === true ? cleanVal + valUnit : cleanVal,
828 | isDirection && prop.avoidTransforms !== true,
829 | isTranslatable,
830 | prop.useTranslate3d);
831 |
832 | }
833 | else {
834 | domProperties[p] = prop[p];
835 | }
836 | }
837 | }
838 |
839 | self.unbind(transitionEndEvent);
840 |
841 | var selfCSSData = self.data(DATA_KEY);
842 |
843 |
844 | if (selfCSSData && !_isEmptyObject(selfCSSData) && !_isEmptyObject(selfCSSData.secondary)) {
845 | callbackQueue++;
846 |
847 | self.css(selfCSSData.properties);
848 |
849 | // store in a var to avoid any timing issues, depending on animation duration
850 | var secondary = selfCSSData.secondary;
851 |
852 | // has to be done in a timeout to ensure transition properties are set
853 | setTimeout(function() {
854 | self.bind(transitionEndEvent, cssCallback).css(secondary);
855 | });
856 | }
857 | else {
858 | // it won't get fired otherwise
859 | opt.queue = false;
860 | }
861 |
862 | // fire up DOM based animations
863 | if (!_isEmptyObject(domProperties)) {
864 | callbackQueue++;
865 | originalAnimateMethod.apply(self, [domProperties, {
866 | duration: opt.duration,
867 | easing: jQuery.easing[opt.easing] ? opt.easing : (jQuery.easing.swing ? 'swing' : 'linear'),
868 | complete: propertyCallback,
869 | queue: opt.queue
870 | }]);
871 | }
872 |
873 | // strict JS compliance
874 | return true;
875 | });
876 | };
877 |
878 | jQuery.fn.animate.defaults = {};
879 |
880 |
881 | /**
882 | @public
883 | @name jQuery.fn.stop
884 | @function
885 | @description The enhanced jQuery.stop function (resets transforms to left/top)
886 | @param {boolean} [clearQueue]
887 | @param {boolean} [gotoEnd]
888 | @param {boolean} [leaveTransforms] Leave transforms/translations as they are? Default: false (reset translations to calculated explicit left/top props)
889 | */
890 | jQuery.fn.stop = function(clearQueue, gotoEnd, leaveTransforms) {
891 | if (!cssTransitionsSupported) return originalStopMethod.apply(this, [clearQueue, gotoEnd]);
892 |
893 | // clear the queue?
894 | if (clearQueue) this.queue([]);
895 |
896 | // route to appropriate stop methods
897 | this.each(function() {
898 | var self = jQuery(this),
899 | selfCSSData = self.data(DATA_KEY);
900 |
901 | // is this a CSS transition?
902 | if (selfCSSData && !_isEmptyObject(selfCSSData)) {
903 | var i, restore = {};
904 |
905 | if (gotoEnd) {
906 | // grab end state properties
907 | restore = selfCSSData.secondary;
908 |
909 | if (!leaveTransforms && typeof selfCSSData.meta['left_o'] !== undefined || typeof selfCSSData.meta['top_o'] !== undefined) {
910 | restore['left'] = typeof selfCSSData.meta['left_o'] !== undefined ? selfCSSData.meta['left_o'] : 'auto';
911 | restore['top'] = typeof selfCSSData.meta['top_o'] !== undefined ? selfCSSData.meta['top_o'] : 'auto';
912 |
913 | // remove the transformations
914 | for (i = cssPrefixes.length - 1; i >= 0; i--) {
915 | restore[cssPrefixes[i]+'transform'] = '';
916 | }
917 | }
918 | } else if (!_isEmptyObject(selfCSSData.secondary)) {
919 | var cStyle = window.getComputedStyle(self[0], null);
920 | if (cStyle) {
921 | // grab current properties
922 | for (var prop in selfCSSData.secondary) {
923 | if(selfCSSData.secondary.hasOwnProperty(prop)) {
924 | prop = prop.replace(rupper, '-$1').toLowerCase();
925 | restore[prop] = cStyle.getPropertyValue(prop);
926 |
927 | // is this a matrix property? extract left and top and apply
928 | if (!leaveTransforms && (/matrix/i).test(restore[prop])) {
929 | var explodedMatrix = restore[prop].replace(/^matrix\(/i, '').split(/, |\)$/g);
930 |
931 | // apply the explicit left/top props
932 | restore['left'] = (parseFloat(explodedMatrix[4]) + parseFloat(self.css('left')) + valUnit) || 'auto';
933 | restore['top'] = (parseFloat(explodedMatrix[5]) + parseFloat(self.css('top')) + valUnit) || 'auto';
934 |
935 | // remove the transformations
936 | for (i = cssPrefixes.length - 1; i >= 0; i--) {
937 | restore[cssPrefixes[i]+'transform'] = '';
938 | }
939 | }
940 | }
941 | }
942 | }
943 | }
944 |
945 | // Remove transition timing functions
946 | // Moving to seperate thread (re: Animation reverts when finished in Android - issue #91)
947 | self.unbind(transitionEndEvent);
948 | self.
949 | css(selfCSSData.original).
950 | css(restore).
951 | data(DATA_KEY, null);
952 | }
953 | else {
954 | // dom transition
955 | originalStopMethod.apply(self, [clearQueue, gotoEnd]);
956 | }
957 | });
958 |
959 | return this;
960 | };
961 | }));
962 |
--------------------------------------------------------------------------------
86 | 
188 |
189 |
190 |
191 |
218 |
219 |
232 |
233 |
241 |
242 |
243 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | jquery.animate-enhanced plugin
2 | ===============
3 |
4 | Extend $.animate() to detect CSS transitions for Webkit, Mozilla, IE >= 10 and Opera and convert animations automatically. Compatible with IE6+
5 |
6 | Tested with jQuery 1.3.2 to 1.8.0
7 |
8 | Properties supported: (more to come)
9 | -----------------
10 |
11 | * left : using translate(x, y) or translate3d(x, y, z)
12 | * top : using translate(x, y) or translate3d(x, y, z)
13 | * right
14 | * bottom
15 | * opacity
16 | * width
17 | * height
18 |
19 | Note that any properties not mentioned above will simply be handled by the standard jQuery $.animate() method. This plugin adds new functionality without taking any away.
20 |
21 | The idea is to simply enhance existing animations with a lightweight 'drop-in' plugin. Those looking for features such as IE transformations & translate() functionality should consider http://plugins.jquery.com/project/2d-transform
22 |
23 |
24 | Demo
25 | -----------------
26 | Simple animation demo and documentation found here: http://playground.benbarnett.net/jquery-animate-enhanced/
27 |
28 |
29 | What it does
30 | -----------------
31 |
32 | The plugin will analyse the properties you're animating on, and select the most appropriate method for the browser in use. This means your transitions on left, top and opacity will convert to a CSS3 transition on Webkit & Mozilla agents that support it, and Opera 10.50+. If the user is on a browser that has no CSS3 transitions, this plugin knows about it and won't get involved. Silent degradation.
33 |
34 | Multiple callback mechanisms are created internally to monitor for DOM manipulation and for all 'transitionend' CSS3 events to be picked up. This means you have one neat callback() for the whole animation regardless on whether the plugin is using CSS3, DOM, or both for its animations.
35 |
36 | Progressively enhanced CSS3 animations without having to do any browser detection or special CSS, therefore using the same Javascript across your applications and websites.
37 |
38 | As this plugin uses CSS3 translate where available, there is an internal callback mechanism to reset the 'left' and/or 'top' properties so that your layout is unaffected.
39 |
40 | Usage
41 | -----------------
42 |
43 | Usage is identical to the jQuery animate() function, but it comes with 3 new paramaters, which are totally optional and safe to leave untouched for general use:
44 |
45 | ### avoidTransforms: (Boolean)
46 | By default the plugin will convert left and top animations to the CSS3 style -webkit-transform (or equivalent) to aid hardware acceleration. This functionality can be disabled by setting this to true.
47 |
48 | ### useTranslate3d: (Boolean)
49 | This will be auto-detected and set to true if the browser supports it. Set to true/false to force a specific mode. 3D is recommended for iPhone/iPad development ([here's why](http://www.benbarnett.net/2010/08/30/writing-html-and-css-for-mobile-safari-just-the-same-old-code/)).
50 |
51 | ### leaveTransforms: (Boolean)
52 | By default if the plugin is animating a left or a top property, the translate (2d or 3d depending on setting above) CSS3 transformation will be used. To preserve other layout dependencies, once the transition is complete, these transitions are removed and converted back to the real left and top values. Set this to true to skip this functionality.
53 |
54 | ### avoidCSSTransitions: (Boolean)
55 | Set this to true to revert to native animate() method, avoiding the plugin entirely. The default for this setting is false, but can be overridden using $.toggleDisabledByDefault()
56 |
57 |
58 | Useful methods
59 | -----------------
60 |
61 | The following methods have been added to the public jQuery object, which you may or may not find useful:
62 |
63 | * $.toggle3DByDefault()
64 | Toggle for plugin settings to automatically use translate3d (where available; its safe to set to true even if the browser doesn't support).
65 | Returns new setting
66 | * $.toggleDisabledByDefault()
67 | Toggle the plugin to be disabled by default (can be overridden per animation with avoidCSSTransitions described above)
68 | Returns new setting
69 | * $.setDisabledByDefault(value)
70 | Explicitly disable or enable the plugin (can be overridden per animation with avoidCSSTransitions described above)
71 | Returns new setting
72 | * $(e).translation()
73 | Returns current X and Y coordinates for (e) no matter how the element is being positioned
74 | Returns in the format { x: 0, y: 0 }
75 |
76 |
77 | Note
78 | -----------------
79 |
80 | Since v0.77, the plugin will now automatically use 3D Translations where supported. To override this functionality, you can either use the parameter above, or run $.toggle3DByDefault();
81 |
82 |
83 | Changelog
84 | -----------------
85 |
86 | 1.11 (08/07/2014):
87 |
88 | * Merging PR #157, fixes #156 for animating with 0
89 |
90 | 1.10 (09/04/2014):
91 |
92 | * Merging PR #153 Don't try to restore values which weren't saved
93 |
94 | 1.09 (09/04/2014):
95 |
96 | * Merging PR #154 Added support of AMD and Node.js (via browserify) environments
97 |
98 | 1.08 (16/01/2014):
99 |
100 | * Merging PR #147 Access element tag name appropriately
101 |
102 | 1.07 (06/12/2013):
103 |
104 | * Other units, beside '%' should also be kept
105 |
106 | 1.06 (06/12/2013):
107 |
108 | * Merging PR #140 Do not change a user defined display mode for elements, after show/hide
109 |
110 | 1.05 (14/08/2013):
111 |
112 | * Merging PR #124 fix for highcharts clash. Thanks @bensonc!
113 |
114 | 1.04 (14/08/2013):
115 |
116 | * Using fix from issue #69 by @rickyk586 to support percentages
117 |
118 | 1.03 (19/7/2013):
119 |
120 | * Merge PR #129 (Use originalAnimateMethod if a step callback function is provided.) /thx @lehni
121 |
122 | 1.02 (8/5/2013):
123 |
124 | * Fixing use3D default flags. It must explicitly be set to false to disable 3d now, the plugin by default will use it if available. (issue #110)
125 |
126 | 1.01 (8/5/2013):
127 |
128 | * Adding appropriate display value for wider range of elements (issue #121 - thanks smacky)
129 |
130 | 1.0 (8/5/2103):
131 |
132 | * Fix avoidTransforms: true behaviour for directional transitions
133 |
134 | 0.99 (5/12/2012):
135 |
136 | * PR #109 Added support for list-item nodes. FadeIn on tags was omitting the list-style support. (thx @SeanCannon)
137 |
138 | 0.98 (12/11/2012):
139 |
140 | * Merging pull request #106 thx @gboysko - checking for ownerDocument before using getComputedStyle
141 |
142 | 0.97 (6/11/2012):
143 |
144 | * Merging pull request #104 thx @gavrochelegnou - .bind instead of .one
145 |
146 | 0.96a (20/08/2012):
147 |
148 | * Checking event is from dispatch target (issue #58)
149 |
150 | 0.96 (20/08/2012):
151 |
152 | * Fixes for context, all elements returned as context (issue #84)
153 | * Reset position with leaveTransforms !== true fixes (issue #93)
154 |
155 | 0.95 (20/08/2012):
156 |
157 | * If target opacity == current opacity, pass back to jquery native to get callback firing (#94)
158 |
159 | 0.94 (20/08/2012):
160 |
161 | * Addresses Firefox callback mechanisms (issue #94)
162 | * using $.one() to bind to CSS callbacks in a more generic way
163 |
164 | 0.93 (6/8/2012):
165 |
166 | * Adding other Opera 'transitionend' event (re: issue #90)
167 |
168 | 0.92 (6/8/2012):
169 |
170 | * Seperate unbinds into different threads (re: issue #91)
171 |
172 | 0.91 (2/4/2012):
173 |
174 | * Merge Pull Request #74 - Unit Management
175 |
176 | 0.90 (7/3/2012):
177 |
178 | * Adding public $.toggleDisabledByDefault() feature to disable entire plugin by default (Issue #73)
179 |
180 | 0.89 (24/1/2012):
181 |
182 | * Adding 'avoidCSSTransitions' property. Set to true to disable entire plugin.
183 |
184 | 0.88 (24/1/2012):
185 |
186 | * Fix Issue #67 for HighchartsJS compatibility
187 |
188 | 0.87 (24/1/2012):
189 |
190 | * Fix Issue #66 selfCSSData.original is undefined
191 |
192 | 0.86 (9/1/2012):
193 |
194 | * Strict JS fix for undefined variable
195 |
196 | 0.85 (20/12/2011):
197 |
198 | * Merge Pull request #57 from Kronuz
199 | * Codebase cleaned and now passes jshint.
200 | * Fixed a few bugs (it now saves and restores the original css transition properties).
201 | * fadeOut() is fixed, it wasn't restoring the opacity after hiding it.
202 |
203 | 0.80 (13/09/2011):
204 |
205 | * Issue #28 - Report $(el).is(':animated') fix
206 |
207 | 0.79 (06/09/2011):
208 |
209 | * Issue #42 - Right negative position animation: please see issue notes on Github
210 |
211 | 0.78 (02/09/2011):
212 |
213 | * Issue #18 - jQuery/$ reference joys
214 |
215 | 0.77 (02/09/2011):
216 |
217 | * Adding feature on Github issue #44 - Use 3D Transitions by default
218 |
219 | 0.76 (28/06/2011):
220 |
221 | * Fixing issue #37 - fixed stop() method (with gotoEnd == false)
222 |
223 | 0.75 (15/06/2011):
224 |
225 | * Fixing issue #35 to pass actual object back as context for callback
226 |
227 | 0.74 (28/05/2011):
228 |
229 | * Fixing issue #29 to play nice with 1.6
230 |
231 | 0.73 (05/03/2011):
232 |
233 | * Merged Pull Request #26: Fixed issue with fadeOut() / "hide" shortcut
234 |
235 | 0.72 (05/03/2011):
236 |
237 | * Merged Pull Request #23: Added Penner equation approximations from Matthew Lein's Ceaser, and added failsafe fallbacks
238 |
239 | 0.71 (05/03/2011):
240 |
241 | * Merged Pull Request #24: Changes translation object to integers instead of strings to fix relative values bug with leaveTransforms = true
242 |
243 | 0.70 (17/03/2011):
244 |
245 | * Merged Pull Request from amlw-nyt to add bottom/right handling
246 |
247 | 0.68 (15/02/2011):
248 |
249 | * Width/height fixes & queue issues resolved.
250 |
251 | 0.67 (15/02/2011):
252 |
253 | * Code cleanups & file size improvements for compression.
254 |
255 | 0.66 (15/02/2011):
256 |
257 | * Zero second fadeOut(), fadeIn() fixes
258 |
259 | 0.65 (01/02/2011):
260 |
261 | * Callbacks with queue() support refactored to support element arrays
262 |
263 | 0.64 (27/01/2011):
264 |
265 | * BUGFIX #13: .slideUp(), .slideToggle(), .slideDown() bugfixes in Webkit
266 |
267 | 0.63 (12/01/2011):
268 |
269 | * BUGFIX #11: callbacks not firing when new value == old value
270 |
271 | 0.62 (10/01/2011):
272 |
273 | * BUGFIX #11: queue is not a function issue fixed
274 |
275 | 0.61 (10/01/2011):
276 |
277 | * BUGFIX #10: Negative positions converting to positive
278 |
279 | 0.60 (06/01/2011):
280 |
281 | * Animate function rewrite in accordance with new queue system
282 | * BUGFIX #8: Left/top position values always assumed relative rather than absolute
283 | * BUGFIX #9: animation as last item in a chain — the chain is ignored?
284 | * BUGFIX: width/height CSS3 transformation with left/top working
285 |
286 | 0.55 (22/12/2010):
287 |
288 | * isEmptyObject function for
Comments
169 |Please DO NOT put bug reports on the comments below. Feel free to report any issues on the Github Issues page.
170 | 171 | 172 |