DMXzone Universal CSS Transforms

What CSSTransforms does, and what it is not able to do

• CSSTransforms IS NOT a jQuery plugin, but a patch for some of it's built-in methods (a plugin needs to be released later, to handle some advanced issues).

The transform CSS property is by definition a list of transformation functions. This is probably the most complex type of css property (not a primitive value and not even a value list). It is a combination of one or more (up to 11) different functions, each of witch can be used more than once. Also, the order DOES matter.

CSSTransforms is designed to be as simple to use, as possible. It attempts to provide a "native" support for those transform functions to jQuery. It is neither possible to make this simple, nor possible to support this in the jQuery way, so we have chosen different approach here. For the sake of functionality and simplicity, we do limit the transform property to a set of unique functions only. For example, if an element has a rotation and skew applied, setting a rotation will replace the existing one (in other words, each transform functions, can be used only once). This brings some limitations, but still covers 90% of use cases and allows us to make other useful things, like supporting a preparatory css properties and mixing them with the regular ones...

All of the CSS transformation function names have been made available for use as a CSS property names with the $.fn.css() method. Those are:

• matrix
• rotate
• scale
• scaleX
• scaleY
• skew
• skewX
• skewY
• translate
• translateX
• translateY

These can also be animated, but see the limitations bellow

Additionally the following are considered very useful and also supported:

• transform
  1. Aliases current transform property name. For example in gecko it's the same as "MozTransform", or in Webkit - "WebkitTransform"..., so just use "transform in any browser" (This also works in IE, or in other old browsers with no CSS transform support).
  2. When used to set a transform (like $(elements).css("transform", cssstring);), the value is expected to be a valid css transform value, but it is less restrictive, than in CSS (will be parsed, unsupported functions will be ignored, all units are optional and so on).
• multiplied-matrix - read only (available when using $.fn.css with a single strange argument "multiplied-matrix") returns a matrix, representing the current multiplied matrix. This means, that all the current transformation functions applied, are "merged" together and represented as a single matrix. It is useful to have a "multiplied-matrix" property, because the matrix multiplication is a complex task, and now we just have it's result at any time...

Limitations

1. Given CSS property can not be used more than once.
2. You can mix transform properties, but you can not order them.
3. "matrix" property can not be animated
4. Only a single-argument functions can be animated. Others can be used as "subtype" functions:
   • Instead of scale use scaleX and scaleY
   • Instead of skew use skewX and skewY
   • Instead of translate use translateX and translateY
5. The transform-origin property is not implemented (for IE and older browser)

Additional resources

• CSS 2D Transforms Module Level 3
• 2D Transforms (dev.opera.com)
• -moz-transform (MDC)

Using $.fn.css()

In jQuery $.fn.css() is used to get or set a css property of the element. One specific thing to note is that when used as a getter, it is queering the computed style, so always returns a value (even is one is not specified by the developer).

We have patched it to support the css transform function names as css property names (plus some others :-) ):

* - Gecko requires units to be used for translate arguments of the matrix. If used in Mozilla, the code will automatically append "px" to them, so matrices will look like "matrix(1, 0, 0, 1, 0px, 0px)".

• GET Returns - The "GET Returns" column shows what can be expected, while using $.fn.css() as a getter. The return value is always a valid and formatted CSS transform value fragment. If the transformation was not applied to the element, the Identity function will be returned.
• Identity - Each transformation function has it's identity call (it does nothing). Note: For "transform" browsers use identity value of "none", but the official recommendation has changed. It is now preferring an identity matrix to be returned, so this can be changed in the future...
• SET argument - If the property can be changed with $.fn.css(), this column describes what kind of argument can be used. Basically, all arguments (one or more) are floating point numbers (or will be converted). All units are optional. In all cases, to use a relative values, the argument must be a string, prefixed with "+=" or "-=".
  Usage Summary:
  • Single argument
    • as number: $(element).css("skew", 30);
    • as string: $(element).css("skew", "30"); or $(element).css("skew", "30deg"); or $(element).css("skew", "-=30"); or $(element).css("skew", "-=30deg");
    • as array: $(element).css("skew", [30]); or $(element).css("skew", ["30"]); or $(element).css("skew", ["30deg"]); or $(element).css("skew", ["+=30"]); ...
  • Multiple arguments
    • as string: $(element).css("skew", "30, 22deg"); or $(element).css("skew", "30, 20"); or $(element).css("skew", "-=30, +=2"); or $(element).css("skew", "-=30deg, 44");..
    • as array: $(element).css("skew", [30, "22deg"]); or $(element).css("skew", [30, 20]); or $(element).css("skew", ["-=30", "+=2"]); or $(element).css("skew", ["-=30deg", 44]); ...
  • For "transform" the argument is a single string - function list. Same as in CSS, but the units are optional.
  • multiplied-matrix can not be set
