diff --git a/doc-src/content/upgrading/css3-v2.markdown b/doc-src/content/upgrading/css3-v2.markdown index 06aaa3ca..499f85d4 100644 --- a/doc-src/content/upgrading/css3-v2.markdown +++ b/doc-src/content/upgrading/css3-v2.markdown @@ -19,7 +19,7 @@ are required to stay up to date. ## Box Shadow The `box-shadow` mixin API has been changed. To upgrade to the new box shadow API, you should -`@import "compass/css3/box-shadow-v2"` or `@import "compass/css/version-2"`. Once you have +`@import "compass/css3/box-shadow-v2"` or `@import "compass/css3/version-2"`. Once you have changed your imports, it is expected that you have migrated your code to the new version, until then, you will receive a deprecation warning from each place in your code where you use deprecated mixins. @@ -56,3 +56,134 @@ To upgrade, you have two choices: would now become: @include box-shadow(inset 5px 5px 2px 3px darken($border_color, 40)) + + +## Transform + +The `transform` mixin API has been changed. To upgrade to the new transform API, you should +`@import "compass/css3/transform-v2"` or `@import "compass/css3/version-2"`. Once you have +changed your imports, it is expected that you have migrated your code to the new version. +Until then, you will receive a deprecation warning from each place in your code where you are +using a deprecated mixin. + +There are several major changes to _how_ the transform mixins are built, to help accomodate +3D transforms while managing the complexity of the options. The old API had few enough options +that the main `transform` mixin listed them all as arguments. The new API for the same mixin +expects a single string with all your transforms listed as they would be in CSS. There are also +two new mixins to handle backwards compatability, and people who preffer long lists of arguments: + +1. `create-transform` - This is a full list of all the possible arguments that can be used in a + 2 or 3D transform, including origin coordinates and so on. It's a bit overwhelming in scope, + and not the recommended technique. + +2. `simple-transform` - This mixin is compatable with the old API, and is optimized for some basic + 2D transforms. To keep your old transforms in place, simply rename them from `transform` to + `simple-transform`. + +For the sake of managing complexity and more closely mimicing css, origin settings have been removed +from all the other transform mixins. Origins should be set directly with the `transform-origin` mixin. + +Because we now support both 2D and 3D transforms, and these transforms overlapp while having different +browser support lists, it became important to let you select which browsers you are targeting with each +transform. With the 3D transforms it is clear, but the 2D transform mixins now all include a final argument +that toggles (true/false) between the full list of 2D-supporting browsers, and the shorter list of +3D-supporting browsers. The argument '3D-only' argument defaults to `false` (2D). You only need to worry +about this if you have 2D transforms that you only want applied in a 3D context. + +In a 3D context you have the additional issue of perspective. The `perspective` mixin can be set on a +parent element to define the 3D stage for all it's decendants, but perspective can also be set on an +element-by-element basis. Because the latter option happens within the transform property (and must be +the first value in the CSS), a `perspective` argument has also been added to all the relevant +transform mixins. + +To update your generic `transform` mixins, you have two opions: + +1. Change the mixin name from `transform` to `simple-transform` and keep the arguments unchanged. For instance: + + @include transform(1.5, 45deg, 1em, 2em, 5deg, -5deg, 100%, 0%) + + would now become: + + @include simple-transform(1.5, 45deg, 1em, 2em, 5deg, -5deg, 100%, 0%) + +2. Keep including the `transform` mixin, but update the arguments to be a space delimited list of transforms. + You may need to split out a distinct transform-origin mixin with this approach. For instance: + + @include transform(1.5, 45deg, 1em, 2em, 5deg, -5deg, 100%, 0%) + + would now become: + + @include transform(scale(1.5) rotate(45deg) translateX(1em) translateY(2em) skewX(5deg) skewY(-5deg)) + @include transform-origin(100%, 0%) + +To upgrade your transform partials (`scale`, `rotate`, `translate`, `skew` and related mixins) you only have one option. +You need to strip any transform-origin arguments into their own mixin, as above. + +The full set of mixins is now as follows: + +* `transform-origin` - ( _[ origin-x, origin-y, origin-z, 3D-only ]_ ) + * `transform-origin2d` - a shortcut for 2D origins with only x and y arguments, automatically targets 2D browsers + * `transform-origin3d` - a shortcut for 3D origins with x, y and z arguments, automatically targets 3D browsers + * `apply-origin` - ( origin _[, 3D-only ]_ ) uses a single, space-delimited argument for the coordinates + +* `transform` - ( transforms _[, 3D-only ]_ ) + * `transform2d`, `transform3d` - shortcuts that automatically target the 2D or 3D browser lists + * `simple-transform`, `create-transform` - longform mixins that take 1 argument per transform option + +* `perspective` - ( perspective ) + * `perspective-origin` - the 'viewer location' set as coordinates + +* `transform-style` - ( style ) + - 'flat' or 'preserves-3d' + +* `backface-visibility` - ( _[ visibility ]_ ) + - 'visible' or 'hidden' + +* `scale` - ( _[ scale-x, scale-y, perspective, 3D-only ]_ ) + * `scaleX`, `scaleY` - shortcuts for the basic 2D scaling + * `scaleZ`, `scale3d` - shortcuts for the 3D options + +* `rotate` - ( _[ rotation, perspective, 3D-only ]_ ) + * `rotateX`, `rotateY` - shortcuts for 3D rotations on the x and y axis + * `rotate3d` - takes three 'vector' arguments that create the axis, and a fourth argument for the angle of rotation + +* `translate` - ( _[ translate-x, translate-y, perspective, 3D-only ]_ ) + * `translateX`, `translateY` - shortcuts for the basic 2D translations + * `translateZ`, `translate3d` - shortcuts for the 3D options + +* `skew` - ( _[ skew-x, skew-y, 3D-only ]_ ) + * `skewX`, `skewY` - shortcuts for skewing along a single axis + +Many of the arguments are optional because of default settings that you can override in your code. +Here is a full list of the defaults: + + // Transform Origin + $default-originx : 50% !default; + $default-originy : 50% !default; + $default-originz : 50% !default; + + // Scale + $default-scalex : 1.25 !default; + $default-scaley : $default-scalex !default; + $default-scalez : $default-scalex !default; + + // Rotate + $default-rotate : 45deg !default; + + // Rotate3d + $default-vectorx : 1 !default; + $default-vectory : 1 !default; + $default-vectorz : 1 !default; + + // Translate + $default-transx : 1em !default; + $default-transy : $default-transx !default; + $default-transz : $default-transx !default; + + // Skew + $default-skewx : 5deg !default; + $default-skewy : 5deg !default; + +Transforms can be quite complex and difficult to understand properly, but there are many good blog +posts on the topic if you need help. Enjoy! + diff --git a/frameworks/compass/stylesheets/compass/css3/_version-2.scss b/frameworks/compass/stylesheets/compass/css3/_version-2.scss index 8d1d2fc0..ebe2eb81 100644 --- a/frameworks/compass/stylesheets/compass/css3/_version-2.scss +++ b/frameworks/compass/stylesheets/compass/css3/_version-2.scss @@ -11,5 +11,5 @@ @import "background-origin"; @import "background-size"; @import "font-face"; -@import "transform"; +@import "transform-v2"; @import "transition";