Q
Version: 0.12.2
Source on Github

CSS3 Pie

Installing

CSS PIE is a javascript library that enhances Internet Explorer to render many modern CSS3 capabilities wherever possible. To install:

compass install compass/pie

This will install an example stylesheet and a PIE.htc behavior file that must be loaded into your pages for IE. This file must be delivered with the following mime-type:

Content-Type: text/x-component

Conventions

The example stylesheet will walk you through setting up your project with css3pie support.

Properties Supported

The following css3 properties are supported:

  • border-radius
  • box-shadow
  • border-image
  • background (in the form of -pie-background, use the background mixin)

Additionally, PIE supports the following CSS3 features:

  • rgba color values
  • linear gradients in backgrounds

Full Documentation on Supported Properties

Caveats

  1. PIE only understands shortcut properties, long-hand properties don't work because the code, in order to be fast, does not attempt to resolve the stylesheet cascade and so it cannot determine which order to apply the long-hand properties.
  2. Each element that has a PIE behavior attached adds about 10ms to the page render time. Moderation is recommended.
  3. PIE generates content that contains the css3 graphical elements. It has to insert this content into your page and so it needs a little help from you. You have two choices:
    1. You can make your element position: relative.
    2. You can give your element a z-index. If you do this you should also give apply a z-index to an ancestor element that comes before or itself has a background. The compass mixins below and the example stylesheet will help get you set up.

Best Practices

It is suggested that you use Sass's @extend directive to mark elements as PIE elements. The example stylesheet you get when you install compass/pie into your project will walk you through the process of setting that up.

Notes

  • For more information see the css3pie website.
  • CSS PIE is written by and copyright to: Jason Johnston
  • Compass is using css3pie version 1.0-beta3. It can be upgraded by downloading a new behavior file and replacing the one that comes with compass.

This file can be imported using: @import "compass/css3/pie"

Configurable Variables help

false

It is recommended that you use Sass's @extend directive to apply the behavior to your PIE elements. To assist you, Compass provides this variable. When set, it will cause the @include pie mixin to extend this class. The class name you provide should not include the ..

relative

The default approach to using PIE. Can be one of:

  • relative (default)
  • z-index
  • none

stylesheet-url("PIE.htc")

The location of your PIE behavior file This should be root-relative to your web server relative assets don't work. It is recommended that you set this yourself.

Constants

true

Mixins

view source

=pie-container($z-index: 0, $position: relative)
  z-index: $z-index
  position: $position
@mixin pie-container($z-index: 0, $position: relative) {
  z-index: $z-index;
  position: $position;
}

When using the z-index approach, the first ancestor of the PIE element at or before the container's opaque background should have a z-index set as well to ensure propert z-index stacking.

The $position argument must be some non-static value (absolute, relative, etc.)

view source

=pie-element($approach: $pie-default-approach, $z-index: 0)
  behavior: $pie-behavior
  @if $approach == relative
    position: relative
  @else if $approach == z-index
    z-index: $z-index
@mixin pie-element($approach: $pie-default-approach, $z-index: 0) {
  behavior: $pie-behavior;
  @if $approach == relative {
    position: relative;
  }
  @else if $approach == z-index {
    z-index: $z-index;
  }
}

PIE elements must have this behavior attached to them. IE is broken -- it doesn't think of behavior urls as relative to the stylesheet. It considers them relative to the webpage. As a result, you cannot reliably use compass's relative_assets with PIE.

  • $approach - one of: relative, z-index, or none
  • $z-index - when using the z-index approach, this
             is the z-index that is applied.
    
view source

=pie($base-class: $pie-base-class)
  @if $base-class
    @extend .#{$base-class}
  @else
    +pie-element
@mixin pie($base-class: $pie-base-class) {
  @if $base-class {
    @extend .#{$base-class};
  }
  @else {
    @include pie-element;
  }
}

a smart mixin that knows to extend or include pie-element according to your stylesheet's configuration variables.

view source

=pie-watch-ancestors($n)
  -pie-watch-ancestors: $n
@mixin pie-watch-ancestors($n) {
  -pie-watch-ancestors: $n;
}

Watch $n levels of ancestors for changes to their class attribute So that cascading styles will work correctly on the PIE element.