iamceege/tooltipster — pull request #75 by louisameline (2013-10-31 14:25:27+00:00)
Title: Tooltipster refactoring

Tooltipster got refactored, hopefully it will be more readable and maintainable. It also got a batch a bug fixes and some new features. The plugin is now more robust and should enable more complex use cases, particularly concerning interactive tooltips.

Changes involve :
-------------------------

- code cleaning in the structure (including tooltipster method), choosing clearer variable names, deleted some "var" repetitions. In particular, things have been fixed for tooltips delegated on icons, as that used to be much complicated to know what was going on. Please take a look at the Plugin function to catch it in a glimpse.
- got rid of unnecessery .data() calls (almost all of them) as there was no reason to bind to the DOM in this manner, preferred instance variables
- the update method is now immediate, having seperated the checkInterval and the content update process
- fixed various bindings and unbindings on body
- a new public method 'content' is available. It acts as a getter when used like .tooltipster('content'), as a setter when used like .tooltipster('content', data). The getter call replaces the 'val' method that has been around for only a couple days. The setter call replaces the 'update' method which is now deprecated (but still working for backward compatibility)
- the provided content and icons can now be jQuery objects with their bindings, the content is now appended and no longer inlined. As a result, the .tooltipster('content') method will return a jQuery object if this is what you provided in the "content" options of the constructor, or via a previous .tooltipster('content', $data) call. Please note that if objects are passed, they will actually be deeply cloned and it is their clone that will be used. Also, if you provide an object as an icon, it will not be applied the iconTheme as it is assumed that you will have styled it by yourself and will want no css property conflicts.
- fixed a couple bugs for people who would like to change the plugin name (not sure what the point is however)
- the functionInit behavior got its original behavior back with origin and content parameters (see https://github.com/iamceege/tooltipster/pull/63 and https://github.com/iamceege/tooltipster/pull/67)
- fixed queues when delay is 0 (not calling $.delay at all) to let things play synchronously
- more thorough about the nature of "empty" content : empty strings are valid content and will now provoke the display of an empty tooltip. This means that a title="" attribute results in an empty tooltip being shown. Do not set a title attribute at all if you want to initialize the tooltip without a content (and thus preventing it from showing up). In the same manner, use .tooltipster('content', null) to actually set an empty content via the API. This is also why the default value of the "content" option is now being set to null rather than an empty string.

Behaviors that have changed
-------------------------

don't worry, almost no code-breaking changes for people who properly use the plugin by its public methods rather than its internals (as they should). Just check my last point, but I hope no one was actually using that feature anyway.
- the tooltip size and position no longer updates on content changes that have been made from the outside without using the update method. I believe that kind of "magic" is not good practice anyway, but autoAnimation parameter may be considered at some point, we'll see
- people who used to bind on the plugin internals like .data() calls on elements should not have done it, please use the proper elementIcon, elementTooltip methods now when you want to build complex interactive tooltips.
- the onlyOne option now defaults to false to avoid unexpected conflicts with non-autoClosing tooltips, see my commit comment on that
- .tooltipster('update', data) method is still working but deprecated, please use .tooltipster('content', data) instead
- the recently added autoclosing of tooltips when they have a select that changes inside them has been removed, as the plugin should not care about what you put inside them. Please use interactiveAutoClose and the elementTooltip and hide methods to set up your own bindings and behaviors
- the plugin does not take script tags off of your content anymore (it was only added a couple days ago anyway). Please understand that it is your job to not let unsafe code get into the plugin content, either by the content option or the title attribute. Script is not the only threat anyway, think of frames or embedded objects for example... Besides, some people may actually want to do this on purpose. So, encode the HTML entities of your content yourself beforehand and you should be safe from XSS, that's a reflex you should have.
- An exception will now be thrown with "unknown method" message when you make a typo in the method name instead of just failing silently and returning the jQuery object back. That will help you debug hopefully. When you call a tooltipster method, respect the case (like : elementTooltip, not elementtooltip). Remember that Javascript is a case-sensitive language.
- removed the ability to call the tooltipster method on an uninitialized container element to reach its children, like `$('body').tooltipster('hide')`. This was unnecessery and slow anyway, please just use some simple `$('.mytooltips').tooltipster('hide')` bit of code. That was almost not documented anyway, just mentioned in an example in the doc that should be amended

FYI, I did not touch the animation part, but I believe they should be almost exclusively left to the CSS file. And animations at showTooltip and at update should not be considered the same thing anyway. I'll leave this to a future commit maybe.

Thank you.