diff --git a/docs/gettingstarted.md b/docs/gettingstarted.md new file mode 100644 index 00000000..b455b40a --- /dev/null +++ b/docs/gettingstarted.md @@ -0,0 +1,25 @@ +# Getting Started + +## Installation +Now you have the jQuery library and qTip2 files, it's time to include them within your HTML. I **highly recommend** that all JavaScript includes be placed just before the end *</body>* +tag as this ensures the DOM is loaded before manipulation of it occurs. This is not a requirement, simply an insiders tip! + +```html + + +My site + + + + + + + + + + + +``` + +**Note:** Make sure to include either the non-minified *or* the un-minified script, **not both!**
+**Note:** Notice *the jQuery library is included ***before** qTip2*. This is absolutely essential for correct functioning of the plugin! diff --git a/docs/guide-content.md b/docs/guide-content.md new file mode 100644 index 00000000..e2de4816 --- /dev/null +++ b/docs/guide-content.md @@ -0,0 +1,112 @@ +# qTip2 - Complete guide - Content + +qTip2 supports the use of regular old browser text, as well as complex HTML, but what are the best ways of actually providing qTip2 with the content? Element attributes? Hidden text? It really depends upon your spefific scenario, but here's some basic examples to get you started + +## Simple text + +### The *title* attribute +If you plan on using qTip2 as simply a very thin replacement of the browser tooltips, the title attribute is a great way to do so. It's standards compliant, it's the expected place for tooltip text, and the plugin will automaically look there for it's content if none is given inside your `.qtip({ ... })` config object! + +```js +$('[title]').qtip(); // Grab all elements with a title attribute, and apply qTip! +$('[title!=""]').qtip(); // A bit better. Grab elements with a title attribute that isn't blank. +``` + +This is the simplest method of using qTip2, as it requires very little setup and works to replace existing, native tooltips auto-magically! + + +### A custom attribute +If for some reason you can't use the title attribute, or you'd like to use a different attribute for your tooltip text, then you can easily tell qTip2 not to look in the title attribute by default, by setting the `content.attr` config property. For example, say we're using a custom *data-* attribute named `data-tooltip`: + +```js +$('[data-tooltip!=""]').qtip({ // Grab all elements with a non-blank data-tooltip attr. + content: { + attr: 'data-tooltip' // Tell qTip2 to look inside this attr for it's content + } +}) +``` + + +## HTML + +### A note on "this" variable +For those of you new to JavaScript/jQuery land, we'll take a small side-track here to describe a unique property of JavaScript: *the **this** variable*. Feel free to skip this is you're already familiar with it. + +This `this` variable in JavaScript is *scope-dependant*, meaning it's value with change depending upon where abouts you access it within your code. For example, accessing the `this` keyword within the "global" scope i.e. outside any functions, t will refer the `window` element. + +Here's a quick example of how "this" can change, depending upon where it's accessed: + +```js +// This will print out the value of "this" for us +function log() { console.log(this); }; + +log(); // Will print out the "window" (log function has no set scope) +log.call([ 1 ]) // Will print out the "[ 1 ]" array +log.apply({ foo: "bar" }); // Wll print out the "{ foo:"bar" }" object +``` + +Almost all of the jQuery methods which take a function as their parameter also set the value of "this" to refer to the element itself (or each element, if the jQuery object contains more than one). For example: + +```js +$('a').each(function() { // Grab all "" elements, and for each... + log(this); // ...print out "this", which now refers to each DOM element +}); + +$('[title]').qtip({ // Grab all elements with a title attribute + content: { + text: $(this).next(); // Won't work, because "this" is the window element! + } +}); + +$('[title]').each(function() { // Grab all elements with a title attribute,and set "this" + $(this).qtip({ // + content: { + text: $(this).next(); // WILL work, because .each() sets "this" to refer to each element + } + }); +}); +``` + +### A hidden element +For complex HTML content where you require the tooltip content to be printed out alongside the element that will be displaying the qTip, the hidden element approach is best suited. When printing out your HTML, either via some server-side script like PHP or Python, or via hand in a text editor, put the tooltip contents within a `
` element located *directly next to* the element which requires the qTip. For example: + +```html +
Hover me to see a tooltip
+ +``` + +*It's important that the elements be **directly next to eachother** in the DOM* otherwise this approach won't work because of the nature of the jQuery `.next()` method we'll be using! Once you've got the HTML set up as described above, we can setup our qTip's like so: + +```js +// Grab all elements with the class "hasTooltip" +$('.hasTooltip').each(function() { // Notice the .each() loop, discussed below + $(this).qtip({ + content: { + text: $(this).next('div') // Use the "div" element next to this for the content + } + }); +}); +``` + +### XHR (AJAX) +For situations where you'd like to load in additonal content from an external page (located on the same domain, or cross-domain if you're using CORS), use the AJAX plugin. This allows you to easily pull content into your qTip's from a defined URL using regular old `$.ajax` syntax, located in the `content.ajax` object. For example, say we've got a number of elements on the page with an attribute `data-url`, which contains the URL to look for that elements tooltip content: + +```js +$('[data-url]').each(function(i) { + // Store $(this) in a variable, more efficient than calling $() multile times + var element = $(this); + + element.qtip({ + content: { + text: 'Loading...', // Set some initial text, otherwise qTip won't load! + ajax: { + url: element.data('url') // Use data-url attribute for the URL + } + } + }); +}); +``` + +And there you have it. When mousing over those elements with the `data-url` attribute, qTip will automatically grab the HTML from the elements URL, and set it as the qTip content. \ No newline at end of file diff --git a/docs/toc.md b/docs/toc.md new file mode 100644 index 00000000..b3646874 --- /dev/null +++ b/docs/toc.md @@ -0,0 +1,30 @@ +[qTip2 homepage](http://craigsworks.com/projects/qtip2) + +# Documentation table of contents + +## Getting started + +* [Getting started](getting_started.md) - A guide to configuring grunt for your project. +* [FAQ](faq.md) - Frequently asked questions, along with their answers. + +## Guides + +* [Content](guide-content.md) - Learn how to load anduse textual and HTML content within your qTip's +* _(more documentation coming soon)_ + +## API reference + +* [content](content.md) - Content +* [position](position.md) - Positioning and corner types +* [show](show.md) - Show properties and effects +* [hide](hide.md) - Hide properties and effects +* [style](style.md) - Styling properties +* [events](events.md) - Events API + +## Other built-ins + +* [Helpers and Directives](helpers_directives.md) - Ones not specifically covered in other task documentation. + +## Development ⚑ + +* [Contributing to grunt](contributing.md) - Development advice. \ No newline at end of file