Polyfill Verbiage Distinction

[cboden]

Would it be worth it to document another option beside polyfills? I'm talking about shims. I've noticed some recommendations aren't true polyfills, but something different.

My understanding is a Polyfill adds a feature missing in a browser by making the called API act as it would in another browser. A polyfill is dropped in via <script> and forgotten about by the developer. Browsers that support the feature will not touch the polyfill code.

A Shim is a wrapper, offering a developer a new API, that provides equal feature functionality to all browsers. A Shim will use native functionality if it exists and its solution if it doesn't. Developers have to be aware of the shim and use it accordingly.

Both aim for the same goal: providing a feature across all browsers, but how they're used and implemented are different.

[addyosmani]

A follow up point: the Modernizr polyfills wiki, which was the source for many of the polyfills listed actually acknowledges that it contains both polyfills and shims. If you went through each one in depth, you'd probably find that quite a number weren't truly polyfills that 100% cover the native API. That said, imo, one of the nice things about H5Please is that is just lists fallback solutions. If someone wants to find out if its a 'true' polyfill or a shim, they'll find that out by reading the project readme for that solution or looking through the code. I wouldn't make the distinguish just to avoid confusing beginners, but others may disagree :)

[Raynos]

I don't see how those definitions differ. The ES5-shim qualifies as a polyfill (for the subset it shims correctly).

Can you clarify the difference? As it currently stands I don't think there is any difference worth making a special note about on H5Please

[cboden]

@addyosmani Good point - it's a balance between technical info but trying not to overwhelming. I suppose it depends on the goal of the project.

@Raynos I'll give you an example from two libs I've used:

First is History.js - using it will use the window.history API if it exists but the user interacts via window.History (notice the case difference). This choice had something to do with a technical issue where the devs couldn't provide the desired functionality by supplementing window.history. As a developer I read the documentation on History.js' website for how to use this feature. This is a shim.

web-socket-js when loaded checks to see if the function window.WebSocket exists. If it does not exist it creates the function with the same prototypes found on the W3 docs. As a developer I go off of the W3's documentation. When all browsers have brought their WebSocket API up to code I remove the .js file from my website. This is a polyfill.

[Raynos]

@cboden then why do we have projects called es5-shim and es6-shim. Surely they should be polyfills? Should I rename the dom shim to dom polyfill as well?

It just seems the word shim is commonly used to name a polyfill. What you call shim I call library

[paulirish]

"shim" is a superset of "polyfill".
and it's existed for a long time before polyfill became a thing. so that's why there are projects named X-shim when they are actually proper polyfills. no big deal, IMO.

as for defining verbiage.. Sure. the History ticket is an example of where this is biting us.

How could we do this in the UI? ideas, @cboden ?

[cboden]

@Raynos perhaps instead of using the term "shim" I should use the term "wrapper"?

@paulirish Perhaps sprites with title attributes? Polyfill could be 4 puzzle pieces together to make a square but one piece is missing/coloured differently. Or a cotton ball. shim/wrapper could be a box with gift wrapping and a bow on it.

Or if that's too cryptic at the bottom of a post there is "Recommended polyfills:" and "Recommended shims/wrappers:".

[Raynos]

wrapper is a good term. As for sprites they are confusing but creating community standard images to represent these concepts is always useful.

[domenic]

Why "wrapper" instead of just "library"?

[cboden]

@DomenicDenicola I would say "wapper" falls under the umbrella of "library" but is more specific.

For example Sizzle (jQuery's selector engine) is a library but not a wrapper. The kind of raw selection you can do in Sizzle/jQuery is/was not part of any browser, it's a new feature. jQuery its self is both a library and a wrapper - specifically jQuery.ajax is an API that wraps the xmlhttprequest object (while providing additional functionality).

[Raynos]

specifically jQuery.ajax is an API that wraps the xmlhttprequest object (while providing additional functionality).

specifically sizzle is an API that wraps document.querySelectorAll (while providing additional functionality).

[cboden]

@Raynos I fall back to my "Sizzle was not part" comment. querySelectorAll was invented because of libraries like Sizzle/Ext/Prototype/AnyOtherLibraryIMissed.

Let me re-assess my example then.

Twitter Profile Widget is a library. It will "Display your most recent Twitter updates on any webpage". There is nothing in the Javascript API/DOM about Twitter. This library adds features to your website.

History.js is a wrapper/shim/library. Through window.History it provides functionality of, or like, that of the session history.

[domenic]

My point was, why try to push an awkward-sounding term like "wrapper" that people are unfamiliar with in this context, when you could just say "library" and everyone would know what you mean.

I think the distinction is pretty academic. Especially since I'd call twitter profile widget a widget, and not a library. (To me, a library provides functionality to be used indirectly by developers building something else, not placed directly on your page.)

[cboden]

My point of this entire ticket is "polyfill" is very specific and used incorrectly in some context. A polyfill implementation could also be called a shim or library, and all three would be correct.

web-socket-js could be called a "polyfill", a "shim", or a "library" and all three would be correct.
History.js could be called a "wrapper", "shim", "library" and all three would be correct - but calling it a "polyfill" is not.

My issue is "polyfill" is very specific, but the other terms are ambiguous. What I would like to see is either:

• A succinct word used to describe non-polyfill libraries in order to inform visitors how they behave.
• Drop the word "polyfill" and apply an ambiguous word, such as "library" or "shim" on all posts.

[Raynos]

+1 on polyfill being used for code that doesn't actually polyfill the native implementation. We need to remove the term "polyfill" from them and probably replace it with "fallback" as that's consistent

Alternatively think of a better term.

[nimbupani]

Perhaps shim is the better word then. Fallback is a term I am used to associating for a case which does not require additional assets (like a script file or htc file etc). I maybe in a minority with that association though.

[Raynos]

We might just want to make a page where h5bp defines exactly what it means with the terms its using on the page. Just something that people can double check if they are not sure.

Mainly because I'm confused with the terms, so I presume others will too.

[nimbupani]

So much bike shedding, should we just call them shims and be done? Every programmer understands what a shim is, polyfill is not as clear.