Summary


Documentation

Basics

In this chapter, we will teach you the easiest and securest way to use PNGHack.

  1. First of all, you'll have to set up a spacer.gif in your images directory

    Your websites folder should look like this :

    index.html - /images/spacer.gif - /scripts/pnghack.js

    You can also check the advanced functionalities to set up the spacer.gif

  2. Now you'll have to target all your elements you want to hack

    To do so, put the class "hack-png" on every element you want to hack, for example :

    <img src="my-image.png" alt="my image" class="hack-png" />
    <input type="image" src="submit.png" alt="Submit" class="submit hack-png" />

    As you can see, PNGhack supports multiple classes and any element

  3. Let's write our javascript :

    <script type="text/javascript" src="scripts/pnghack.js"></script>
    <script type="text/javascript">
    ph = new PNGHack();
    window.onload = function() {
    ph.hackClass();
    };
    </script>

    That's it ! You PNG's are now hacked !

    Take a look at advanced functionalities to master the PNG elements on your website :)

Back to top


Advanced functionalities

Writing a PNGHack object

PNGhack() Class

Syntax :
object = new PNGHack([spacer]);

Parameters :
  • spacer : Defines the local directory or hosted directory for spacer.gif

Methods

hackClass() Method

Syntax :
object.hackClass({ [elm:sTag] [, src:sSrc] [, scope:DOMNode] });

Parameters :
  • elm : Defines the tagname of an element type you want to hack, if not specified it applies to all elements.
  • src : Defines the source attribute such as src or data, if not specified it uses the src property.
  • scope : Defines a DOM node as starting point to apply the hack to all his children, if not specified it applies to all the document

The hackClass() method is bounded to the "hack-png" class. It permits you to target the elements you want to hack and to avoid flickering while the page loads


hackExtension() Method

Syntax :
object.hackExtension({ [elm:sTag] [, src:sSrc] [, ext:RegExp] [, scope:DOMNode] });

Parameters :
  • elm : Defines the tagname of an element type you want to hack, if not specified it applies to all elements.
  • src : Defines the source attribute such as src or data, if not specified it uses the src property.
  • ext : Defines the extension of your elements, it allows you to use Regular Expressions to target dynamic created elements, if not specified it targets all files ending with PNG.
  • scope : Defines a DOM node as starting point to apply the hack to all his children, if not specified it applies to all the document

The hackExtension() method permits you to target all elements ending with a specified extension, .PNG by default.
Caution : The ext parameter is NOT case-sensitive !


hackElement() Method

Syntax :
object.hackElement({ elm:DOMElement [, src:sSrc] });

Parameters :
  • elm : Required. Defines the DOM element you want to hack.
  • src : Defines the source attribute such as src or data, if not specified it uses the src property.

The hackElement() method permits you to hack individual DOM elements.

Back to top


Collections

elements Collection

Syntax :
object.elements;

Remarks :

The elements collection returns an array of all hacked elements.
It is readable and writable.

Back to top


Properties

checkIE Property

Syntax :
object.checkIE = [RegExp];

Possible values :
  • 'MSIE 5\.5|MSIE 6' : Default, permits IE 5.5 and 6
  • false : Doesn't check the browser
  • Any regular expression

This property works with regular expressions and let you define the IE version that you'd like to check


remotehost Property

Syntax :
object.remotehost = [value];

Possible values :
  • null : Default, 'rescue mode', tries to use the local spacer.gif, if it fails it uses the google hosted spacer.gif
  • false : Only use the local or defined spacer.gif
  • true : Only use the google hosted spacer.gif

This property lets you handle the spacer.gif hosting component

Back to top


pngsrc DOM property

As explained in Further explanations, the src value of your hacked element is changed into a spacer.gif. So to recover your original src, the hack writes a new property called "pngsrc".

You can retrieve (read) the value like every other property of your element by that way :

yourElement.pngsrc;

And also change (write) the image like that :

yourElement.src = 'newImage.png'; ph.hackElement(yourElement);

Enjoyable right ?

Back to top


Further explanations

How does it work

While other libraries affect the DOM structure by replacing images or other type of elements by new elements, this one doesn't. Although it still uses the existing element to improve cross-browser compatibility, easier maintenance and further developments inside the website.

The only change is applied to the src or the specified property what would be replaced by a spacer.gif, while the original src would be transformed into a DirectX AlphaImageLoader Filter. Finally, the hack back ups the original src by applying a 'pngsrc' property to the image, that you'll be able to read !

Back to top


Namespaces

We didn't want to limit developers to HTML or XHTML elements.
PNGhack is dedicated to handle with 32 bits PNG formats, without worrying about namespaces or elements.
So you'll also be able to hack VML image elements, deprecated elements, or whatever ...
You are the one who handles the DOM.

Back to top


Source attributes

Since we don't want to force developers to only hack pre-defined elements like img, or input in HTML, we also increased the support to other source attributes.
By that way, you can for example invent your own element and tell PNGHack to use "data" instead of "src".
<myelement data="my-image.png" />

Back to top


Browser check

While using HTML conditional comments can some times be painful, we decided to include our own Internet Explorer version checker.
By that way you'll be able to specify what version of IE has to be checked and you can also cancel the version checker.

Back to top


Setting up the spacer.gif

Because Internet Explorer also lacks on base64 data encoding, we weren't able to let the javascript write the spacer.gif.
Therefore we tried to deliver a solid replacement :

Is there a defined spacer.gif ?
--> If yes, use it.
--> If no, use the local directory 'images/spacer.gif'.
----> If it fails use the google hosted spacer.gif.

We recommend you to define a spacer.gif, the second possibility is a basic option, and the third a rescue action.
Note that the rescue won't be possible if you're offline.

Back to top


Defining the file extension

The last attractive option of this library is that you can define the extension that the hackExtension() method should use.

By that way you can for example hack server-side generated images ending by a variable.

Back to top