Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Documentation updates to sync with site and recent changes

  • Loading branch information...
commit ee110db893c56b437969fccedf3ecb61846208e9 1 parent 119c8d4
Jason Johnston authored
View
122 documentation/about.html
@@ -11,105 +11,51 @@
<h1>About PIE</h1>
-<h2>What is PIE?</h2>
-<p>PIE is a utility for Internet Explorer (currently versions 6-8) which gives it the ability to parse
-and render a number of the most useful CSS3 properties.</p>
+<!-- noformat on -->
-<h2>How does it work?</h2>
-<p>PIE is implemented as an attached behavior; in your CSS, you simply specify:</p>
-<pre><code>behavior: url(PIE.htc);</code></pre>
-<p>Once the behavior is attached, it looks for any of the supported CSS3 properties which might be attached to the
-target element, parses those properties, and renders them on the page.</p>
+<p>CSS Level 3 brings with it some incredibly powerful styling features. Rounded corners, soft drop shadows, gradient fills, and so on. These are the kinds of elements our designer friends love to use because they make for attractive sites, but are difficult and time-consuming to implement, involving complex sprite images, extra non-semantic markup, large JavaScript libraries, and other lovely hacks.</p>
+<p>CSS3 promises to do away with all that! But as we all know, due to Internet Explorer's lack of support for any of these features, <strong>we must be patient and refrain from using them</strong>, and make do with the same old tedious techniques for the foreseeable future.</p>
+
+<p><strong>Or must we?</strong></p>
+
+<p>PIE stands for Progressive Internet Explorer. It is an IE attached behavior which, when applied to an element, allows IE to recognize and display a number of CSS3 properties. Consider, if you will, the following CSS:</p>
+
+<pre><code>#myElement {
+ background: #EEE;
+ padding: 2em;
+ -moz-border-radius: 1em;
+ -webkit-border-radius: 1em;
+ border-radius: 1em;
+}</code></pre>
+
+<p>This results in a box with nicely rounded corners in any of today's modern browsers, except of course for IE 6, 7, or 8, which all display a square box. However, add the following single rule to that CSS:</p>
+
+<pre><code>#myElement {
+ ...
+ behavior: url(PIE.htc);
+}</code></pre>
+
+<p>Now the exact same rounded corners appear in IE! That's all there is to it. No, really, I mean it.</p>
+
+<p>PIE currently has full or partial support for the following CSS3 features:</p>
-<h2>What CSS3 properties are currently supported?</h2>
-<p>PIE currently has full or partial support for:</p>
<ul>
<li>border-radius</li>
<li>box-shadow</li>
<li>border-image</li>
<li>multiple background images</li>
- <li>linear-gradient background images</li>
+ <li>linear-gradient as background image</li>
</ul>
-<p>You can find detailed information about the levels of support in the <a href="properties.html">Supported CSS3
-Properties and Values</a> documentation.</p>
-
-
-<h2>How large is it?</h2>
-<p>The .htc behavior file is 28K. With gzip compression, it is 12K. (You do gzip your content, right?)</p>
-<p>It's pretty easy to save at least as much as that by using CSS3 instead of all the extra images, markup, and CSS
-you'd have to use otherwise. Also, it's important to note that the behavior file is only downloaded by IE, so in other
-browsers which support these CSS3 features natively, that's pure win.</p>
-
-
-<h2>What are the goals of the project?</h2>
-<p>Even though today's advanced browsers are starting to implement decent levels of CSS3 support, it will still be
-years before Web authors can start using these CSS3 features in widespread deployment. The main reason is, of course,
-that Internet Explorer does not yet implement any of these features, has a majority market share, and has a notoriously
-slow upgrade cycle among its users. IE9 promises to start implementing some CSS3, but like it or not it will still
-likely be years before IE8 and below shrink to a negligible percentage of users.</p>
-<p>PIE aims to drastically shorten that timeframe, by implementing a simple shim to make CSS3 "just work" in IE. Our
-goals are:</p>
-<ol>
- <li>
- <h3>Be simple to use</h3>
- <p>Applying PIE is extremely simple; in many cases the only thing you have to do is add the behavior property
- to your CSS.</p>
- </li>
- <li>
- <h3>Be a CSS-only solution</h3>
- <p>Many of the current solutions for implementing CSS3 features like border-radius are implemented as
- JavaScript libraries and require the author to write JavaScript to invoke them. That is less than ideal
- because it requires the CSS author to also know how to write JS, and it makes development slower and less
- maintainable because your styling code is scattered between CSS and JS files. PIE works entirely within the
- stylesheet, so you only write CSS and it's all in a single place.</p>
- </li>
- <li>
- <h3>Be seamless to the CSS author</h3>
- <p>There have been several articles and resources in recent months which show ways that you can make IE
- "mimic" certain CSS3 features, for example using IE filters to fake box-shadow, or jQuery plugins to implement
- rounded corners. The problem with these solutions is that they require a lot of IE-specific code on top of your
- real CSS3, increasing your development time and the size of your CSS files. PIE on the other hand uses your
- CSS3 directly whenever possible; you simply write real CSS3, and PIE handles it seamlessly.</p>
- <p>PIE handles attaching, detaching, and updating automatically without any intervention from the author. This
- means that, unlike some other solutions, PIE does not require you to explicitly initialize elements when they
- are added to or removed from the document via script, and does not require any sort of "update" method to be
- called when an element's position, size, or styles are modified on the fly.</p>
- <p>Another aspect of PIE's seamlessness is that it should be fully compatible with any JavaScript library the
- site author might choose to use. You can create elements and assign CSS3 styles to them in jQuery or YUI or
- MooTools or any other library and PIE will automatically apply itself. Also, PIE's objects are completely
- self-contained except for a single global <code>PIE</code> object, so there's no chance that it will
- override objects or functions from any other JS code.</p>
- </li>
- <li>
- <h3>Be as compliant with the CSS3 specs as possible</h3>
- <p>PIE aims to be a true CSS3 implementation for those features it supports, complying with the current spec
- drafts as closely as possible. The goal is to allow authors to write a single set of CSS3 code and have it
- "just work" between browsers.</p>
- </li>
- <li>
- <h3>Be as performant as possible</h3>
- <p>If it makes the browser feel sluggish (more so than IE normally does, that is) then it's useless. PIE was
- architected with performance in mind from the very beginning:</p>
- <ul>
- <li>Rendering elements are only updated when they need to be.</li>
- <li>CSS property values are only parsed when they have changed.</li>
- <li>Internal objects are created lazily, and cached when appropriate.</li>
- <li>The behavior script is written with file size in mind, and the most advanced JS compression tools
- available are used to minimize the file size, so the initial download is as fast as possible.</li>
- </ul>
- </li>
-</ol>
-
-
-<h2>What sites have used PIE?</h2>
-<p>(todo)</p>
-
-
-<h2>What are the licensing terms?</h2>
-<p>PIE is licensed under the <a href="http://github.com/lojjic/PIE/blob/master/LICENSE">Apache License Version 2.0</a>.</p>
+<p>Other features are under active development.</p>
+
+<p><strong>Want to learn more?</strong> View some live <a href="/demos">demos</a>, read the <a href="/documentation/">documentation</a>, and <a href="/download-latest">download PIE</a> to try it yourself.</p>
+
+<p>PIE is still a young project with big plans. But it's already good enough to save you a <em>lot</em> of time and make your life as a Web developer much easier. Happy CSS3 coding!</p>
+
+<!-- noformat off -->
View
19 documentation/build.html
@@ -3,16 +3,22 @@
<head>
<meta content="text/html; charset=UTF-8" http-equiv="content-type">
- <title>PIE Documentation: Building PIE</title>
+ <title>PIE Documentation: Building PIE From Source</title>
</head>
<body>
-<h1>Building PIE</h1>
+<h1>Building PIE From Source</h1>
-<h2>Prerequisites</h2>
-<p>Building PIE is straightforward. You need the following tools installed:</p>
+
+<!-- noformat on -->
+
+<p>This document describes how you can build PIE from the most recent source code. This is useful if you want to get a feature or bug fix which hasn't yet made it into a release package. It's also necessary if you want to make changes to the code yourself to try and fix a bug or implement a new feature. If you do so, please consider contributing your changes back to the main project so we can all benefit!</p>
+
+<h2 id="prereqs">Prerequisites</h2>
+
+<p>Building PIE is straightforward. You need to have the following tools installed:</p>
<ol>
<li><a href="http://git-scm.com/">Git</a>, if you are going to be checking out the source from the Git repository</li>
@@ -24,7 +30,7 @@
-<h2>Get the source code</h2>
+<h2 id="getsource">Get the source code</h2>
<p>You have two options for getting the source:</p>
@@ -40,7 +46,7 @@
-<h2>Perform the build</h2>
+<h2 id="build">Perform the build</h2>
<p>From the root directory of your local copy of the source code, invoke the following command in the terminal:</p>
@@ -56,6 +62,7 @@
very large so it should not be deployed in production environments.</li>
</ul>
+<!-- noformat off -->
</body>
View
66 documentation/getting-started.html
@@ -0,0 +1,66 @@
+<!DOCTYPE html>
+<html>
+<head>
+
+ <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
+ <title>PIE Documentation: Getting Started</title>
+
+</head>
+<body>
+
+<h1>Getting Started</h1>
+
+
+
+<!-- noformat on -->
+
+<p>The following instructions should get you up and running with PIE in most circumstances. If you run into
+problems along the way, consult our <a href="/documentation/known-issues/">known issues</a> page, or ask
+for help in the <a href="http://css3pie.com/forum">forums</a>.</p>
+
+<h2>Step 1: Download it</h2>
+
+<p><a href="/download-latest">Download the PIE distribution</a> and unzip it somewhere.</p>
+
+<h2>Step 2: Upload it</h2>
+
+<p>Inside the unzipped directory, you will find a file named PIE.htc. This is the behavior file for IE,
+and is what does all the magic. Upload this file to the server where you're going to serve pages using
+CSS3. It doesn't matter where exactly, as long as you know where it is.</p>
+
+<h2>Step 3: Write some CSS3</h2>
+
+<p>Assuming you already have a HTML document, let's say you want to give one of its elements rounded corners.
+Create a CSS rule for that element and give it a border-radius style like so:</p>
+
+<pre><code>#myAwesomeElement {
+ border: 1px solid #999;
+ -webkit-border-radius: 10px;
+ -moz-border-radius: 10px;
+ border-radius: 10px;
+}</code></pre>
+
+<p>(Note the -webkit- and -moz- prefixed versions; these are necessary to make the rounded corners work in
+WebKit and Mozilla-based browsers.)</p>
+
+<h2>Step 4: Apply PIE</h2>
+
+<p>In that same CSS rule, add the following style line:</p>
+
+<pre><code>behavior: url(path/to/PIE.htc);</code></pre>
+
+<p>Of course you will need to adjust the path to match where you uploaded PIE.htc in step 2. <em>Note: this
+path is relative to the HTML file being viewed, not the CSS file it is called from.</em></p>
+
+<h2>Step 5: View it in IE</h2>
+
+<p>If all went well, at this point you should be able to load the page in IE and see the CSS3 rounded corners
+rendered just like other browsers. Now you can play around with some of the other supported CSS3 decorations
+like box-shadow. See the documentation on <a href="/documentation/supported-css3-features/">supported CSS3
+features</a> to see exactly what PIE can do. Have fun!</p>
+
+<!-- noformat off -->
+
+
+</body>
+</html>
View
72 documentation/issues.html → documentation/known-issues.html
@@ -10,15 +10,32 @@
<h1>Known Issues</h1>
+
+
+<!-- noformat on -->
+
<p>This document describes the most common general issues encountered when using PIE. For information regarding bugs
and limitations in the implementations of specific features, see the detailed documentation of the
-<a href="properties.html">supported CSS3 properties and values</a>, and also our issue tracking system [TODO provide link].</p>
+<a href="/documentation/supported-css3-features/">supported CSS3 features</a>, and also
+our <a href="http://github.com/lojjic/PIE/issues">issue tracking system</a>.</p>
-<h2>Problems with z-index</h2>
+<ul>
+ <li><a href="#z-index">Problems with z-index (disappearing backgrounds/borders/shadows)</a></li>
+ <li><a href="#relative-paths">Relative paths</a></li>
+ <li><a href="#shorthand">Shorthand only</a></li>
+ <li><a href="#hasLayout">Problems with hasLayout</a></li>
+ <li><a href="#spec-bugs">Deviations from CSS3 spec</a></li>
+ <li><a href="#content-type">Serving the correct Content-Type</a></li>
+ <li><a href="#x-domain">Same domain limitation</a></li>
+ <li><a href="#elements">Problems on certain elements</a></li>
+</ul>
+
+
+<h2 id="z-index">Problems with z-index (disappearing backgrounds/borders/shadows)</h2>
<p>First, a little background on how PIE renders CSS3 decorations: a single <code>&lt;css3-container/&gt;</code>
element is created which holds all the VML objects. This container element is inserted as a previous sibling to the
-target element, and absolutely positioned at the same coordinates. If the target element is position:absolute or
+target element, and absolutely positioned at the same coordinates. If the target element is position:absolute or
position:relative, then the css3-container element is given the same z-index as the target element, and since it
is a previous sibling in the DOM tree it gets displayed behind, with no possibility of any other element sneaking
in between.</p>
@@ -45,19 +62,20 @@
confusing inconsistencies.</li>
</ol>
-<p>PIE therefore does neither, and it is up to the author to implement either workaround where necessary.</p>
+<p>PIE therefore does neither, and it is up to the author to implement either workaround where necessary. In
+most cases simply adding position:relative to the target element is fine.</p>
-<h2>Relative paths</h2>
+<h2 id="relative-paths">Relative paths</h2>
<p>There are two main issues related to relative paths in CSS:</p>
<h3>The behavior URL</h3>
<p>IE interprets the URL for the <code>behavior</code> property relative to the source HTML document, rather than
-relative to the CSS file like every other CSS property. This makes invoking the PIE behavior inconvenient, because
+relative to the CSS file like every other CSS property. This makes invoking the PIE behavior inconvenient, because
the URL has to either be:</p>
<ol>
@@ -68,7 +86,7 @@
<h3>URLs in PIE-interpreted CSS properties</h3>
<p>PIE does not parse the CSS stylesheets (to do so would be unacceptably slow); it lets IE handle the parsing,
-selector querying, cascading, etc. and then simply asks it for the resulting property values. This means that when
+selector querying, cascading, etc. and then simply asks it for the resulting property values. This means that when
PIE gets a property value, it has no knowledge of the context from which that value originated.</p>
<p>As a result, for properties which contain URL values (such as border-image or -pie-background), PIE cannot resolve
@@ -77,16 +95,16 @@
-<h2>Shorthand only</h2>
+<h2 id="shorthand">Shorthand only</h2>
<p>For all CSS properties which PIE parses, only the shorthand versions of those properties will be recognized.
For example, while <code>border-radius</code> is supported, the individual longhand <code>border-top-left-radius</code>
etc. properties are not.</p>
<p>The reason for this is the same reason URLs are not resolved relative to the CSS file (see above): PIE does not
-have visibility into where each style property comes from. If there is both a shorthand and a longhand
+have visibility into where each style property comes from. If there is both a shorthand and a longhand
property present, PIE cannot determine the order in which the CSS author specified those properties, nor can it
-determine the specificity of the selector for each property. It cannot therefore make an informed decision about
+determine the specificity of the selector for each property. It cannot therefore make an informed decision about
which property should take precedence.</p>
<p>To avoid making dumb guesses, we have opted to only support shorthand properties. Shorthand was chosen over longhand
@@ -94,24 +112,24 @@
-<h2>Problems with hasLayout</h2>
+<h2 id="hasLayout">Problems with hasLayout</h2>
<p>In order to automatically detect element position and dimension changes, PIE has to force
"<a href="http://www.satzansatz.de/cssd/onhavinglayout.html">hasLayout</a>" on the target element (in IE6 and IE7).
It does so by applying the style <code>zoom:1;</code> to the element.</p>
<p>For the most part, doing this has no adverse effect on the rendering of the element. In fact, a lot of times it
-improves the rendering (hasLayout is often used as a hack to work around IE CSS bugs). However, in some cases this has
+improves the rendering (hasLayout is often used as a hack to work around IE CSS bugs). However, in some cases this has
<a href="http://www.satzansatz.de/cssd/onhavinglayout.html#rev">unwanted consequences</a>.</p>
-<h2>Deviations from CSS spec</h2>
+<h2 id="spec-bugs">Deviations from CSS3 spec</h2>
<p>For the properties it supports, PIE attempts to match the syntax parsing and rendering as specified by the current
-CSS3 spec document drafts. Any deviations should be considered defects. If you find a bug, please open a ticket in
-our issue tracking system [TODO provide link]. You can find information about many of the known issues in the
-detailed documentation of <a href="properties.html">supported CSS3 properties and values</a>.</p>
+CSS3 spec document drafts. Any deviations should be considered defects. If you find a bug, please open a ticket in
+our <a href="http://github.com/lojjic/PIE/issues">issue tracking system</a>. You can find information about many of the known issues in the
+detailed documentation of <a href="/documentation/supported-css3-features">supported CSS3 properties and values</a>.</p>
<p>Do keep in mind, however, that the CSS3 specs are still a moving target. Some properties, such as border-radius,
have been around long enough, and have sufficient cross-browser implementation, such that it is unlikely further
@@ -127,14 +145,14 @@
<p>But what happens when the spec changes and PIE hasn't yet been updated to support the new syntax or behavior? Or
what about when there's a bug in PIE that makes it impossible to use the same CSS property for both PIE and other
-browsers? To handle both these cases, any of the supported CSS3 properties can be prefixed with <code>-pie-</code>
+browsers? To handle both these cases, any of the supported CSS3 properties can be prefixed with <code>-pie-</code>
and that will be used in preference to the standard property. So for instance you could specify a <code>box-shadow</code>
value which would be used by other browsers, and then a <code>-pie-box-shadow</code> value which will be used only by
PIE. This is recommended only as a final resort; it's always best to use the standard property if at all possible.</p>
-<h2>Serving the correct Content-Type</h2>
+<h2 id="content-type">Serving the correct Content-Type</h2>
<p>IE requires that HTC behaviors are served up with a content-type header of "text/x-component", otherwise it will
simply ignore the behavior. Many web servers are preconfigured to serve the correct content-type, but others are not.</p>
@@ -142,7 +160,7 @@
<p>If you have problems with the PIE behavior not being applied, check your server configuration and if possible
update it to use the correct content-type. For Apache, you can do this in a .htaccess file:</p>
-<pre><code>AddType text/x-component htc</code></pre>
+<pre><code>AddType text/x-component .htc</code></pre>
<p>If for some reason you are unable to modify the server configuration (e.g. if you are on a shared host which does
not allow custom .htaccess files), then you may also use a wrapper script. For instance, PIE includes in its
@@ -153,6 +171,22 @@
<pre><code>behavior: url(PIE.php);</code></pre>
+<h2 id="x-domain">Same-domain limitation</h2>
+
+<p>IE requires that the PIE.htc behavior file must be in the same domain as the HTML page which uses it. If you try
+to load the behavior from a different domain, you will get an "Access Denied" error.</p>
+<p>Note that the domain must be <em>exactly</em> the same; that means that http://www.foo.com is a different
+domain than http://foo.com.</p>
+
+
+<h2 id="elements">Problems on certain elements</h2>
+
+<p>PIE does not currently work when applied to the &lt;body> or &lt;html> elements. Try using a wrapper div
+around the body contents and applying your CSS3 styles and PIE.htc to it instead.</p>
+
+
+<!-- noformat off -->
+
</body>
</html>
View
89 documentation/pie-js.html
@@ -0,0 +1,89 @@
+<!DOCTYPE html>
+<html>
+<head>
+
+ <meta content="text/html; charset=UTF-8" http-equiv="content-type">
+ <title>PIE Documentation: PIE.js - PIE JavaScript edition</title>
+
+</head>
+<body>
+
+<h1>PIE.js - PIE JavaScript edition</h1>
+
+
+
+<!-- noformat on -->
+
+<p>In addition to the traditional PIE.htc behavior, the distribution now also includes a pure
+JavaScript version of the tool, PIE.js. While the .htc behavior is still the recommended approach
+for most users, the JS version has some advantages that may be a better fit for some users.</p>
+
+
+<h2 id="pros">Advantages of the JS version</h2>
+
+<p>Since it is a normal .js file, PIE.js does not suffer from some of the more annoying limitations
+of the PIE.htc behavior:</p>
+
+<ul>
+ <li>You can load PIE.js from a different domain than the HTML page.</li>
+ <li>You don't have to worry about your server not using the correct Content-type header for the file.</li>
+ <li>Referencing the PIE.js file via a relative path is simpler since you only have to do it once in
+ each HTML page.</li>
+ <li>It is more easily integrated within JavaScript libraries.</li>
+</ul>
+
+
+<h2 id="cons">Disadvantages of the JS version</h2>
+
+<p>Unfortunately there are some significant drawbacks to using PIE.js, which is why the .htc behavior is still
+the recommended approach for most users:</p>
+
+<ul>
+ <li>Invoking it requires writing some JavaScript, which means your styling is scattered between CSS
+ and JS code.</li>
+ <li>The .js file blocks the parsing of the page while it is loading, whereas the .htc file loads asynchronously.</li>
+ <li>You have to wait until the page's DOM has completely loaded before applying PIE.js to elements, whereas
+ the .htc behavior applies itself while the page is still loading. This means the "flash of unstyled content"
+ problem is much greater with PIE.js.</li>
+ <li>PIE.js cannot automatically attach and detach itself from elements which are dynamically added to/removed from
+ the page's DOM, so you have to write code to handle that yourself.</li>
+</ul>
+
+
+<h2 id="usage">Using PIE.js</h2>
+
+<p>If you've decided the above advantages outweigh the disadvantages for you, here's how you go about using PIE.js.</p>
+
+<p><em>Note: this API is currently very simplistic, and will likely be enhanced in the future to make it easier
+to work with, for example allowing the use of CSS selectors to match a set of elements.</em></p>
+
+<ol>
+ <li>Include the PIE.js script in your page:
+ <pre><code>&lt;script type="text/javascript" src="path/to/PIE.js">&lt;/script></code></pre>
+ </li>
+
+ <li>Invoke the <code>PIE.attach(el)</code> function for each element that needs CSS3 styling. Make sure you do this
+ after the page's DOM has been fully loaded. For example, using jQuery:
+ <pre><code>$(function() {
+ $('.rounded').each(function() {
+ PIE.attach(this);
+ });
+});</code></pre>
+ </li>
+</ol>
+
+<p>If you are going to add new elements to the page via JavaScript after the fact, you will have to make sure your
+JS code calls <code>PIE.attach(el)</code> for each new element that needs CSS3 styling. Calling attach for a
+particular element more than once is safe (PIE will ignore the call if the element has already been attached),
+so you don't need to worry about filtering out elements.</p>
+
+<p>Also, if you remove elements from the page that had PIE attached, you will need to call
+<code>PIE.detach(el)</code> to clean up their CSS3 rendering.</p>
+
+
+<!-- noformat off -->
+
+
+
+</body>
+</html>
View
89 documentation/product-comparison.html
@@ -0,0 +1,89 @@
+<!DOCTYPE html>
+<html>
+<head>
+
+ <meta content="text/html; charset=UTF-8" http-equiv="content-type">
+ <title>PIE Documentation: Comparing PIE to Other CSS3 Products</title>
+
+</head>
+<body>
+
+<h1>Comparing PIE to Other CSS3 Products</h1>
+
+
+
+<!-- noformat on -->
+
+<p>PIE is not the first product by far to provide some level of CSS3 support in IE. It can be difficult to tell what the differences are between all the products out there, so I'm going to attempt to cover several of the major ones here, and clarify their similarities and differences with PIE.</p>
+
+<p>An aside: some of these comparisons are based on fairly cursory evaluations of the projects. As a result there may be some inaccuracies. I welcome any corrections, as I want to give each product a fair description.</p>
+
+<ul>
+ <li><a href="#ie7-js">IE7.js</a></li>
+ <li><a href="#selectivizr">Selectivizr</a></li>
+ <li><a href="#eCSStender">eCSStender</a></li>
+ <li><a href="#DD_roundies">DD_roundies</a></li>
+ <li><a href="#curved-corner">border-radius.htc (curved-corner)</a></li>
+ <li><a href="#ie-css3-htc">ie-css3.htc</a></li>
+</ul>
+
+<h2 id="ie7-js">Dean Edwards's <a href="http://code.google.com/p/ie7-js/">IE7.js</a> (and IE8.js, IE9.js)</h2>
+
+<p>This is the granddaddy of all IE shims, and probably the first major attempt at implementing CSS3 features in IE. I'm a big fan of Dean Edwards's work (<a href="http://dean.edwards.name/weblog/2006/03/base/">Base.js</a> is still the most elegant classical inheritance abstraction for JavaScript I've come across) and this is certainly one of his more impressive chunks of code.</p>
+
+<p>It is implemented as a series of drop-in .js scripts, the main focus of which is working around IE layout bugs and implementing advanced selectors. This includes, naturally, several CSS3 selectors. It doesn't currently attempt to implement rendering of any of the CSS3 box decoration properties.</p>
+
+<p>Conversely, PIE doesn't attempt to implement any CSS3 selectors. This means that the two products target completely different aspects of CSS3 with no overlap.</p>
+
+<p>The big downside with IE7.js as I understand it is performance. Because it has to parse all the document's stylesheets, rewrite many aspects of them, and add a bunch of extra elements and classNames to the DOM tree, page loads can feel sluggish. This is the main reason PIE makes no attempt to implement selectors, or anything else such as shorthand/longhand specificity resolution which would require parsing stylesheets. Performance is a primary goal, so I made the tough choice early on to sacrifice some completeness for speed.</p>
+
+<p>A possibility I find intriguing is combining the two libraries so that IE7.js gives you all the advanced selectors, and PIE gives you the advanced box decoration rendering. While I haven't tried this yet, I don't know of any reason it couldn't work splendidly.</p>
+
+<h2 id="selectivizr">Keith Clark's <a href="http://selectivizr.com/">Selectivizr</a></h2>
+
+<p>This project, like IE7.js, implements CSS3 selectors only. It should also be possible to combine this with PIE to get both selectors and box decorations in IE.</p>
+
+<p>One of the more interesting things about this product is that it outsources all its parsing and matching of CSS selectors to a number of other JavaScript libraries. As a result, Selectivizr itself is extremely small. This makes a whole lot of sense if your site, like many or most sites, already include a JavaScript library like jQuery for other functionality; by reusing that code your total file download size can be much smaller.</p>
+
+<h2 id="eCSStender">Aaron Gustafson's <a href="http://ecsstender.org/">eCSStender</a></h2>
+
+<p>Of the products listed here, this is probably the most modular and well-documented from an API point of view. It consists of a "core" which parses the page's stylesheets and invokes one or more modular "extensions" based on conditions such as selector pattern or property name. There are a few extensions available which add some level of support for various features, including @font-face, CSS3 selectors, and CSS3 Backgrounds and Borders.</p>
+
+<p>That last one sounds like it might overlap with PIE somewhat, but alas not really, at least not yet. It appears that the main focus of eCSStender is not implementing advanced features where they are missing, but more just abstracting away some of the differences in how browsers already implement things. The Backgrounds and Borders extension, for example, allows you to just write <code>border-radius</code> in your CSS and it automatically adds the corresponding vendor-prefixed versions. This is definitely handy, but if the browser doesn't already natively support some variant of rounded corners (as IE obviously does not), then it does nothing for you. Similarly, it handles <code>box-shadow</code> and will add an IE shadow filter to try to mimic the shadow in IE, but the filter differs so much from standard box-shadow in rendering that this isn't really useful if precision matters to you.</p>
+
+<p>That said, eCSStender's modular nature should make it very easy to write an extension which would add references to PIE.htc where needed to implement the advanced renderings. This is a very interesting prospect.</p>
+
+<h2 id="DD_roundies">Drew Diller's <a href="http://www.dillerdesign.com/experiment/DD_roundies/">DD_roundies</a></h2>
+
+<p>It's difficult to express how much Drew's work on DD_roundies has influenced and inspired my work on PIE. The whole idea of positioning VML behind elements to mimic box decorations, proof that it could be done reliably and automatically adjust to position and size changes, and even some of the logic for building the rounded box paths, came from seeing DD_roundies in action and studying its source code. There are a lot of similarities between these two products... including, unfortunately, many of the "gotchas".</p>
+
+<p>DD_roundies is implemented as a JavaScript library which you can call to add rounded corners to elements. It isn't just limited to IE, but can also apply the appropriate [-webkit-][-moz-]border-radius CSS properties if so desired. It does handle different radius lengths for each corner, though not different x/y axis radius values.</p>
+
+<p>The main differences between DD_roundies and PIE are:</p>
+<ul>
+ <li>PIE is far more complete feature-wise. It basically handles everything DD_roundies does, but additionally supports non-solid border styles, differing x/y axis radius values, and details of the CSS3 border-radius spec such as how overlapping radii are adjusted. And then it adds in other CSS3 decoration features like box-shadow, multiple backgrounds, border-image, and gradients.</li>
+ <li>They are invoked very differently. DD_roundies is a .js file which requires you to write JavaScript to invoke it. Your radius values and selectors must be passed in that JS function call, which means they are separated from your CSS so you have two places to maintain styling code. PIE on the other hand is a .htc behavior, which is applied directly in your CSS file. It also picks up its target styles from your standard CSS rules, so you don't ever have to write any JavaScript. Both approaches have their strengths and weaknesses, but in my opinion PIE's approach gives a nicer coding experience to CSS authors.</li>
+</ul>
+
+<h2 id="curved-corner">Remiz Rahnas's <a href="http://code.google.com/p/curved-corner/">border-radius.htc</a> aka "curved-corner"</h2>
+
+<p>Like PIE, this project uses a .htc behavior which picks up the target border-radius value directly from the CSS. It also uses a similar approach of positioning VML directly behind the target element.</p>
+
+<p>Unfortunately it is extremely simplistic. It only supports a single border radius value for all corners, doesn't handle rendering background images which are positioned or have repeat values other than 'repeat', and only supports solid border styles. In addition, it doesn't automatically adjust to match position or size changes of target elements, making it difficult to use in dynamically scripted environments.</p>
+
+<p>That said, its simplicity comes with a big advantage: a minuscule file size. If you only require the basic features it provides, then this is probably an excellent choice.</p>
+
+<h2 id="ie-css3-htc">Nick Fetchak's <a href="http://www.fetchak.com/ie-css3/">ie-css3.htc</a></h2>
+
+<p>This project seems nearly identical to border-radius.htc mentioned above (in face Nick gives credit to Remiz on the site), but adds in some support for box-shadow, including blur, matching the rounded box shape. To my knowledge it is the first product to do so (though I had already implemented it in PIE before I found this project online).</p>
+
+<p>The box-shadow seems to work well, but due to the algorithm of IE's blur filter, the rendering for a given blur radius ends up looking quite a bit different between IE and other browsers. I ran into this same issue building PIE, but have made some adjustments to make the rendering much more similar to the standard blur algorithm.</p>
+
+<p>It also has some support for text-shadow, which PIE does not (yet) do at all. This is on the roadmap, but it is a very tricky problem to get text-shadow rendering correctly and adjust to on-the-fly DOM changes, perhaps even impossible.</p>
+
+<!-- noformat off -->
+
+
+
+</body>
+</html>
View
138 documentation/q-and-a.html
@@ -0,0 +1,138 @@
+<!DOCTYPE html>
+<html>
+<head>
+
+ <meta content="text/html; charset=UTF-8" http-equiv="content-type">
+ <title>PIE Documentation: Q &amp; A</title>
+
+</head>
+<body>
+
+<h1>Q &amp; A</h1>
+
+
+<!-- noformat on -->
+
+<h2>What is PIE?</h2>
+<p>PIE is a utility for Internet Explorer (currently versions 6-8) which gives it the ability to parse
+and render a number of the most useful CSS3 properties.</p>
+
+
+<h2>How does it work?</h2>
+<p>PIE is implemented as an attached behavior; in your CSS, you simply specify:</p>
+<pre><code>behavior: url(PIE.htc);</code></pre>
+<p>Once the behavior is attached, it looks for any of the supported CSS3 properties which might be attached to the
+target element, parses those properties, and renders them on the page.</p>
+
+
+<h2>What CSS3 properties are currently supported?</h2>
+<p>PIE currently has full or partial support for:</p>
+<ul>
+ <li>border-radius</li>
+ <li>box-shadow</li>
+ <li>border-image</li>
+ <li>multiple background images</li>
+ <li>linear-gradient background images</li>
+</ul>
+<p>You can find detailed information about the levels of support in the
+<a href="/documentation/supported-css3-features/">Supported CSS3 Properties and Values</a> documentation.</p>
+
+
+<h2>How large is it?</h2>
+<p>The .htc behavior file is 30K. With gzip compression, it is 12K. (You do gzip your content, right?)</p>
+<p>It's pretty easy to save at least as much as that by using CSS3 instead of all the extra images, markup, and CSS
+you'd have to use otherwise, so this is usually a net win in terms of total page weight. Also, it's important to
+note that the behavior file is only downloaded by IE, so in other browsers which support these CSS3 features natively,
+that's pure win.</p>
+
+
+<h2>What are the goals of the project?</h2>
+<p>Even though today's advanced browsers are starting to implement decent levels of CSS3 support, it will still be
+years before Web authors can start using these CSS3 features in widespread deployment. The main reason is, of course,
+that Internet Explorer does not yet implement any of these features, has a majority market share, and has a notoriously
+slow upgrade cycle among its users. IE9 promises to start implementing some CSS3, but like it or not it will still
+likely be years before IE8 and below shrink to a negligible percentage of users.</p>
+<p>PIE aims to drastically shorten that timeframe, by implementing a simple shim to make CSS3 "just work" in IE. Our
+goals are:</p>
+<ol>
+ <li>
+ <h3>Be simple to use</h3>
+ <p>Applying PIE is extremely simple; in many cases the only thing you have to do is add the behavior property
+ to your CSS.</p>
+ </li>
+ <li>
+ <h3>Be a CSS-only solution</h3>
+ <p>Many of the current solutions for implementing CSS3 features like border-radius are implemented as
+ JavaScript libraries and require the author to write JavaScript to invoke them. That is less than ideal
+ because it requires the CSS author to also know how to write JS, and it makes development slower and less
+ maintainable because your styling code is scattered between CSS and JS files. PIE works entirely within the
+ stylesheet, so you only write CSS and it's all in a single place.</p>
+ </li>
+ <li>
+ <h3>Be seamless to the CSS author</h3>
+ <p>There have been several articles and resources in recent months which show ways that you can make IE
+ "mimic" certain CSS3 features, for example using IE filters to fake box-shadow, or jQuery plugins to implement
+ rounded corners. The problem with these solutions is that they require a lot of IE-specific code on top of your
+ real CSS3, increasing your development time and the size of your CSS files. PIE on the other hand uses your
+ CSS3 directly whenever possible; you simply write real CSS3, and PIE handles it seamlessly.</p>
+ <p>PIE handles attaching, detaching, and updating automatically without any intervention from the author. This
+ means that, unlike some other solutions, PIE does not require you to explicitly initialize elements when they
+ are added to or removed from the document via script, and does not require any sort of "update" method to be
+ called when an element's position, size, or styles are modified on the fly.</p>
+ <p>Another aspect of PIE's seamlessness is that it should be fully compatible with any JavaScript library the
+ site author might choose to use. You can create elements and assign CSS3 styles to them in jQuery or YUI or
+ MooTools or any other library and PIE will automatically apply itself. Also, PIE's objects are completely
+ self-contained except for a single global <code>PIE</code> object, so there's no chance that it will
+ override objects or functions from any other JS code.</p>
+ </li>
+ <li>
+ <h3>Be as compliant with the CSS3 specs as possible</h3>
+ <p>PIE aims to be a true CSS3 implementation for those features it supports, complying with the current spec
+ drafts as closely as possible. The goal is to allow authors to write a single set of CSS3 code and have it
+ "just work" between browsers.</p>
+ </li>
+ <li>
+ <h3>Be as performant as possible</h3>
+ <p>If it makes the browser feel sluggish (more so than IE normally does, that is) then it's useless. PIE was
+ architected with performance in mind from the very beginning:</p>
+ <ul>
+ <li>Rendering elements are only updated when they need to be.</li>
+ <li>CSS property values are only parsed when they have changed.</li>
+ <li>Internal objects are created lazily, and cached when appropriate.</li>
+ <li>The behavior script is written with file size in mind, and the most advanced JS compression tools
+ available are used to minimize the file size, so the initial download is as fast as possible.</li>
+ </ul>
+ </li>
+</ol>
+
+
+<h2>What sites have used PIE?</h2>
+<p>Here is just a tiny list of sites using PIE already in production. <a href="/contact/">Tell us about yours!</a></p>
+<ul>
+ <li><a href="http://www.tractionco.com/">Traction</a></li>
+ <li><a href="http://www.tinypie.co.uk/">TinyPie Projects</a></li>
+ <li><a href="http://americanapparel.net">American Apparel</a> (<strong><abbr title="Not safe for work">NSFW</abbr></strong>)</li>
+ <li><a href="http://demo.crowdfavorite.com/carrington-business">Carrington Business WordPress Theme</a></li>
+ <li><a href="http://www.composite.net/">Composite C1 CMS</a></li>
+ <li><a href="http://www.lizardq.com/">LizardQ Panoramic Cameras</a></li>
+ <li><a href="http://mirrorstonecrystals.com/">Mirrorstone Crystals</a></li>
+ <li><a href="http://www.journeyoutreach.org/">Journey Outreach</a></li>
+ <li><a href="https://www.viaprinto.de/">viaprinto</a></li>
+ <li><a href="http://sheffieldismyplanet.co.uk/">Sheffield Is My Planet</a></li>
+</ul>
+
+
+<h2>What are the licensing terms?</h2>
+<p>PIE is licensed under a <a href="http://github.com/lojjic/PIE/blob/master/LICENSE">dual license of Apache License
+Version 2.0 and General Public License (GPL) Version 2</a>.</p>
+<p>While you are welcome to use PIE free of charge, we do ask that you consider making a donation as you are able.
+Development of PIE happens almost exclusively during "free time" on evenings and weekends, so your donations are
+important to help keep this going. Think of the hours of costly, frustrating cross-browser hacking that PIE is saving
+you; if you can donate a small proportion of that it will be greatly appreciated!</p>
+
+<!-- noformat off -->
+
+
+
+</body>
+</html>
View
180 documentation/properties.html → documentation/supported-css3-features.html
@@ -3,24 +3,33 @@
<head>
<meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
- <title>PIE Documentation: Supported CSS3 Properties and Values</title>
+ <title>PIE Documentation: Supported CSS3 Features</title>
</head>
<body>
-<h1>Supported CSS3 properties and values</h1>
+<h1>Supported CSS3 Features</h1>
-<p>The following sections describe in detail the exact levels of support PIE has for certain CSS3 properties.</p>
-<h2>border-radius</h2>
+
+<!-- noformat on -->
+
+<p>The following sections describe in detail the exact levels of support PIE has for certain CSS3 properties
+and value types.</p>
+
+
+
+<h2 id="border-radius">border-radius</h2>
<p>PIE fully supports the border-radius property as defined in the CSS3
Backgrounds and Borders module specification.</p>
-<pre>border-radius: [ &lt;length&gt; | &lt;percentage&gt; ]{1,4} [ / [ &lt;length&gt; | &lt;percentage&gt; ]{1,4} ]?</pre>
+<pre class="long">border-radius: [ &lt;length&gt; | &lt;percentage&gt; ]{1,4} [ / [ &lt;length&gt; | &lt;percentage&gt; ]{1,4} ]?</pre>
<p>Only the shorthand version is supported; the longhand
-border-top-left-radius etc. properties are not.</p>
+border-top-left-radius etc. properties are not. The shorthand syntax does support different radii per corner, though:</p>
+
+<p><code>border-radius: 5px 10px 15px 20px;</code> (top-left, top-right, bottom-right, bottom-left).</p>
<p>The rounded corners are applied to the element's background area
(including solid background colors, background images, and background
@@ -50,22 +59,17 @@
WebKit nightlies and recent Chrome, I think these may now match the
spec and drop the prefix.)</p>
-<h2>box-shadow</h2>
-<p>PIE supports the box-shadow property syntax as of its last
-appearance in the CSS3 Backgrounds and Borders module. It was removed
-from the spec due to, as far as I can tell, some questions around how
-it should behave in conjunction with semi-transparent background
-images. The plan seems to be to add it back in at some point in another
-(perhaps new) CSS3 module, but I have not yet seen that happen.
-Regardless, this is an extremely useful property which has widespread
-support (via prefixed properties) in other browsers, so PIE includes
-support as best it can.</p>
-<pre>box-shadow: none | &lt;shadow&gt; [,&lt;shadow&gt;]*
+<h2 id="box-shadow">box-shadow</h2>
+
+<p>PIE supports the <a href="http://dev.w3.org/csswg/css3-background/#box-shadow">box-shadow property syntax</a>
+as currently defined in the CSS3 Backgrounds &amp; Borders module.</p>
+
+<pre class="long">box-shadow: none | &lt;shadow&gt; [,&lt;shadow&gt;]*
where &lt;shadow&gt; = inset? &amp;&amp; [ &lt;offset-x&gt; &lt;offset-y&gt; &lt;blur-radius&gt;? &lt;spread-radius&gt;? &amp;&amp; &lt;color&gt;? ]</pre>
-<p>Both the (ex-)standard box-shadow property name as well as a custom
+<p>Both the standard box-shadow property name as well as a custom
prefixed -pie-box-shadow property name are recognized; if both are
present the prefixed value will take precedence. It is recommended to
use the non-prefixed property when possible, since there are no known
@@ -89,16 +93,42 @@
<p>See the compatibility chart at the bottom of
<a href="https://developer.mozilla.org/En/CSS/-moz-box-shadow">https://developer.mozilla.org/En/CSS/-moz-box-shadow</a></p>
-<h2>border-image</h2>
+
+
+<h2 id="border-image">border-image</h2>
<p>PIE has preliminary support for the border-image property. This property allows
you to specify an image which gets divided into nine squares which are then drawn as
the corners, sides, and center of the target element. The sides and center will stretch
to match the size of the element.</p>
-<p>TODO syntax, caveats, browser compatibility notes</p>
-
-<h2>-pie-background</h2>
+<p>There are currently several limitations of PIE's implementation, including:</p>
+<ol>
+ <li>It only supports the 'stretch' scheme. I'd like to support the others in the future but performance
+ is a big concern as it seems it will require creating a separate VML shape for each tile.</li>
+ <li>It doesn't support the <a href="http://dev.w3.org/csswg/css3-background/#border-image-outset">outset parameter</a>
+ described in the Backgrounds &amp; Borders module spec, though other browsers don't seem to support
+ that yet either.</li>
+ <li>It doesn't support the <a href="http://dev.w3.org/csswg/css3-background/#border-image-width">width override
+ parameter</a> to the border-image shorthand; it will only use the element's border-width for determining
+ the slice widths (again, support for this in other browsers is spotty too).</li>
+ <li>Related to #3, if the element's <code>border-style</code> is 'none' it will treat that as
+ <code>border-width:0</code>.</li>
+ <li>It requires the 'fill' keyword to be present for the center area to be filled in. This is correct
+ behavior according to the spec but other browsers don't require it and some even fail if 'fill' is
+ present, so it's a bit tricky making it work consistently across browsers.</li>
+ <li>It doesn't hide the element's normal border when border-image is specified. In conjunction with #4
+ above, this means you have to set the border-style to 'solid' (or something other than 'none')
+ <strong>and</strong> set the border-color to transparent.</li>
+ <li>It seems there are on rare occasion rounding errors which cause 1px gaps between slices of the
+ image. I've seen these gaps occur in other browsers too, though.</li>
+</ol>
+
+<p>These issues will be addressed in a future release.</p>
+
+
+
+<h2 id="pie-background">-pie-background</h2>
<p>PIE supports CSS3 multiple background images, linear gradients as
background images, and some of the new CSS3 background aspects such as
@@ -109,25 +139,24 @@
Therefore we use a custom -pie-background property for holding these
values.</p>
-<p>Only the single -pie-background shorthand value is recognized; there
-are no supported corresponding longhand values (e.g.
--pie-background-origin).</p>
+<p>Only the single -pie-background shorthand value is recognized; longhand values (e.g.
+-pie-background-origin) are ignored.</p>
<p>For backward-compatibility with browsers which do not support CSS3
backgrounds, be sure to include appropriate fallbacks. For example:</p>
-<pre>#myElement {
+<pre class="long"><code>#myElement {
background: url(bg-image.png) no-repeat #CCC; /*non-CSS3 browsers will use this*/
- background: url(bg-image.png) no-repeat, -moz-linear-gradient(90deg, #CCC, #EEE); /*gecko*/
- background: url(bg-image.png) no-repeat, -webkit-gradient(linear, left bottom, left top, from(#CCC) to(#EEE)); /*webkit*/
- -pie-background: url(bg-image.png) no-repeat, linear-gradient(90deg, #CCC, #EEE); /*PIE*/
-}</pre>
+ background: url(bg-image.png) no-repeat, -moz-linear-gradient(#CCC, #EEE); /*gecko*/
+ background: url(bg-image.png) no-repeat, -webkit-gradient(linear, 0 0, 0 100%, from(#CCC) to(#EEE)); /*webkit*/
+ background: url(bg-image.png) no-repeat, linear-gradient(#CCC, #EEE); /*future CSS3 browsers*/
+ -pie-background: url(bg-image.png) no-repeat, linear-gradient(#CCC, #EEE); /*PIE*/
+}</code></pre>
<p>While the PIE parser will allow them, the following aspects of the
background shorthand will currently be ignored when rendering:</p>
<ul>
-
<li>background-attachment (will always use 'scroll' even if 'fixed'
or 'local' are specified)</li>
<li>background-size (will always use the image's intrinsic size)</li>
@@ -138,17 +167,18 @@
<p>Support for these items will be added in future versions as possible.</p>
-<p>PNG background images specified using <code>-pie-background</code> will be rendered with
-correct alpha transparency in IE6. (This will also be the case when using just
-the normal <code>background-image</code> property in conjunction with any other property
-which invokes PIE re-rendering of the background, e.g. border-radius or border-image.)</p>
+<p>Note that PNG background images specified using <code>-pie-background</code> will be
+rendered with correct alpha channel transparency in IE6. See the section below regarding
+<a href="#pie-png-fix">PNG alpha transparency</a> for more information.</p>
<p>Notes on other browsers:</p>
<p>Firefox supports multiple backgrounds as of version 3.6. Safari supports them as of version 1.3.
See <a href="https://developer.mozilla.org/en/CSS/Multiple_backgrounds">https://developer.mozilla.org/en/CSS/Multiple_backgrounds</a></p>
-<h2>-pie-watch-ancestors</h2>
+
+
+<h2 id="pie-watch-ancestors">-pie-watch-ancestors</h2>
<p>PIE automatically listens for any attribute or style property
changes on the element to which the behavior is applied. This means
@@ -156,7 +186,7 @@
properties on the fly, those changes will automatically be picked up
and the rendering will be updated to match. For example:</p>
-<pre>/* JS: */
+<pre><code>/* JS: */
myElement.onclick = function() {
this.style.borderRadius = '20px';
};
@@ -165,7 +195,7 @@
#myElement {
behavior: url(PIE.htc);
border-radius: 10px;
-}</pre>
+}</code></pre>
<p>Assuming myElement has the PIE.htc behavior attached to it, the
above code will work as expected without any extra effort from the
@@ -178,7 +208,7 @@
corresponding to those class names be maintained in the CSS. So
reworking the above example:</p>
-<pre>/* JS: */
+<pre><code>/* JS: */
myElement.onclick = function() {
this.className += ' poked';
}
@@ -190,7 +220,7 @@
}
#myElement.poked {
border-radius: 20px;
-}</pre>
+}</code></pre>
<p>Again, since the className is being changed on the element to which
the behavior is applied, PIE will automatically be notified of the
@@ -199,7 +229,7 @@
<p>However, what if the className is changed not on the element itself
but on one of its ancestors?</p>
-<pre>/* JS: */
+<pre><code>/* JS: */
myElement.onclick = function() {
this.parentNode.className += ' poked';
}
@@ -211,7 +241,7 @@
}
.poked #myElement {
border-radius: 20px;
-}</pre>
+}</code></pre>
<p>This is a very common pattern which allows a lot of flexibility.
However, in this case, PIE will not be automatically notified of the
@@ -222,7 +252,7 @@
usage. So instead, we have introduced a custom CSS property which
allows authors to tell PIE that certain ancestors should be watched:</p>
-<pre>/* JS: */
+<pre><code>/* JS: */
myElement.onclick = function() {
this.parentNode.className += ' poked';
}
@@ -235,7 +265,7 @@
}
.poked #myElement {
border-radius: 20px;
-}</pre>
+}</code></pre>
<p>This tells PIE that it should watch for changes on ancestors one
level up from the element. It will attach the propertychange listener
@@ -243,7 +273,9 @@
className gets changed, and update the rendering correctly.
</p>
-<h2>rgba color values</h2>
+
+
+<h2 id="rgba">rgba color values</h2>
<p>PIE parses RGBA color values wherever they are allowed. However it
is only able to successfully render their opacity value in a few
@@ -252,18 +284,20 @@
the opacity will be rendered correctly:</p>
<ul>
- <li>The solid background-color as specified in the -pie-background property</li>
- <li>The color value of box-shadow</li>
+ <li>The solid background-color as specified in the -pie-background property.</li>
+ <li>The color value of box-shadow, if the shadow has no blur.</li>
</ul>
-<h2>gradients</h2>
+
+
+<h2 id="gradients">gradients</h2>
<p>PIE currently supports linear-gradient image values when used in the
-pie-background property. Use in any contexts other than the background
are not supported. The supported syntax matches that of the current
CSS3 Image Values module.</p>
-<pre>linear-gradient([&lt;bg-position&gt; || &lt;angle&gt;,]? &lt;color-stop&gt;, &lt;color-stop&gt;[, &lt;color-stop&gt;]*);</pre>
+<pre class="long">linear-gradient([&lt;bg-position&gt; || &lt;angle&gt;,]? &lt;color-stop&gt;, &lt;color-stop&gt;[, &lt;color-stop&gt;]*);</pre>
<p>Currently all color stops are rendered fully opaque, even if
specifying an rgba color value. This is due to a limitation in VML's
@@ -281,12 +315,52 @@
<p>Notes on other browsers:</p>
<p>WebKit's gradient syntax is drastically different than that of the
-CSS3 spec. See the Safari documentation for their syntax:
-<a href="http://developer.apple.com/safari/library/documentation/InternetWeb/Conceptual/SafariVisualEffectsProgGuide/Gradients/Gradients.html">http://developer.apple.com/safari/library/documentation/InternetWeb/Conceptual/SafariVisualEffectsProgGuide/Gradients/Gradients.html</a></p>
+CSS3 spec. See the
+<a href="http://developer.apple.com/safari/library/documentation/InternetWeb/Conceptual/SafariVisualEffectsProgGuide/Gradients/Gradients.html">Safari documentation</a> for their syntax</p>
<p>Mozilla only supports gradients (via the -moz-linear-gradient
-property) as of Firefox 3.6.</p>
+function) as of Firefox 3.6.</p>
<p>Opera currently has no support for CSS gradients.</p>
-</body></html>
+
+
+<h2 id="pie-png-fix">PNG alpha transparency and -pie-png-fix</h2>
+
+<p>A nice side-effect of PIE's use of VML for rendering is that it causes PNG images
+with alpha channel transparency to be correctly displayed in IE6 when they are rendered
+by PIE's engine. This includes:</p>
+<ul>
+ <li>Background images specified using the <a href="#pie-background">-pie-background</a> property</li>
+ <li>Background images specified using the standard <code>background-image</code> style, when used
+ in conjunction with other CSS3 properties that trigger re-rendering of the background
+ (border-radius, border-image)</li>
+ <li>&lt;img> elements that have border-radius applied</li>
+</ul>
+
+<p>Sometimes you might want the benefit of the fixed PNG transparency, on elements that do not meet
+the criteria above. In that case, you can add the custom property <code>-pie-png-fix: true;</code> to
+force re-rendering of the background-image or &lt;img>. (The PIE.htc behavior must also be
+attached to the element.)</p>
+
+
+
+<h2 id="pie-lazy-init">Lazy Initialization</h2>
+
+<p>While PIE has been optimized for speed, there is still a small cost in rendering performance for each element
+it is applied to. When you have dozens or hundreds of elements on your page with CSS3 styles applied, this
+can add up to a noticeable rendering delay.</p>
+
+<p>When you have that many elements on one page, chances are that only a small number of them are visible
+in the browser viewport initially, as viewing the rest would require scrolling. PIE allows an optional
+optimization for this case: if you apply the custom <code>-pie-lazy-init:true;</code> property to elements
+PIE will delay the initialization of their CSS3 rendering until they are scrolled into the viewport. This
+keeps the initial page load snappy without severely limiting the number of elements you can render.</p>
+
+
+<!-- noformat off -->
+
+
+
+</body>
+</html>
View
2  site/pie-wp-theme/header/header-default.php
@@ -79,7 +79,7 @@
<![if lt IE 8]><nav id="mainNav"><![endif]>
<?php wp_nav_menu( array('menu' => 'Main Menu', 'container' => null )); ?>
- <p><a class="outbound" href="http://github.com/downloads/lojjic/PIE/PIE-1.0beta2.zip"><strong>Download</strong> <span class="version">Version 1.0beta2</span></a></p>
+ <p><a class="outbound" href="/download-latest"><strong>Download</strong> <span class="version">Version 1.0beta2</span></a></p>
<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_s-xclick">
Please sign in to comment.
Something went wrong with that request. Please try again.