Here’s a Tip: Qtip is Awesome

Posted: July 21, 2012 | Author: | Filed under: Engineering, javascript, qtip | Leave a comment »

Qtip is an awesome solution for displaying context clues on websites using some incredibly simple javascript. We first started using it on Jokels to display a help tip to explain the daily inspiration:

The HTML (well, erb) and JavaScript here is incredibly simple. We put the daily word inside a span, give that span a title that describes its content and then call the “qtip” function on the selected content. The target attribute specifies the page component hovering over which causes the tool-tip shows up. The “position” object determines where the tool-tip points to on the target content and where the caption arrow is on the tool-tip itself. The style object, as you’d expect, is used to style the tool-tip itself.

Qtip’s biggest issue is that it simply isn’t documented very well. We use Qtip to do a variety of slick things at Jokels, but figuring out how to do them took a significant amount of time of digging through the qtip documentation and Googling qtip examples. To save you some time, here are some the slicker features of Qtip and how to use them:

Ajax Qtips

One of the slicker uses of Qtips on Jokels is to display extra Jokel and user information when a user hovers over a user avatar, a joke link or the info tag on each Jokel’s info bar. To accomplish this, we just embed the ID for the joke or the user in a “data-id” attribute for the area in question, then we use the following JavaScript snippet on page load:

The meat of the code is in the “content” object. The “text” attribute is displayed until the “ajax” object can be loaded. The “/qtip/joke/” page is a very simple view which has some simple joke information and takes a query parameter of ‘id’ for the joke. Once this page is loaded it’s displayed in the Qtip.

Specifying More Complicated Content

Another cool use of Qtip is that it can take a jquery element and use that as it’s element. This isn’t used on Jokels, but I have used this in a side project as a way to have a generalized way of grabbing a form element that was hidden and display it to the user when certain conditions are met (e.g. a validation condition comes up that requires additional information from the user):

One issue to be aware of is that Qtip will actually take that DOM content and move it to the bottom of the page in some qtip specific DIV tags, which means that if you have form fields they will no longer be inside the form tag and they will not be included with form submission. There are two approaches to this issue: one is to immediately move the Qtip div back into the form, but there’s a reason Qtip moves its content to the bottom of the page — in earlier versions of IE z-order is not respected so this content may not be visible. A solution that’s more compatible with IE is to call .clone() on content handed to Qtip, then keep matching form fields in sync using a little bit of simple JavaScript (although it is a bit of a hack):

The only change for the Qtip section from the previous gist that is that we add a .clone() to make a copy of the content so Qtip will leave the original section alone. The meat of this gist is the second section: we’re using the live function on page load so that any form field that’s created inside of a qtip div will automatically have a change event handler attached that finds the matching field in the form and updates it to match its own value.

Displaying Validation Messages

Another really slick use of Qtips that I came across recently is to show validation messages on forms. Here, we get the error message and pop it up in a qtip on the form field:

There’s nothing terribly exotic about this example, except for some of the options that after content. By adding the “ready: true” attribute to the show object, we’re telling Qtip to pop up the tip on page load. By giving a null target we’re telling Qtip to never show the message again after the initial page load. The “hide” object tells qtip to hide the message on the “blur” event (focus lost event) for the form field. So the validation message will stay on the form field until the user focuses in and exits the given form field (at which point we can assume they’ve at least had the opportunity to address the issue).

Viewport and Effect

I mentioned before that Qtip isn’t documented well, and hopefully this blog post has shown some cool uses of Qtip that maybe wouldn’t immediately jump out of the tutorials and doc available on the project website, but I wanted to quickly show two options that are critical to a sucessful use of Qtip in your project. Viewport just tells Qtip what to consider the bounds of where it can show a Qtip. So by specifying $(window), Qtip won’t show any pop-ups that will be outside of the browser’s current view. Effect is documented well on Qtip’s site, but the thing most people are going to want to use for effect isn’t, which is simply to turn off all of Qtip’s effects and just show the pop-up, which can just be accomplished by setting the attribute to “false”.

Almost assuredly you’ll find Qtip a fantastic tool for your website or latest project. It’s documentation may leave a little to be desired in terms of organization and comprehensiveness, but that’s only because it’s such a fantastic, versatile tool that it’s difficult to document all of its features.