Contact Me

@zoltandulac

Categories

Archives

cssSandpaper – a CSS3 JavaScript Library

Remix of images by Parée Erica and Hans Christophersen

The cssSandpaper JavaScript library looks at the stylesheets in an HTML document and, where possible, smooths out the browser differences between CSS3 properties like transform, opacity, box-shadow and others.  This script is not only useful for developers who want to support CSS3 in IE (which doesn’t support it in IE natively) but in other browsers which implement their own vendor-specific variants of these properties.

For a good introduction to cssSandpaper and how it works under the covers, you may want to first read these blog-posts:

How to Use

  1. Download the JavaScript archive linked to at the end of this manual
  2. Put the following code in the head of your document
    <script type="text/javascript" src="/path/to/shared/js/EventHelpers.js">
</script>
<script type="text/javascript" src="/path/to/shared/js/cssQuery-p.js">
</script>
<script type="text/javascript" src="/path/to/shared/js/jcoglan.com/sylvester.js">
</script>
<script type="text/javascript" src="/path/to/shared/js/cssSandpaper.js">
</script>

    (Thanks to Zoe Gillenwater for pointing out an error in the script declarations above).

  3. Edit your CSS to use the properties in the CSS Properties Section, or use JavaScript to create scripted effects using the information from the DOM Manipulation Section.  Note that you can speed up the loading of your pages by inserting the class="cssSandpaper-noIndex" attribute into link and style tags that do not have any cssSandpaper supported markup.

Note that all supported properties except for opacity use the vendor-specific prefix -sand-. This is prevent interference with native implementations of these properties.

-sand-transform

Description

Transforms allow developers to rotate, scale, and skew blocks of HTML via CSS.

Syntax

#container {
   -sand-transform:  <function-list>;
}

where <function-list> can be a space separated list of the following functions:

Function Purpose
rotate(angle) Rotates HTML elements. angle can be in degrees (e.g. rotate(30deg)) or radians rotate(1.3rad)
scale(sx[, sy]) Scales HTML elements. sx and sy are numbers, where 1 represents the original size, 2 represents twice the size, etc. Note that if sy isn’t specified, it is assumed to be equal to sx. Similar functions are scaleX(sx) and scaleY(sy).
translate(tx, ty) Translates (moves horizontally and vertically) HTML elements from the object’s perspective (as opposed to the CSS top and left which moves an object from the browser’s perspective. tx and ty are the horizontal and vertical translation offsets. Internet Explorer support for this function was introduced in version 1.1 beta 1. For more information, visit my blog post on the subject.
skew(ax[, ay]) Skews the object around the x and y axes by the specified angles in degrees or radians. If ay isn’t provided, it is assumed to be 0deg.
matrix(a, c, b, d, tx, ty) Applies a 2D transformation matrix comprised of the specified six values. If you aren’t familiar with linear algebra and matrix arithmetic, this function will be hard to understand. For further information, you may want to read Wikipedia’s Transformation Matrix article, although if you are mathematically challenged, you may run away from your computer screaming.

If you are familiar with matrix multiplication, note that c and b are reversed. This follows the way Firefox has implemented this method (i believe WebKit based browsers reverse these numbers).

Examples

-sand-box-shadow

Description

box-shadow allows us to take a block level element and put a shadow underneath. There can optionally set a blur factor to give a warmer effect to the shadow.

Syntax

#container {
   -sand-box-shadow: <horizontal-offset> <vertical-offset> <blur-radius>;
}

Note that in IE, the blur-radius is not currently not supported, due to a lack of support in IE’s DropShadow filter.

Examples

-sand-gradient

Description

Gradients are gradual blends of color, and can be linear or radial:

Syntax

#container {
   background-image: -sand-gradient(<type>, <start-point>, <end-point>, <color-stop1>, <color-stop2>, ..., <color-stopN>)
}

The type can be linear and gradient, although Internet Explorer doesn’t support radial gradients at this time, due to limitations in IE’s gradient filter. Internet Explorer also only supports simple linear gradients (i.e. only horizontal and vertical and only two colours).

