This repository has been archived by the owner on Apr 20, 2023. It is now read-only.
/
known-issues.html
205 lines (140 loc) · 11 KB
/
known-issues.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
<!DOCTYPE html>
<html>
<head>
<meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
<title>PIE Documentation: Known Issues</title>
</head>
<body>
<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="/documentation/supported-css3-features/">supported CSS3 features</a>, and also
our <a href="http://github.com/lojjic/PIE/issues">issue tracking system</a>.</p>
<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>
<li><a href="#zoom">Browser zooming</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><css3-container/></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
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>
<p>However, this does not work so well when the target element is position:static, because static elements do not
participate in z-index stacking. The only way to make our position:absolute css3 element go behind it is to give
it <code>z-index:-1</code>. Unfortunately, this has a bad side-effect: not only will the css3 element go behind the
target element, it will also go <em>behind the background of any ancestor element(s) which are themselves position:static.</em>
This leads to situations in which PIE creates the VML rendering correctly but it disappears behind a parent element's
background.</p>
<p>The only way I know of to work around this is to either:</p>
<ol>
<li>make the target element position:relative, or</li>
<li>make the ancestor element position:relative and give it a z-index.</li>
</ol>
<p>Both of these workarounds can have potential unwanted side-effects in terms of child element positioning and
z-index stacking. PIE could easily force one or the other itself, but:</p>
<ol>
<li>One or the other may be more appropriate depending on the particular situation, so the CSS author needs to
be able to control which one gets chosen.</li>
<li>Forcing position:relative outside of the CSS would put IE out of sync with other browsers, leading to
confusing inconsistencies.</li>
</ol>
<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 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
the URL has to either be:</p>
<ol>
<li>Absolute from the domain root — this makes the CSS not easily moveable between directories — or,</li>
<li>Relative to the HTML document — this makes the CSS not easily reusable between different HTML files.</li>
</ol>
<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
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
those URLs relative to the CSS file in which they appear. It resolves them instead relative to the JavaScript
execution context, which is the location of the source HTML document.</p>
<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
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
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
to keep file size small and avoid tedious repetition.</p>
<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
<a href="http://www.satzansatz.de/cssd/onhavinglayout.html#rev">unwanted consequences</a>.</p>
<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 <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
changes to the spec will occur. Other things, such as gradients, are relatively new to the specs and are more likely
to change in future drafts.</p>
<p>Fortunately, this threat of future change is not as much of a problem when using PIE as it is when writing
for other browsers. The reason is that the CSS author, by deploying PIE, essentially has control over the user agent.
You know that when you deploy a certain version of PIE, all IE users will experience the same parsing and rendering
behavior. You don't have to worry that some users will be using an old version which has more bugs, or that users will
have a newer version in the future which has different behavior you can't plan for. You can safely depend on the
behavior of the exact PIE version you deploy, indefinitely into the future.</p>
<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>
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 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>
<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>
<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
distribution files a PHP script called PIE.php; this script simply serves up the PIE.htc file using the correct
content-type header. To use it, simply make sure both PIE.php and PIE.htc are in the same directory, and then in your
CSS point the behavior to the PHP file instead:</p>
<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>
<p>If this limitation is a dealbreaker for you, you may be able to use the alternate
<a href="/documentation/pie-js/">PIE.js</a> approach to get around it.</p>
<h2 id="elements">Problems on certain element types</h2>
<p>PIE does not currently work when applied to the <body> or <html> elements. Try using a wrapper div
around the body contents and applying your CSS3 styles and PIE.htc to it instead.</p>
<p>Avoid using PIE on <fieldset> elements, as it does not properly handle rendering of the <legend>.</p>
<p>Also, element types that cannot accept children (e.g. <input> and <img>) will fail or throw errors
if you apply styles that use relative length units such as em or ex. Stick to using px units for these elements.</p>
<h2 id="zoom">Browser Zooming</h2>
<p>When the user uses the browser zoom function (available in IE7 and up), PIE does not currently scale any
background images it manages to match. This can cause things to look broken at zoom levels other than 100%,
if your background images are dependent on sizing (e.g. sprite images).</p>
<!-- noformat off -->
</body>
</html>