Summary
Documentation
Basics
In this chapter, we will teach you the easiest and securest way to use PNGHack.
First of all, you'll have to set up a spacer.gif in your images directory
Your websites folder should look like this :
You can also check the advanced functionalities to set up the spacer.gif
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
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 :)
Advanced functionalities
Writing a PNGHack object
- PNGhack() Class
Syntax :
Parameters :object = new PNGHack([spacer]);- spacer : Defines the local directory or hosted directory for spacer.gif
Methods
- hackClass() Method
Syntax :
Parameters :object.hackClass({ [elm:sTag] [, src:sSrc] [, scope:DOMNode] });- 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 :
Parameters :object.hackExtension({ [elm:sTag] [, src:sSrc] [, ext:RegExp] [, scope:DOMNode] });- 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 :
Parameters :object.hackElement({ elm:DOMElement [, src:sSrc] });- 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.
Collections
- elements Collection
Syntax :
Remarks :object.elements;The elements collection returns an array of all hacked elements.
It is readable and writable.
Properties
- checkIE Property
Syntax :
Possible values :object.checkIE = [RegExp];- '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 :
Possible values :object.remotehost = [value];- 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
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 ?
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 !
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.
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" />
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.
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.
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.