A more detailed explanation can be found in the section regarding gradients of the W3C’s working draft of CSS Image Values Module Level 3

RGBA gradients are also supported. For details on what this is and how to implement RGBA gradients, please visit my blog post on the subject.

Caveats

Firefox version 3.6+ natively uses a very different syntax for gradients.  If -sand-gradient() is used in this browser, the native implementation will not be used but the a JavaScript implementation using Canvas.   cssSandpaper will be updated to use the Firefox native version in a future release.

Examples

opacity

Description

Sets the opacity level of a block of HTML

Syntax

#container {
   opacity:  <opacity-level;;
}

where <opacity-level> is a number between 0 and 1.

Examples

Opacity Test

RGBA, HSL and HSLA colorspaces

Description

RGBA allows alpha channel support to the RGB colorspace. HSL is an alternative, easy to use, human friendly
color-space. HSLA allows alpha channel support to the HSL colorspace.

Syntax

#container1 {
   background: rgba(32, 45, 230, 0.5);
}

#container2 {
   background: hsl(120, 50%, 50%);
}

#container3 {
   background: hsl(270, 100%, 50%, 0.4);
}

More information about these colorspaces can be found in the User Agent Man articles cssSandpaper Now Supports transform: translate() and rgba() Gradients and

Examples

Developers can use cssSandpaper to manipulate transform, opacity, box-shadow, and background gradients, using cssSandpaper.setOpacity(), cssSandpaper.setBoxShadow() and cssSandpaper.setGradient() respectively. All these functions take two parameters, a DOM node, and the second is the CSS property value that is of the syntax described on my previous blog post. For example:

    cssSandpaper.setTransform(node, "rotate(25deg) scale(2, 2) skew(20deg, 20deg)");
    cssSandpaper.setOpacity(node, 0.3);
    cssSandpaper.setBoxShadow(node, "10px 10px 5px #ffcccc");
    cssSandpaper.setGradient(node, "-sand-gradient(linear, center top, center bottom, from(#0000ff), to(#ff0000));")

Known Issues

  • Currently, when a users changes the font-size in IE, the layout gets a little messed up. This will be fixed in a future release.
  • Opera 10.5 sort of works. It works on my copy, but not on another copy I’ve seen. I don’t know why yet, but I will find out soon and post and update when I
    do.
  • In IE, having a transparent background or a background with an alpha channel seems to result in an ugly pixely block. This seems like it may be a limitation of IE’s CSS filters and there may not be a workaround available. If one does come up, I’ll definitely update (and if anyone smarter than me finds one, I would be very grateful if you would give me a few pointers ;-). Thanks to Robert Momary for pointing this out.

Future Work

cssSandpaper is a living, active project.  I intend to support more CSS3 properties as time goes on, as well as fix bugs that I or others come across.

Any feedback is welcome, either as a comment on this page or emailing the address in the top left corner.

Acknowledgments

I would like to thank Weston Ruter for his CSS Gradients in Canvas script, since I stole many of his ideas with his permission (I will be implementing more of the advanced features of his script in a future release of cssSandpaper). I would also like to thank James Coglan for building Sylvester so I didn’t have to.

Downloads

Download version 1.2 of cssSandpaper

(Thanks for Lemaire Adrien for pointing out a script tag error in some of the examples within the earlier 1.1 beta 1 release).

 <a href="http://reference.sitepoint.com/css/vendorspecific">vendor-specific prefix</a> <code>-sand-</code>

20 Comments