• Units - What units are used. This is for information only. All units are optional. In fact, units are useless, because the script will strip them, and re add them later as needed. One limitation is that currently the only supported length unit is "px", so it will be used for all lengths (translate, translateX, translateY).
• Can be relative - See SET argument for "how to use" examples
• Can be animated - Unfortunately, not all can be animated (only those, that can be parsed to a single number value)

rotate

          
$("#theimage").css({ "rotate": 30       });
		  
$("#theimage").css({ "rotate": "+=30deg"});
          
$("#theimage").css({ "rotate": -30      });
          
$("#theimage").css({ "rotate": "-=30"   });
          
$("#theimage").css({ "rotate": ["+=15"] });
          
$("#theimage").css({ "rotate": [10]     });

skew

                      
$("#theimage").css({ "skew": 30             });
          
$("#theimage").css({ "skew": "30, 10"       });
          
$("#theimage").css({ "skew": "30deg, 10"    });
          
$("#theimage").css({ "skew": ["30", "+=10"] });
          
$("#theimage").css({ "skew": [20, 140]      });
                      
$("#theimage").css({ "skew": "-=30"         });
                      
$("#theimage").css({ "skew": [55]           });

skewX

          
$("#theimage").css({ "skewX": 30      });
          
$("#theimage").css({ "skewX": -30     });
          
$("#theimage").css({ "skewX": "-=30"  });
          
$("#theimage").css({ "skewX": ["+=15"]});
          
$("#theimage").css({ "skewX": [10]    });

skewY

          
$("#theimage").css({ "skewY": 30      });
          
$("#theimage").css({ "skewY": -30     });
          
$("#theimage").css({ "skewY": "-=30"  });
          
$("#theimage").css({ "skewY": ["+=15"]});
          
$("#theimage").css({ "skewY": [10]    });

scale

                      
$("#theimage").css({ "scale": 2               });
          
$("#theimage").css({ "scale": "2, 0.5"        });
          
$("#theimage").css({ "scale": "1.3, 1"        });
          
$("#theimage").css({ "scale": ["3", "+=0.10"] });
                      
$("#theimage").css({ "scale": "-=0.3"         });
                      
$("#theimage").css({ "scale": [2]             });

scaleX

          
$("#theimage").css({ "scaleX": 3         });
          
$("#theimage").css({ "scaleX": -0.3      });
          
$("#theimage").css({ "scaleX": "-=0.3"   });
          
$("#theimage").css({ "scaleX": ["+=1.5"] });
          
$("#theimage").css({ "scaleX": [2]       });

scaleY

          
$("#theimage").css({ "scaleY": 3         });
          
$("#theimage").css({ "scaleY": -0.3      });
          
$("#theimage").css({ "scaleY": "-=0.3"   });
          
$("#theimage").css({ "scaleY": ["+=1.5"] });
          
$("#theimage").css({ "scaleY": [2]       });

translate

                      
$("#theimage").css({ "translate": 200              });
          
$("#theimage").css({ "translate": "120, 50"        });
          
$("#theimage").css({ "translate": "130px, 100"     });
          
$("#theimage").css({ "translate": ["30", "+=10px"] });
                      
$("#theimage").css({ "translate": "-=30px"         });
                      
$("#theimage").css({ "translate": [120]            });

translateX

          
$("#theimage").css({ "translateX": 30       });
          
$("#theimage").css({ "translateX": -11      });
          
$("#theimage").css({ "translateX": "-=30px" });
          
$("#theimage").css({ "translateX": ["+=15"] });
          
$("#theimage").css({ "translateX": [20]     });

translateY

          
$("#theimage").css({ "translateY": 30       });
          
$("#theimage").css({ "translateY": -11      });
          
$("#theimage").css({ "translateY": "-=30px" });
          
$("#theimage").css({ "translateY": ["+=15"] });
          
$("#theimage").css({ "translateY": [20]     });

matrix

          
$("#theimage").css({ "matrix": "3, 2, 1, 0, 20, -45"                  });
          
$("#theimage").css({ "matrix": [1, 2, 3, "4", "-20px", 45]            });
          
$("#theimage").css({ "matrix": "-=0.3, +=0.2, +=0.1, -=0.5, +=2, +=5" });