{"id":951,"date":"2010-04-05T23:14:13","date_gmt":"2010-04-06T03:14:13","guid":{"rendered":"http:\/\/www.useragentman.com\/blog\/?page_id=951"},"modified":"2012-08-11T21:01:17","modified_gmt":"2012-08-12T01:01:17","slug":"csssandpaper-a-css3-javascript-library","status":"publish","type":"page","link":"http:\/\/www.useragentman.com\/blog\/csssandpaper-a-css3-javascript-library\/","title":{"rendered":"cssSandpaper &#8211; a CSS3 JavaScript Library"},"content":{"rendered":"<p><div id=\"attachmehttpswwwuseragentmancomblogwp-adminpagephpactioneditamppost951ampmessage8nt_977\" style=\"width: 267px\" class=\"wp-caption alignright\"><a href=\"https:\/\/www.useragentman.com\/blog\/wp-content\/uploads\/2010\/04\/cssSandpaper.jpg\"><img loading=\"lazy\" decoding=\"async\" aria-describedby=\"caption-attachmehttpswwwuseragentmancomblogwp-adminpagephpactioneditamppost951ampmessage8nt-977\" class=\"size-full wp-image-977 \" title=\"cssSandpaper\" src=\"https:\/\/www.useragentman.com\/blog\/wp-content\/uploads\/2010\/04\/cssSandpaper.jpg\" alt=\"\" width=\"257\" height=\"257\" srcset=\"http:\/\/www.useragentman.com\/blog\/wp-content\/uploads\/2010\/04\/cssSandpaper.jpg 257w, http:\/\/www.useragentman.com\/blog\/wp-content\/uploads\/2010\/04\/cssSandpaper-150x150.jpg 150w\" sizes=\"auto, (max-width: 257px) 100vw, 257px\" \/><\/a><p id=\"caption-attachmehttpswwwuseragentmancomblogwp-adminpagephpactioneditamppost951ampmessage8nt-977\" class=\"wp-caption-text\">Remix of images by Par\u00e9e Erica and Hans Christophersen<\/p><\/div><\/p>\n<p>The cssSandpaper JavaScript library looks at the stylesheets in an HTML document and, where possible, <strong>smooths out the browser differences between CSS3 properties<\/strong> like <code>transform<\/code>, <code>opacity<\/code>, <code>box-shadow<\/code> and others.\u00a0 This script is not only useful for developers who want to support CSS3 in IE (which doesn&#8217;t support it in IE natively) but in other browsers which implement their own vendor-specific variants of these properties.<\/p>\n<p>For a good introduction to cssSandpaper and how it works under the covers, you may want to first read these blog-posts:<\/p>\n<ul>\n<li><a href=\"https:\/\/www.useragentman.com\/blog\/2010\/03\/09\/cross-browser-css-transforms-even-in-ie\/\">Cross Browser Transforms \u2014 even in IE<\/a>: this article talks about how why cssSandpaper was created and how it works under the hood.\u00a0 It also has several interesting examples that can be seen by all modern web browsers.<\/li>\n<li><a href=\"https:\/\/www.useragentman.com\/blog\/2010\/04\/05\/cross-browser-animated-css-transforms-even-in-ie\">Cross-Browser <em>Animated<\/em> CSS Transforms \u2014 even in IE<\/a>: introduces scripting CSS3 properties to create some interesting visual effects.<\/li>\n<\/ul>\n<h2>How to Use<\/h2>\n<ol>\n<li>Download the JavaScript archive linked to at the end of this manual<\/li>\n<li>Put the following code in the <code>head<\/code> of your document<br \/>\n<blockquote class=\"code\">\n<pre>&lt;script type=\"text\/javascript\" src=\"\/path\/to\/shared\/js\/EventHelpers.js\"&gt;\r\n&lt;\/script&gt;\r\n&lt;script type=\"text\/javascript\" src=\"\/path\/to\/shared\/js\/cssQuery-p.js\"&gt;\r\n&lt;\/script&gt;\r\n&lt;script type=\"text\/javascript\" src=\"\/path\/to\/shared\/js\/jcoglan.com\/sylvester.js\"&gt;\r\n&lt;\/script&gt;\r\n&lt;script type=\"text\/javascript\" src=\"\/path\/to\/shared\/js\/cssSandpaper.js\"&gt;\r\n&lt;\/script&gt;\r\n<\/pre>\n<\/blockquote>\n<p>(Thanks to Zoe Gillenwater for pointing out an error in the script declarations above).\n<\/li>\n<li>Edit your CSS to use the properties in the <a href=\"#cssProperties\">CSS Properties Section<\/a>, or use JavaScript to create scripted effects using the information from the <a href=\"#domProperties\">DOM Manipulation Section<\/a>.\u00a0 Note that you can speed up the loading of your pages by inserting the <code>class=\"cssSandpaper-noIndex\"<\/code> attribute into link and style tags that <strong>do not<\/strong> have any cssSandpaper supported markup.<\/li>\n<\/ol>\n<p><a name=\"cssProperties\"><\/a><\/p>\n<h2><a name=\"cssProperties\"><\/a><\/h2>\n<p>Note that all supported properties except for <code>opacity<\/code> and <code>text-shadow<\/code> use the <a href=\"http:\/\/reference.sitepoint.com\/css\/vendorspecific\">vendor-specific prefix<\/a> <code>-sand-<\/code>.  This is prevent interference with native implementations of these properties.<\/p>\n<h3>-sand-transform<\/h3>\n<p><!-- Begin steps --><\/p>\n<div class=\"steps\">\n<h4 class=\"first\">Description<\/h4>\n<p>Transforms allow developers to rotate, scale, and skew blocks of HTML via CSS.<\/p>\n<h4>Syntax<\/h4>\n<blockquote class=\"code\">\n<pre>#container {\r\n   -sand-transform:  <em>&lt;function-list&gt;<\/em>;\r\n}<\/pre>\n<\/blockquote>\n<p>where <em>&lt;function-list&gt;<\/em> can be a space separated list of the following functions:<\/p>\n<table class=\"screenshot\">\n<thead>\n<tr>\n<th>Function<\/th>\n<th>Purpose<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>rotate(angle)<\/code><\/td>\n<td>Rotates HTML elements.  <code>angle<\/code> can be in degrees (e.g. rotate(30deg)) or radians <code>rotate(1.3rad)<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>scale(sx[, sy])<\/code><\/td>\n<td>Scales HTML elements.  <code>sx<\/code> and <code>sy<\/code> are numbers, where <code>1<\/code> represents the original size, <code>2<\/code> represents twice the size, etc.  Note that if <code>sy<\/code> isn&#8217;t specified, it is assumed to be equal to <code>sx<\/code>.  Similar functions are <code>scaleX(sx)<\/code> and <code>scaleY(sy)<\/code>.<\/td>\n<\/tr>\n<tr>\n<td><code>translate(tx, ty)<\/code><\/td>\n<td>Translates (moves horizontally and vertically) HTML elements <strong>from the object\u2019s perspective<\/strong> (as opposed to the CSS <code>top<\/code> and <code>left<\/code> which moves an object from the browser&#8217;s perspective.  <code>tx<\/code> and <code>ty<\/code> are the horizontal and vertical translation offsets.   <strong>Internet Explorer support for this function was introduced in version 1.1 beta 1.<\/strong> For more information, visit <a href=\"\/blog\/2010\/05\/06\/csssandpaper-now-supports-transform-translate-and-rgba-gradients\/\">my blog post on the subject<\/a>.<\/td>\n<\/tr>\n<tr>\n<td><code>skewX(ax)<\/code>, and <code>skewY(ay)<\/code><\/td>\n<td>These functions skew the object around the x and y axes by the specified angles in degrees or radians.<strong>Note: the <code>skew(ax, ay)<\/code> function, which used to work in browsers that support CSS3 Transforms natively is no longer part of the W3C CSS3 spec and is no longer supported by Firefox.<\/strong><\/td>\n<\/tr>\n<tr>\n<td><code>matrix(a, c, b, d, tx, ty)<\/code><\/td>\n<td>Applies a 2D transformation matrix comprised of the specified six values.  If you aren&#8217;t familiar with linear algebra and matrix arithmetic, this function will be hard to understand.  For further information, you may want to read <a href=\"http:\/\/en.wikipedia.org\/wiki\/Transformation_matrix\">Wikipedia&#8217;s Transformation Matrix<\/a> article, although if you are mathematically challenged, you may run away from your computer screaming.<\/p>\n<p><strong>If you are familiar with matrix multiplication, note that c and b are reversed.<\/strong> This follows the way Firefox has implemented this method (i <strong>believe<\/strong> WebKit based browsers reverse these numbers).<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h4>Examples<\/h4>\n<ul>\n<li><a href=\"\/tests\/cssSandpaper\/rotateTest.html\">Rotations<\/a><\/li>\n<li><a href=\"\/tests\/cssSandpaper\/skewTest.html\">Skews<\/a><\/li>\n<\/ul>\n<\/div>\n<h3>text-shadow<\/h3>\n<p><!-- Begin steps --><\/p>\n<div class=\"steps\">\n<h4 class=\"first\">Description<\/h4>\n<p>This property, which is an official CSS3 property, allows developers to add text-shadows to the text that matches the selector(s) used.  Using it in conjunction with cssSandpaper allows IE 7-9 to implement the text-shadow.<\/p>\n<h4>Syntax<\/h4>\n<blockquote class=\"code\">\n<pre>#container {\r\n   text-shadow:  <em>&lt;x-offset&gt; &lt;y-offset&gt; &lt;blur-radius&gt; &lt;color&gt;<\/em>;\r\n}<\/pre>\n<\/blockquote>\n<p>The <em>x-offset<\/em> and <em>y-offset<\/em> values state how many pixels horizontally and vertically the shadow is positioned with respect to the original text, while the <em>blur-radius<\/em> value is used to express how much the shadow is blurred (the higher the value, the more blurry it is).  All of these values can be expressed using any CSS unit of measure (e.g. <code>px<\/code>, <code>em<\/code>, etc).  The <em>color<\/em> can be any CSS color value, representing the color of the text.<\/p>\n<p>A full description of how to use text-shadows with cssSandpaper can be seen in my article <a href=\"\/blog\/2011\/06\/29\/full-css3-text-shadows-even-in-ie\/\">Full CSS3 Text-Shadows \u2014 Even In IE<\/a>.<\/p>\n<h4>Examples<\/h4>\n<ul>\n<li><a href=\"\/packages\/cssSandpaper-1.5\/tests\/csssandpaper\/textshadowcss3info.html\">Flaming <\/a><\/li>\n<li><a href=\"\/packages\/cssSandpaper-1.5\/tests\/csssandpaper\/textshadowline25.html\">Various Other Examples<\/a><\/li>\n<li>My own example of a <a href=\"lawAndOrder.html\">Parody of a logo from a famous TV show.<\/a><\/li>\n<\/ul>\n<\/div>\n<h3>-sand-box-shadow<\/h3>\n<div class=\"steps\">\n<h4 class=\"first\">Description<\/h4>\n<p><code>box-shadow<\/code> 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.<\/p>\n<h4>Syntax<\/h4>\n<blockquote class=\"code\">\n<pre>#container {\r\n   -sand-box-shadow: <em>&lt;horizontal-offset&gt;<\/em> <em>&lt;vertical-offset&gt;<\/em> <em>&lt;blur-radius&gt;<\/em>;\r\n}<\/pre>\n<\/blockquote>\n<p>Note that in IE, the <code>blur-radius<\/code> is not currently not supported, due to a lack of support in IE&#8217;s <a href=\"http:\/\/msdn.microsoft.com\/en-us\/library\/ms533014%28VS.85%29.aspx\"><code>DropShadow<\/code> filter<\/a>.<\/p>\n<h4>Examples<\/h4>\n<ul>\n<li><a href=\"\/tests\/cssSandpaper\/boxShadowTest.html\">Box-Shadow Example<\/a><\/li>\n<\/ul>\n<\/div>\n<h3>-sand-gradient<\/h3>\n<div class=\"steps\">\n<h4 class=\"first\">Description<\/h4>\n<p>Gradients are gradual blends of color, and can be <code>linear<\/code> or <code>radial<\/code>:<\/p>\n<h4>Syntax<\/h4>\n<blockquote class=\"code\">\n<pre>#container {\r\n   background-image: -sand-gradient(<em>&lt;type&gt;, &lt;start-point&gt;, &lt;end-point&gt;, &lt;color-stop1&gt;, &lt;color-stop2&gt;, ..., &lt;color-stopN&gt;<\/em>)\r\n}<\/pre>\n<\/blockquote>\n<p>The type can be <code>linear<\/code> and <code>gradient<\/code>, although Internet Explorer doesn&#8217;t support radial gradients at this time, due to limitations in IE&#8217;s <a href=\"http:\/\/msdn.microsoft.com\/en-us\/library\/ms532997%28VS.85%29.aspx\"><code>gradient<\/code> filter<\/a>.  Internet Explorer also only supports simple linear gradients (i.e. only  horizontal and vertical and only two colours).<\/p>\n<p>A more detailed explanation can be found in the <a href=\"http:\/\/dev.w3.org\/csswg\/css3-images\/#linear-gradients\">section regarding gradients<\/a> of the <a href=\"http:\/\/dev.w3.org\/csswg\/css3-images\/\">W3C&#8217;s working draft of CSS Image Values Module Level 3<\/a><\/p>\n<p>RGBA gradients are also supported. For details on what this is and how to implement RGBA gradients, please visit <a href=\"\/blog\/2010\/05\/06\/csssandpaper-now-supports-transform-translate-and-rgba-gradients\/\">my blog post on the subject<\/a>.<\/p>\n<h4 style=\"font-size: 1em;\">Caveats<\/h4>\n<p>Firefox version 3.6+ natively uses a very different syntax for gradients.\u00a0 If\u00a0<code>-sand-gradient()<\/code> is used in this browser, the native implementation will not be used but the a JavaScript implementation using Canvas.\u00a0\u00a0 cssSandpaper will be updated to use the Firefox native version in a future release.<\/p>\n<h4 style=\"font-size: 1em;\">Examples<\/h4>\n<ul>\n<li><a href=\"\/tests\/cssSandpaper\/gradientTest.html\">Gradients Example Page<\/a><\/li>\n<\/ul>\n<\/div>\n<h3>opacity<\/h3>\n<div class=\"steps\">\n<p><!-- Begin steps --><\/p>\n<h4 class=\"first\">Description<\/h4>\n<p>Sets the opacity level of a block of HTML<\/p>\n<h4>Syntax<\/h4>\n<blockquote class=\"code\">\n<pre>#container {\r\n   opacity:  <em>&lt;opacity-level;<\/em>;\r\n}<\/pre>\n<\/blockquote>\n<p>where <em>&lt;opacity-level&gt;<\/em> is a number between 0 and 1.<\/p>\n<h4>Examples<\/h4>\n<p><a href=\"\/tests\/cssSandpaper\/opacityTest.html\">Opacity Test<\/a><\/p>\n<\/div>\n<h3>RGBA, HSL and HSLA colorspaces<\/h3>\n<div class=\"steps\">\n<p><!-- Begin steps --><\/p>\n<h4 class=\"first\">Description<\/h4>\n<p>RGBA allows alpha channel support to the RGB colorspace.  HSL is an alternative, easy to use, human friendly<br \/>\ncolor-space. HSLA allows alpha channel support to the HSL colorspace.<\/p>\n<h4>Syntax<\/h4>\n<blockquote class=\"code\">\n<pre>#container1 {\r\n   background: rgba(32, 45, 230, 0.5);\r\n}\r\n\r\n#container2 {\r\n   background: hsl(120, 50%, 50%);\r\n}\r\n\r\n#container3 {\r\n   background: hsla(270, 100%, 50%, 0.4);\r\n}\r\n<\/pre>\n<\/blockquote>\n<p>More information about these colorspaces can be found in the User Agent Man articles <a href=\"\/blog\/2010\/05\/06\/csssandpaper-now-supports-transform-translate-and-rgba-gradients\/\">cssSandpaper Now Supports <code>transform: translate()<\/code> and <code>rgba()<\/code> Gradients<\/a> and <a href=\"\/blog\/2010\/08\/28\/coding-colors-easily-using-css3-hsl-notation\/\" rel=\"next\">Coding Colors Easily Using CSS3 <code>hsl()<\/code> Notation<\/a>\n<\/div>\n<h4>Examples<\/h4>\n<p><a name=\"domProperties\"><\/a><\/p>\n<h2><a name=\"domProperties\"><\/a><\/h2>\n<p>Developers can use cssSandpaper to manipulate <code>transform<\/code>, <code>opacity<\/code>, <code>box-shadow<\/code>,  and <code>background<\/code> gradients, using <code>cssSandpaper.setOpacity()<\/code>, <code>cssSandpaper.setBoxShadow()<\/code> and <code>cssSandpaper.setGradient()<\/code> 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:<\/p>\n<blockquote class=\"code\">\n<pre>    cssSandpaper.setTransform(node, \"rotate(25deg) scale(2, 2) skew(20deg, 20deg)\");\r\n    cssSandpaper.setOpacity(node, 0.3);\r\n    cssSandpaper.setBoxShadow(node, \"10px 10px 5px #ffcccc\");\r\n    cssSandpaper.setGradient(node, \"-sand-gradient(linear, center top, center bottom, from(#0000ff), to(#ff0000));\")<\/pre>\n<\/blockquote>\n<h2>Known Issues<\/h2>\n<ul>\n<li>Please note that <strong>cssSandpaper cannot load embedded stylesheets when the page is not on a web server in all browsers.<\/strong>  This is because IE (and Chrome it seems) cannot use <code>XMLHttpRequest<\/code> object with the <code>file:<\/code> protocol.  Thanks to Seth Scoville for pointing this out.<\/li>\n<li>Note also that <strong>all stylesheet <code>link<\/code> tags must point to URLs on the same hostname that store cssSandpaper<\/strong> (i.e. both cssSandpaper and all your stylesheets must be served off the same domain).  If there are stylesheets that are on a different domain that don&#8217;t contain any cssSandpaper styles, you can keep them where they are by setting the <code>link<\/code> tag&#8217;s <code>class<\/code> attribute to <code>cssSandpaper-noIndex<\/code>.<\/li>\n<li>Currently, <strong>when a user changes the font-size in IE, the layout gets a little messed up<\/strong>.  This will be fixed in a future release.<\/li>\n<li><strong>In IE, having a transparent background or a background with an alpha channel seems to result in an ugly pixely block.<\/strong>  This seems like it may be a limitation of IE&#8217;s CSS filters and there may not be a workaround available.  <strike>If one does come up, I&#8217;ll definitely update (and if anyone smarter than me finds one, I would be very grateful if you would give me a few pointers ;-).<\/strike> It is now possible to override this behavior by using the <code>-sand-chroma-override<\/code> CSS property.  More details on how to use this can be seen by looking at my article on <a href=\"https:\/\/www.useragentman.com\/blog\/2011\/06\/29\/full-css3-text-shadows-even-in-ie\/\">Full CSS3 Text-Shadows &#8211; Even In IE<\/a>.   Thanks to Robert Momary for pointing this out.<\/li>\n<li><strong>Some copies of Opera 10.5 have problems running the script. <\/strong> It is unknown why, but it seems that Opera 11 and greater don&#8217;t have this issue.<\/li>\n<\/ul>\n<h2>Future Work<\/h2>\n<p>cssSandpaper is a living, active project.\u00a0 I intend to support more CSS3 properties as time goes on, as well as fix bugs that I or others come across.<\/p>\n<p>Any feedback is welcome, either as a comment on this page or emailing the address in the top left corner.<\/p>\n<h2>Acknowledgments<\/h2>\n<p>I would like to thank Weston Ruter for his <a href=\"http:\/\/weston.ruter.net\/projects\/css-gradients-via-canvas\/\">CSS Gradients in Canvas<\/a> 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  <a href=\"www.jcoglan.com\/\">James Coglan<\/a> for building  <a href=\"http:\/\/sylvester.jcoglan.com\/\">Sylvester<\/a> so I didn&#8217;t have to.<\/p>\n<h2>Downloads<\/h2>\n<p><a class=\"exampleLink\" href=\"https:\/\/github.com\/zoltan-dulac\/cssSandpaper\">Get the latest version of cssSandpaper from GitHub.<\/a><\/p>\n<p>(Thanks for Lemaire Adrien for pointing out a script tag error in some of the examples within the earlier 1.1 beta 1 release).<\/p>\n<div id=\"_mcePaste\" style=\"position: absolute; left: -10000px; top: 304px; width: 1px; height: 1px; overflow: hidden;\">\n<pre id=\"line1\"> &lt;<span class=\"start-tag\">a<\/span><span class=\"attribute-name\"> href<\/span><span>=\"<\/span><a href=\"view-source:http:\/\/reference.sitepoint.com\/css\/vendorspecific\">http:\/\/reference.sitepoint.com\/css\/vendorspecific<\/a><span>\"<\/span>&gt;vendor-specific prefix&lt;\/<span class=\"end-tag\">a<\/span>&gt; &lt;<span class=\"start-tag\">code<\/span>&gt;-sand-&lt;\/<span class=\"end-tag\">code<\/span>&gt;<\/pre>\n<\/div>\n","protected":false},"excerpt":{"rendered":"<p>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.\u00a0 This script is not only useful for developers who want to support CSS3 in IE (which doesn&#8217;t support it in IE natively) but in other browsers [&hellip;]<\/p>\n","protected":false},"author":2,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"open","ping_status":"open","template":"","meta":{"footnotes":""},"class_list":["post-951","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"http:\/\/www.useragentman.com\/blog\/wp-json\/wp\/v2\/pages\/951","targetHints":{"allow":["GET"]}}],"collection":[{"href":"http:\/\/www.useragentman.com\/blog\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"http:\/\/www.useragentman.com\/blog\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"http:\/\/www.useragentman.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"http:\/\/www.useragentman.com\/blog\/wp-json\/wp\/v2\/comments?post=951"}],"version-history":[{"count":78,"href":"http:\/\/www.useragentman.com\/blog\/wp-json\/wp\/v2\/pages\/951\/revisions"}],"predecessor-version":[{"id":1028,"href":"http:\/\/www.useragentman.com\/blog\/wp-json\/wp\/v2\/pages\/951\/revisions\/1028"}],"wp:attachment":[{"href":"http:\/\/www.useragentman.com\/blog\/wp-json\/wp\/v2\/media?parent=951"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}