20 responses so far ↓

  • 1 Anonymous // Apr 26, 2010 at 12:51 pm

    [...] CSS Transforms ? Even in IE, jonka on kirjoittanut Zoltan ?Du Lac? Hawryluk. H

  • 2 CSS3 Transitions – Are We There Yet? | samuli.hakoniemi.net // Apr 26, 2010 at 12:52 pm

    [...] Additionally, I recommend reading an article titled Cross-Browser Animated CSS Transforms ? Even in IE, written by Zoltan ?Du Lac? Hawryluk who is the author of cssSandpaper. [...]

  • 3 Kev Adamson // Apr 28, 2010 at 6:54 pm

    But gradient is currently different between FF and Webkit??

    Also, putting -sand- in my css – would it not be better to somehow target then actual correct syntax, so you would put border-radius and it would auto write the testing prefixes? That way, when everything is fully supported you only have to remove the JS file.

  • 4 [Web] 連結分享 - 傑夫碎碎唸-有線電視、漫畫、PHP、Pushmail、Blackberry // Apr 29, 2010 at 5:00 am

    [...] cssSandpaper – a CSS3 JavaScript Library [...]

  • 5 This looks like a useful tool … 01 | transmission line noise // Apr 30, 2010 at 9:31 am

    [...] for full details and to download [...]

  • 6 Jon // May 2, 2010 at 5:00 pm

    Awesome – if it would also handle rounded corners I’d be SOLD!!!

  • 7 zoltan // May 2, 2010 at 9:04 pm

    I would definitely like to do that. There are many solutions for border-radius in IE, but one of the things I want for a cssSandpaper solution is that any transforms done on an object would not affect their border-radius. I think it’s doable, but a lot of work. I will let you know if I get this done … or if anyone out there wants to help out and get a huge amount of JavaScript street cred.

  • 8 zoltan // May 7, 2010 at 10:47 am

    @Kev: yes, unfortunately there is a huge difference between the syntax between Firefox’s and WebKit’s syntax for gradients. Right now, cssSandpaper uses WebKit style syntax, and uses Weston Ruter’s algorithm to implement this gradient in Firefox. It would be nice to be able to translate WebKit’s gradient systems to Firefox’s so I can use Firefox’s native gradient, but this looks complicated.

    I am not exactly which syntax is going to win in the end, and is one of the reasons why I have decided to use the -sand prefix on my CSS properties and functions. I would rather I didn’t have to, and in some cases I don’t – the opacity property is one example. For stuff like transforms and box-shadow, there doesn’t look like there is a huge difference between the syntax between the non-IE browsers, so I might just decide to allow both transform and -sand-transform.

    Another question that has been asked before is whether it should respect -webkit and -moz versions of the CSS properties, the argument being it would prevent the FOUC (Flash of Unstyled CSS) that happens on object affected by -sand CSS properties before the page loads. I am not exactly sure what the answer to that question is, but it is something to look into.

    This is not the first time this has come up …

  • 9 More CSS3 Goodies « MEDIA SALT // May 11, 2010 at 4:56 am

    [...] 3. cssSandpaper   >Visit Site [...]

  • 10 Some links for light reading (12/05/10) | Max Design // May 12, 2010 at 1:14 pm

    [...] cssSandpaper ? a CSS3 JavaScript Library [...]

  • 11 Rob Crowther // May 13, 2010 at 6:47 am

    @zoltan Firefox gradient syntax is following the current spec, so it’s likely that this syntax will win in the end. This is because Firefox didn’t have a release which implemented gradients until after the syntax was changed in the spec. WebKit can’t reasonably update their own syntax now until after the spec as whole moves forward a stage in the standards process, then they can implement it in the standard format without the vendor prefix.

  • 12 Skrigs // May 14, 2010 at 6:29 am

    Great library.

    Received the following error in Chrome (5.0.375.38 beta) and Firefox (3.5.9)
    under Ubuntu, while integrating its use within a GWT app through a native call.
    runLists[name].add not a function for line 317.

    From what I have read in the last couple of minutes in your script it probably
    got confused on something within in one of the stylesheets being used by GWT.
    I removed any app stylesheets I defined and the error still occurred. If I get
    time I will try to find the stylesheet causing the issue.

  • 13 [rb] // May 14, 2010 at 6:35 am

    Really great idea but this concerns me:

    “Right now, cssSandpaper uses WebKit style syntax, and uses Weston Ruter?s algorithm to implement this gradient in Firefox.”

    I take that to mean that in firefox the sandpaper script still runs applying the -sand properties? If so why? I see you mention “It would be nice to be able to translate WebKit?s gradient systems to Firefox?s so I can use Firefox?s native gradient, but this looks complicated.”
    Surely you should leave Firefox alone and the developer should handle the property correctly for that browser with css. Or do you mean -sand only enhances if its a version of Firefox or other browser that is less that supporting version?

    When I first read the article I has assumed the methodology was something like this:

    .box {
    -moz-box-shadow: 1px 1px 1px #000; /* FF deals with it */
    -webkit-box-shadow: 1px 1px 1px #000; /* webkit deals with it */
    -sand-box-shadow: 1px 1px 1px #000; /* all browsers ignore but valid */
    box-shadow: 1px 1px 1px #000; /* future / browsers that understand now */
    }

    And have sandpaper only enhance browsers that are in need.

    Id love to use this script if it is an unobtrusive script that only adds support to browsers that dont understand the rules. But if it adds support for browsers that dont need the support I think that is a very bad idea as we would no longer be dealing with a true css3 effect.
    Not to mention the fact that youd be running js for no reason and with js disabled there would be no css3 at all if you only define -sand and not the other browser specific properties.

    Like I said love the idea but -sand should be treated as all the other browser specific rules where the intention is in the future there will be no need for -moz, -webkit, -o, -ms, -sand and developers will simply remove the -whatever properties.

  • 14 zoltan // May 14, 2010 at 10:33 am

    @Skrigs: you can tell cssSandpaper to ignore link or style tags by setting their class attribute to cssSandpaper-noIndex, which may help your problem. However, if you have time, I’d be indebted to you if you could find out which rule the parser is having a problem with – it would help me bullet-proof the parsing routines and make cssSandpaper more useful. :)

  • 15 zoltan // May 14, 2010 at 10:45 am

    @rb: I think your concerns are valid … I also think there are some developers who would like to use only one syntax for all browsers and not write multiple vendor specific properties (especially if, like gradient, the syntax is really different).

    To give both camps what we want (because I want cssSandpaper to be flexible) , would it be a good idea to make cssSandpaper configurable so that if it’s configured one way, we have the -sand properties executed only if the browser doesn’t support a vendor specific or the official CSS3 property? Maybe the developer could do this if a class is set in the html tag perhaps (like, say class="cssSandpaper-strict" or something along those lines)?

    This could possibly be a great way to minimize the “Flash of unstyled content” that happens sometimes with these CSS3 properties.

    What do you think?

  • 16 Zoe Gillenwater // May 25, 2010 at 2:52 pm

    I can’t get the script to work, and suspect it is because your “How to Use” instructions are incomplete or out of date. I’d love some help.

    You list three scripts to include: cssQuery-p.js, sylvester.js, and css3helpers.js. But, css3helpers.js is not included in the download. The download also includes two additional scripts that aren’t in your instructions: cssSandpaper.js and EventHelpers.js. So I decided to just make a wild guess about which scripts to include, and it’s the four included in the download:
    cssQuery-p.js
    sylvester.js
    cssSandpaper.js
    EventHelpers.js

    I then added the -sand-transform declaration in the CSS as specified.

    But, when I load the page, I get errors about EventHelpers being undefined, and the rotation transform doesn’t work.

    What do I need to change? Will you please update your instructions accordingly?

    Thanks in advance for your help.

  • 17 zoltan // May 26, 2010 at 4:53 pm

    My apologies … I have fixed the script declarations since they are based on the old working version of cssSandpaper called css3helpers.js. If you follow the instructions now, you should have no problems with the transforms.

  • 18 Trevor Burnham // Jul 3, 2010 at 2:22 pm

    I’m curious: If I’m already using jQuery on my site and I want to avoid the 6k addition of cssQuery, could I just substitute jQuery as the document.querySelectorAll? The two have a very similar selector syntax, but not identical. Do you know where it would break?

  • 19 Cross-browser rotations: The Sass Way « Iterative.ly // Jul 3, 2010 at 2:31 pm

    [...] should also mention the cssSandpaper library, which looks very exciting. You define a -sand-transform CSS property and it translates it [...]

  • 20 zoltan // Jul 3, 2010 at 7:52 pm

    @Trevor: adding support for jQuery and other libraries with cassette selector engines would be ideal. It is something I will be looking into in the near future.

Give Feedback

Don't be shy! Give feedback and join the discussion.