/
index.html
1768 lines (1389 loc) · 97.9 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html lang="en">
<head>
<title>Tooltipster - The jQuery Tooltip Plugin</title>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1.0, user-scalable=no">
<meta name="description" content="Tooltipster is a powerful, flexible jQuery plugin enabling you to easily create clean, HTML5 validated tooltips." />
<meta property="og:title" content="Tooltipster" />
<meta property="og:type" content="website" />
<meta property="og:url" content="index.html" />
<meta property="og:image" content="images/social.jpg" />
<meta property="og:site_name" content="Tooltipster - The jQuery Tooltip Plugin" />
<meta property="og:description" content="Tooltipster is a powerful, flexible jQuery plugin enabling you to easily create clean, HTML5 validated tooltips." />
<meta itemprop="name" content="Tooltipster - The jQuery Tooltip Plugin">
<meta itemprop="description" content="Tooltipster is a powerful, flexible jQuery plugin enabling you to easily create clean, HTML5 validated tooltips.">
<meta itemprop="image" content="images/social.jpg">
<link rel="icon" type="image/png" href="images/favicon.png" />
<link rel="image_src" href="images/social.jpg" />
<link rel="stylesheet" type="text/css" href="doc/css/reset.css" />
<link rel="stylesheet" type="text/css" href="doc/css/prettify.css" />
<link rel="stylesheet" type="text/css" href="doc/css/style.css" />
<link rel="stylesheet" type="text/css" href="dist/css/tooltipster.bundle.min.css" />
<link rel="stylesheet" type="text/css" href="dist/css/plugins/tooltipster/sideTip/themes/tooltipster-sideTip-borderless.min.css" />
<link rel="stylesheet" type="text/css" href="dist/css/plugins/tooltipster/sideTip/themes/tooltipster-sideTip-light.min.css" />
<link rel="stylesheet" type="text/css" href="dist/css/plugins/tooltipster/sideTip/themes/tooltipster-sideTip-noir.min.css" />
<link rel="stylesheet" type="text/css" href="dist/css/plugins/tooltipster/sideTip/themes/tooltipster-sideTip-punk.min.css" />
<link rel="stylesheet" type="text/css" href="dist/css/plugins/tooltipster/sideTip/themes/tooltipster-sideTip-shadow.min.css" />
<link rel="stylesheet" type="text/css" href="//louisameline.github.io/tooltipster-follower/dist/css/tooltipster-follower.min.css" />
<link rel="stylesheet" href="doc/js/jquery-ui-draggable/jquery-ui.min.css">
<script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.10.0/jquery.min.js"></script>
<script type="text/javascript" src="dist/js/tooltipster.bundle.js"></script>
<script type="text/javascript" src="//louisameline.github.io/tooltipster-follower/dist/js/tooltipster-follower.min.js"></script>
<script type="text/javascript" src="//louisameline.github.io/tooltipster-discovery/tooltipster-discovery.min.js"></script>
<script type="text/javascript" src="doc/js/scripts.js"></script>
<script type="text/javascript" src="doc/js/jquery-ui-draggable/jquery-ui.min.js"></script>
<script type="text/javascript" src="doc/js/jquery.ui.touch-punch.min.js"></script>
<script type="text/javascript" src="doc/js/jquery.jgfeed.js"></script>
<script type="text/javascript" src="doc/js/prettify.js"></script>
<script type="text/javascript" src="doc/js/lang-css.js"></script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
</head>
<body>
<div id="background">
<img src="doc/images/large-background.jpg" />
</div>
<div id="wrapper">
<header>
<div id="social">
<div id="github">
<iframe src="http://ghbtns.com/github-btn.html?user=calebjacob&repo=tooltipster&type=watch&count=true" allowtransparency="true" frameborder="0" scrolling="0" width="100" height="20"></iframe>
</div>
<div id="tweet">
<a href="https://twitter.com/share" class="twitter-share-button" data-text="Tooltipster - A powerful & degradable jQuery tooltip plugin" data-via="calebjacob" data-related="calebjacob">Tweet</a>
<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="//platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script>
</div>
<div id="gplus">
<g:plusone href="http://calebjacob.com/tooltipster"></g:plusone>
</div>
</div>
<nav>
<ul>
<li><a href="https://github.com/calebjacob/tooltipster/archive/master.zip">Download</a></li>
<li><a href="#demos">Demos</a></li>
<li><a href="#getting-started">Get started</a></li>
<li><a href="#options">Options</a></li>
<li><a href="#methods">Methods</a></li>
<li><a href="#usecases">Use cases</a></li>
<li><a href="#faq">FAQ</a></li>
</ul>
</nav>
<select>
<option selected="selected" disabled="disabled">Menu...</option>
<option value="demos">Demos</option>
<option value="getting-started">Get started</option>
<option value="options">Options</option>
<option value="methods">Methods</option>
<option value="usecases">Use cases</option>
<option value="faq">FAQ</option>
</select>
</header>
<section id="welcome">
<img src="doc/images/tooltipster.svg" alt="Tooltipster" id="tooltipster" />
<h1>
A flexible and extensible jQuery plugin for modern tooltips.<br />
Simple enough for everyone, powerful enough for everything.
</h1>
<div id="browsers">
<img src="doc/images/browser-chrome.png" alt="Chrome" class="tooltip" title="Chrome Support" />
<img src="doc/images/browser-firefox.png" alt="FireFox" class="tooltip" title="FireFox Support" />
<img src="doc/images/browser-opera.png" alt="Opera" class="tooltip" title="Opera Support" />
<img src="doc/images/browser-safari.png" alt="Safari" class="tooltip" title="Safari Support" />
<img src="doc/images/browser-ie.png" alt="Internet Explorer" class="tooltip" title="IE6+ support" />
</div>
<div id="download">
<a href="https://github.com/calebjacob/tooltipster/archive/master.zip" class="button alt">Download</a>
</div>
</section>
<section id="demos">
<h2>Demos</h2>
<ul>
<li>
<span id="demo-default" title="Hi! I am a tooltip.">Hover</span> Default settings
</li>
<li id="test">
<span id="demo-events" title="Press any key on your keyboard or click anywhere in the page to close me">Click</span> Custom open/close triggers
</li>
<li>
<span id="demo-html" data-tooltip-content="#demo-html-content">Hover</span> HTML, side, fixed size
</li>
<li>
<span id="demo-smart">Drag</span> Smart positioning
</li>
<li>
<span id="demo-touch">Click</span> Mouse, touch & hybrid devices
</li>
<li>
<span id="demo-theme" title="Build custom themes and CSS powered animations!">Hover</span> Custom themes & animations
</li>
<li>
<span id="demo-callback" title="This will be populated by AJAX.">Hover</span> Custom callbacks (AJAX <3)
</li>
<li>
<span id="demo-interact" title="Try clicking <a href='http://google.com/' target='_blank'>this link</a>">Hover</span> Interaction with tooltips
</li>
<li>
<span id="demo-imagemap">
<img id="demo-imagemapped" src="./doc/images/star.png" usemap="#imagemap" />
<map name="imagemap">
<area id="demo-imagemaparea" title="The tooltip triggers only on a given image area" shape="poly" coords="20,17,26,0,32,17,48,16,36,29,40,45,27,36,11,45,16,29,2,17" />
</map>
</span> Support of image maps & SVG
</li>
<li>
<span id="demo-multiple">Hover</span> Multiple tooltips on a single element
</li>
<li id="demo-complex-li">
<span id="demo-complex-placeholder"></span>
<span id="demo-complex" title="I also stick to fixed-positioned, moving and resizing elements. Try scrolling!">Click</span> Position tracking system
</li>
<li>
<span id="demo-position" data-tooltip-content="#demo-position-content">Hover</span> <div id="demo-position-grid">Custom position</div>
</li>
<li>
<span id="demo-plugin" title="I use a plugin to follow the mouse!">Hover</span> Extensible with plugins
</li>
<li>...& more!</li>
</ul>
<br class="clear" />
</section>
<div id="templates">
<div id="demo-html-content">
<img src="doc/images/spiderman.png" width="50" height="50" />
<p style="text-align:left;">
<strong>Lorem ipsum dolor sit amet</strong><br />
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu.
</p>
</div>
<span id="demo-position-content">I'm the most accurate tooltip ever! Let me fit to your layout the way you want to. I'm great to create menus too :)</span>
</div>
<section id="getting-started">
<h2>Getting Started <a href="#">⇑</a></h2>
<h3>1. Load jQuery and include Tooltipster's files</h3>
<p>After you <a href="https://github.com/calebjacob/tooltipster/archive/master.zip">download Tooltipster</a>, load jQuery and include Tooltipster's CSS and JavaScript files in your page.<br /></p>
<pre class="prettyprint">
<head>
<link rel="stylesheet" type="text/css" href="tooltipster/dist/css/tooltipster.bundle.min.css" />
<script type="text/javascript" src="http://code.jquery.com/jquery-1.10.0.min.js"></script>
<script type="text/javascript" src="tooltipster/dist/js/tooltipster.bundle.min.js"></script>
</head>
</pre>
<p>Compatibility note: jQuery 1.7 is enough except if you need SVG support in IE (then use jQuery 1.10+). Tooltipster does not work at all with jQuery 1.8 in IE9.</p>
<p>Bonus: available on <a href="https://github.com/calebjacob/tooltipster" target="_blank">GitHub</a> but also on <a href="https://www.npmjs.com/package/tooltipster" target="_blank">Npm</a>, <a href="https://libraries.io/bower/tooltipster" target="_blank">Bower</a> and <a href="https://www.jsdelivr.com/projects/jquery.tooltipster" target="_blank">jsDelivr</a>.<br />
Bonus 2: if you need .gz files, running <span class="code">grunt compress</span> will gzip all files within the dist folder.</p>
<h3>2. Set up your HTML</h3>
<p>To spot the elements which will get a tooltip, aka the "origins", we will give them a <span class="code">'tooltip'</span> class. You may use another class name or even other means of selection, your choice. After that, we will set the <span class="code">title</span> attribute to whatever we'd like our tooltip to say. Here are a couple examples:</p>
<pre class="prettyprint">
// Putting a tooltip on an image:
<img src="my-image.png" class="tooltip" title="This is my image's tooltip message!" />
// Putting a tooltip on some text (span, div or whatever):
<span class="tooltip" title="This is my span's tooltip message!">Some text</span>
</pre>
<p>Note: if you use Twitter's Bootstrap, use another class name because <span class="code">'tooltip'</span> will create a conflict.</p>
<h3>3. Activate Tooltipster</h3>
<p>The last thing we have to do is activate Tooltipster. To do this, add the following script right before your closing <span class="code"></head></span> tag (using whatever selector you like - in this case we're still using the <span class="code">'tooltip'</span> class):</p>
<pre class="prettyprint">
<head>
...
<script>
$(document).ready(function() {
$('.tooltip').tooltipster();
});
</script>
</head></pre>
<h3 id="theming">4. Style your tooltips</h3>
<p>On top of its default style, Tooltipster is packaged with five themes to choose from.</p>
<div id="themes">
<div class="tooltipster-default-preview tooltip" title="The default style" target="_blank">Default</div>
<div class="tooltipster-light-preview" title="Light and frisky!" target="_blank">Light</div>
<div class="tooltipster-borderless-preview" title="Let's travel!" target="_blank">Borderless</div>
<div class="tooltipster-punk-preview" title="I will not conform to your old fart ways!" target="_blank">Punk</div>
<div class="tooltipster-noir-preview" title="Hipsterific!" target="_blank">Noir</div>
<div class="tooltipster-shadow-preview" title="Hey, I have a smaller arrow" target="_blank">Shadow</div>
</div>
<p> To use a theme, just include its css file (located in the <span class="code">dist/css/plugins/tooltipster/sideTip/themes</span> folder) in your page and specify its name in Tooltipster's options:</p>
<pre class="prettyprint">
$('.tooltip').tooltipster({
theme: 'tooltipster-noir'
});</pre>
<p>To bring your own modifications to the style of your tooltips, a <a href="#styling">custom themes section</a> awaits you below.</p>
<p>Note: "sideTip" is the name of the plugin used by default by Tooltipster. We'll see about plugins later.</p>
<h3 id="html">5. Use HTML inside your tooltips</h3>
<p>Tooltipster allows you to use any HTML markup inside your tooltips. It means that you can insert things like images and text formatting tags.</p>
<p>Instead of a <span class="code">title</span> attribute, use a <span class="code">data-tooltip-content</span> attribute to provide a selector that corresponds to the HTML element of your page that should be used as content. This is your HTML:</p>
<pre class="prettyprint">
<span class="tooltip" data-tooltip-content="#tooltip_content">This span has a tooltip with HTML when you hover over it!</span>
<div class="tooltip_templates">
<span id="tooltip_content">
<img src="myimage.png" /> <strong>This is the content of my tooltip!</strong>
</span>
</div></pre>
<p>In your CSS file, add <span class="code">.tooltip_templates { display: none; }</span> so that the content does not get displayed outside of the tooltip.</p>
<p>Important: if you have two tooltips that have the same <span class="code">data-tooltip-content</span> attribute (that is to say, want to both use the same HTML element), please set the <span class="code">contentCloning</span> option to <span class="code">true</span> when you initialize your tooltips:</p>
<pre class="prettyprint">
$('.tooltip').tooltipster({
contentCloning: true
});</pre>
<p>Note: there are alternative ways of setting HTML content in the tooltip, discussed in <a href="#htmlcontentalt">this section</a>.</p>
<h3>6. Use plugins</h3>
<p>
Tooltipster's features may be extended through the use of plugins. They may add new styles, new options, new methods, new behaviors, etc.<br />
Some popular plugins for Tooltipster are:
</p>
<p><span class="code">sideTip</span> Shipped with Tooltipster and used by default</p>
<p><span class="code">SVG</span> Shipped with Tooltipster, adds SVG support, not enabled by default (see the <a href="#svg">SVG section</a>)</p>
<p><span class="code">follower</span> Lets the tooltip follow the cursor. Available <a href="https://github.com/louisameline/tooltipster-follower" target="_blank">here</a></p>
<p><span class="code">scrollableTip</span> Makes the tooltip scrollable when it gets too big. Available <a href="https://github.com/louisameline/tooltipster-scrollableTip" target="_blank">here</a></p>
<p><span class="code">discovery</span> Creates groups of tooltips for faster display. Demonstrated in the <a href="#grouped">Grouped tooltips</a> section and available <a href="https://github.com/louisameline/tooltipster-discovery" target="_blank">here</a></p>
<p><span class="code">selectableText</span> Makes a tooltip appear when you select / highlight some text. Available <a href="https://github.com/louisameline/tooltipster-selectableText" target="_blank">here</a></p>
<p>For more information about plugins, read our <a href="#plugins">plugins section</a>.</p>
</section>
<section id="options">
<h2>Options <a href="#">⇑</a></h2>
<p>Tooltipster's options give you a wide range of variables to tweak your tooltip to your heart's content. Here's how you declare options:</p>
<pre class="prettyprint">
$('.tooltip').tooltipster({
animation: 'fade',
delay: 200,
theme: 'tooltipster-punk',
trigger: 'click'
});</pre>
<p>And here is the full list of available options:</p>
<table id="table_options" border="0" cellpadding="0" cellspacing="0">
<tr>
<td><b>Option name</b></td>
<td><b>Accepted values</b></td>
<td><b>Description</b></td>
</tr>
<tr>
<td><h4>animation</h4></td>
<td>'fade',<br />
'grow',<br />
'swing',<br />
'slide',<br />
'fall'</td>
<td>Determines how the tooltip will animate in and out. In addition to the built-in transitions, you may also create custom transitions in your CSS files. In IE9 and lower, all animations default to a JavaScript generated, fade animation. <strong>Default: 'fade'</strong></td>
</tr>
<tr>
<td><h4>animationDuration</h4></td>
<td>integer,<br />integer[]</td>
<td>Sets the duration of the animation, in milliseconds. If you wish to provide different durations for the opening and closing animations, provide an array of two different values. <strong>Default: 350</strong></td>
</tr>
<tr>
<td><h4>arrow</h4></td>
<td>boolean</td>
<td>Add a "speech bubble" arrow to the tooltip. <strong>Default: true</strong></td>
</tr>
<tr>
<td><h4>content</h4></td>
<td>string,<br />jQuery object,<br />any</td>
<td>If set, this will override the content of the tooltip. If you provide something else than a string or jQuery-wrapped HTML element, you will need to use the 'functionFormat' option to format your content for display. <strong>Default: null</strong></td>
</tr>
<tr>
<td><h4>contentAsHTML</h4></td>
<td>boolean</td>
<td>If the content of the tooltip is provided as a string, it is displayed as plain text by default. If this content should actually be interpreted as HTML, set this option to true. <strong>Default: false</strong></td>
</tr>
<tr>
<td><h4>contentCloning</h4></td>
<td>boolean</td>
<td>If you provide a jQuery object to the 'content' option, this sets if it is a clone of this object that should actually be used. <strong>Default: false</strong></td>
</tr>
<tr>
<td><h4>debug</h4></td>
<td>boolean</td>
<td>Tooltipster logs hints and notices into the console when you're doing something you ideally shouldn't be doing. Set to false to disable logging. <strong>Default: true</strong></td>
</tr>
<tr>
<td><h4>delay</h4></td>
<td>integer,<br />integer[]</td>
<td>Upon mouse interaction, this is the delay before the tooltip starts its opening and closing animations when the 'hover' trigger is used <span class="tooltip" title="More specifically: when the 'triggerOpen.mouseenter' and/or 'triggerClose.mouseleave' are used">(<span class="red">*</span>)</span>. If you wish to specify different delays for opening and closing, you may provide an array of two different values. <strong>Default: 300</strong></td>
</tr>
<tr>
<td><h4>delayTouch</h4></td>
<td>integer,<br />integer[]</td>
<td>Upon touch interaction, this is the delay before the tooltip starts its opening and closing animations when the 'hover' trigger is used <span class="tooltip" title="More specifically: when the 'triggerOpen.touchstart' and/or 'triggerClose.touchleave' are used">(<span class="red">*</span>)</span>. If you wish to specify different delays for opening and closing, you may provide an array of two different values. <strong>Default: [300, 500]</strong></td>
</tr>
<tr>
<td><h4>distance</h4></td>
<td>integer,<br />integer[]</td>
<td>The distance between the origin and the tooltip, in pixels. The value may be an integer or an array of integers (in the usual CSS syntax) if you wish to specify a different distance for each side. <strong>Default: 6</strong></td>
</tr>
<tr>
<td><h4>functionInit</h4></td>
<td>function</td>
<td>A custom function to be fired only once at instantiation. <a href="#callback_arguments">Arguments</a>. <strong>Default: none (null)</strong></td>
</tr>
<tr>
<td><h4>functionBefore</h4></td>
<td>function</td>
<td>A custom function to be fired before the tooltip is opened. This function may prevent the opening if it returns false. <a href="#callback_arguments">Arguments</a>. <strong>Default: none (null)</strong></td>
</tr>
<tr>
<td><h4>functionReady</h4></td>
<td>function</td>
<td>A custom function to be fired when the tooltip and its contents have been added to the DOM. <a href="#callback_arguments">Arguments</a>. <strong>Default: none (null)</strong></td>
</tr>
<tr>
<td><h4>functionAfter</h4></td>
<td>function</td>
<td>A custom function to be fired once the tooltip has been closed and removed from the DOM. <a href="#callback_arguments">Arguments</a>. <strong>Default: none (null)</strong></td>
</tr>
<tr>
<td><h4>functionFormat</h4></td>
<td>function</td>
<td>A custom function that does not modify the content but that can format it for display. It gets the two first usual <a href="#callback_arguments">arguments</a> and also the content as third argument. It must return the value that will be displayed in the tooltip, either a string or a jQuery-wrapped HTML element (see the <a href="#formatting">formatting section</a>). <strong>Default: none (null)</strong></td>
</tr>
<tr>
<td><h4>functionPosition</h4></td>
<td>function</td>
<td>A custom function fired when the tooltip is repositioned. It gives you the ability to slightly or completely modify the position that Tooltipster is about to give to the tooltip. It gets the proposed set of placement values as third argument. The function must return the set of placement values, which you may have edited (see the <a href="#positioning">positioning section</a>). <strong>Default: none (null)</strong></td>
</tr>
<tr>
<td><h4>IEmin</h4></td>
<td>integer</td>
<td>The minimum version of Internet Explorer to run on. <strong>Default: 6</strong></td>
</tr>
<tr>
<td><h4>interactive</h4></td>
<td>boolean</td>
<td>Give users the possibility to interact with the content of the tooltip. If you want them to be able to make clicks, fill forms or do other interactions inside the tooltip, you have to set this option to true. When the 'hover' close trigger is used, the user has to move the cursor to the tooltip before it starts closing (this lapse of time has its duration set by the 'delay' option). <strong>Default: false</strong></td>
</tr>
<tr>
<td><h4>maxWidth</h4></td>
<td>integer</td>
<td>Set a maximum width for the tooltip. <strong>Default: null (no max width)</strong></td>
</tr>
<tr>
<td><h4>minIntersection</h4></td>
<td>integer</td>
<td>Corresponds to the minimum distance to enforce between the center of the arrow and the edges of the tooltip. Mainly used to create an arrow bigger than those of the default themes. <strong>Default: 16</strong></td>
</tr>
<tr>
<td><h4>minWidth</h4></td>
<td>integer</td>
<td>Set a minimum width for the tooltip. <strong>Default: 0 (auto width)</strong></td>
</tr>
<tr>
<td><h4>multiple</h4></td>
<td>boolean</td>
<td>Allows you to put several tooltips on a single element (see the <a href="#multiple">multiple section</a>). <strong>Default: false</strong></td>
</tr>
<tr>
<td><h4>plugins</h4></td>
<td>string[]</td>
<td>The names of plugins to be used by Tooltipster. <strong>Default: ['sideTip']</strong></td>
</tr>
<tr>
<td><h4>repositionOnScroll</h4></td>
<td>boolean</td>
<td>Repositions the tooltip if it goes out of the viewport when the user scrolls the page, in order to keep it visible as long as possible. <strong>Default: false</strong></td>
</tr>
<tr>
<td><h4>restoration</h4></td>
<td>'none',<br />'previous',<br />'current'</td>
<td>Specifies if a TITLE attribute should be restored on the HTML element after a call to the 'destroy' method. This attribute may be omitted, or be restored with the value that existed before Tooltipster was initialized, or be restored with the stringified value of the current content. Note: in case of multiple tooltips on a single element, only the last destroyed tooltip may trigger a restoration. <strong>Default: 'none'</strong></td>
</tr>
<tr>
<td><h4>selfDestruction</h4></td>
<td>boolean</td>
<td>Sets if the tooltip should self-destruct after a few seconds when its origin is removed from the DOM. This prevents memory leaks. <strong>Default: true</strong></td>
</tr>
<tr>
<td><h4>side</h4></td>
<td>string,<br />string[]</td>
<td>Sets the side of the tooltip. The value may one of the following: 'top', 'bottom', 'left', 'right'. It may also be an array containing one or more of these values. When using an array, the order of values is taken into account as order of fallbacks and the absence of a side disables it (see the <a href="#sides">sides section</a>). <strong>Default: ['top', 'bottom', 'right', 'left']</strong></td>
</tr>
<tr>
<td><h4>timer</h4></td>
<td>integer</td>
<td>How long (in ms) the tooltip should live before closing. <strong>Default: 0 (disabled)</strong></td>
</tr>
<tr>
<td><h4>theme</h4></td>
<td>string,<br />string[]</td>
<td>Set a theme that will override the default tooltip appearance. You may provide an array of strings to apply several themes at once (see the <a href="#theming">themes section</a>). <strong>Default: empty array</strong></td>
</tr>
<tr>
<td><h4>trackerInterval</h4></td>
<td>integer</td>
<td>Sets how often the tracker should run (see trackOrigin and trackTooltip), in milliseconds. The tracker runs even if trackOrigin and trackTooltip are false to check if the origin has not been removed while the tooltip was open, so you shouldn't set too high or too low values unless you need to. <strong>Default: 500</strong></td>
</tr>
<tr>
<td><h4>trackOrigin</h4></td>
<td>boolean</td>
<td>Repositions the tooltip if the origin moves or is resized. As this option may have an impact on performance, we suggest you enable it only if you need to. <strong>Default: false</strong></td>
</tr>
<tr>
<td><h4>trackTooltip</h4></td>
<td>boolean</td>
<td>Repositions the tooltip if its size changes. When the size change results from a call to the 'content' method, the tooltip is already repositioned without the need to enable this option. As this option may have an impact on performance, we suggest you enable it only if you need to. See <a href="#faq_sizeissue">this entry</a> of the FAQ. <strong>Default: false</strong></td>
</tr>
<tr>
<td><h4>trigger</h4></td>
<td>'hover',<br />'click',<br />'custom'</td>
<td>Sets when the tooltip should open and close. 'hover' and 'click' correspond to predefined sets of built-in triggers, while 'custom' lets you create your own, for a completely customized behavior. See the <a href="#triggers">triggers section</a> to learn how to use custom triggers. <strong>Default: 'hover'</strong></td>
</tr>
<tr>
<td><h4>triggerClose</h4></td>
<td>object</td>
<td>When 'trigger' is set to 'custom', all built-in close triggers are disabled by default. This option allows you to reactivate the triggers of your choice to create a customized behavior. Only applies if 'trigger' is set to 'custom'. See the <a href="#triggers">triggers section</a>.</td>
</tr>
<tr>
<td><h4>triggerOpen</h4></td>
<td>object</td>
<td>Similar to 'triggerClose'.</td>
</tr>
<tr>
<td><h4>updateAnimation</h4></td>
<td>'fade',<br />'rotate',<br />'scale',<br />null</td>
<td>Plays a subtle animation when the content of the tooltip is updated (if the tooltip is open). You may create custom animations in your CSS files. Set to null to disable the animation. <strong>Default: 'rotate'</strong></td>
</tr>
<tr>
<td><h4>viewportAware</h4></td>
<td>boolean</td>
<td>Tries to place the tooltip in such a way that it will be entirely visible on screen when it's opened. If the tooltip is to be opened while its origin is off screen (using a method call), you may want to set this option to false. <strong>Default: true</strong></td>
</tr>
<tr>
<td><h4>zIndex</h4></td>
<td>integer</td>
<td>Set the z-index of the tooltip. <strong>Default: 9999999</strong></td>
</tr>
</table>
<br /><br />
<h3 id="callback_arguments">Arguments passed to callback functions</h3>
<p>Almost all user callbacks have the same input signature. It means that <span class="code">functionInit</span>, <span class="code">functionBefore</span>, <span class="code">functionReady</span>, <span class="code">functionAfter</span>, <span class="code">functionFormat</span>, <span class="code">functionPosition</span> and the <span class="code">open</span> and <span class="code">close</span> callbacks all get these two parameters:</p>
<pre class="prettyprint">
// this is valid for the other callback functions too
functionInit(instance, helper){
...
}</pre>
<p>Small exception: <span class="code">functionFormat</span> and <span class="code">functionPosition</span> get an extra third parameter (documented above).</p>
<p><span class="code">instance</span> is the Tooltipster object which is calling the callback function and is described in the <a href="#object-oriented">object-oriented section</a>.</p>
<p><span class="code">helper</span> is an object that contains variables that you may find useful. For example:</p>
<p><span class="code">helper.origin</span> is always present, it's the HTML element on which the tooltip is set.</p>
<p><span class="code">helper.tooltip</span> is present in <span class="code">functionReady</span> and <span class="code">open</span> callbacks, it's the root HTML element of the tooltip. In other callbacks, it is <span class="code">undefined</span>.</p>
<p><span class="code">helper.event</span> is present in <span class="code">functionBefore</span> and <span class="code">functionAfter</span> callbacks. It's the mouse or touch event that triggered the opening or the closing of the tooltip. When the action was not triggered by a mouse or touch event, this variable is <span class="code">null</span> or <span class="code">undefined</span>.</p>
</section>
<section id="methods">
<h2>Methods <a href="#">⇑</a></h2>
<p>For advanced use cases, Tooltipster offers a set of methods to manipulate your tooltips. They allow you to create custom triggers, update tooltip content on the fly (whether the tooltip is currently open or not), destroy Tooltipster functionality if needed, reposition tooltips and more.</p>
<h3 id="instance_methods">Instance methods</h3>
<p>Instance methods are used to manipulate one tooltip in particular. There are two ways to call them.</p>
<p>1) Through the origin's HTML element: <span class="code">$('#my-tooltip').tooltipster(methodName [, argument1] [, argument2]);</span></p>
<p>2) Through the tooltip instance, when you have it: <span class="code">instance.methodName([argument1] [, argument2]);</span></p>
<p>The latter will be discussed in the <a href="#object-oriented">object-oriented section</a>. Users with simple use cases just need to know that it's the recommended way of calling methods when you are inside <span class="code">functionInit</span>, <span class="code">functionBefore</span> and the like. Here is the list of instance methods:</p>
<br /><br />
<table class="table_methods" border="0" cellpadding="0" cellspacing="0">
<tr>
<td><b>Method name</b></td>
<td><b>Arguments</b></td>
<td><b>Description</b></td>
</tr>
<tr>
<td><h4>close</h4></td>
<td>callback</td>
<td>Closes the tooltip. When the animation is over, its HTML element is destroyed (definitely removed from the DOM). The `callback` function argument is optional (see its <a href="#callback_arguments">input signature</a>).</td>
</tr>
<tr>
<td><h4>content (getter)</h4></td>
<td>None</td>
<td>Returns a tooltip's current content. If the selector matches multiple origins, only the value of the first will be returned.</td>
</tr>
<tr>
<td><h4>content (setter)</h4></td>
<td>content</td>
<td>Updates the tooltip's content.</td>
</tr>
<tr>
<td><h4>destroy</h4></td>
<td>None</td>
<td>Closes and destroys the tooltip functionality.</td>
</tr>
<tr>
<td><h4>disable</h4></td>
<td>None</td>
<td>Temporarily disables a tooltip from being able to open.</td>
</tr>
<tr>
<td><h4>elementOrigin</h4></td>
<td>None</td>
<td>Returns the HTML element which has been tooltipped.</td>
</tr>
<tr>
<td><h4>elementTooltip</h4></td>
<td>None</td>
<td>Returns the HTML root element of the tooltip if it is open, `null` if it is closed.</td>
</tr>
<tr>
<td><h4>enable</h4></td>
<td>None</td>
<td>If a tooltip was disabled, restores its previous functionality.</td>
</tr>
<tr>
<td><h4>instance</h4></td>
<td>None</td>
<td>Returns the instance of Tooltipster associated to the tooltip. If the selector matches multiple origins, only the instance of the first will be returned.</td>
</tr>
<tr>
<td><h4>on, one, off, triggerHandler</h4></td>
<td>callback</td>
<td>Handle Tooltipster's events on a per-instance basis (see the <a href="#events">events section</a>).</td>
</tr>
<tr>
<td><h4>open</h4></td>
<td>callback</td>
<td>Opens the tooltip. The `callback` function argument is optional (see its <a href="#callback_arguments">input signature</a>) and, if provided, is called when the opening animation has ended.</td>
</tr>
<tr>
<td><h4>option (getter)</h4></td>
<td>optionName</td>
<td>Returns the value of an option.</td>
</tr>
<tr>
<td><h4>option (setter)</h4></td>
<td>optionName, optionValue</td>
<td>Sets the value of an option (for advanced users only; we do not provide support on unexpected results).</td>
</tr>
<tr>
<td><h4>reposition</h4></td>
<td>None</td>
<td>Resizes and repositions the tooltip.</td>
</tr>
<tr>
<td><h4>status</h4></td>
<td>None</td>
<td>Returns various information about the tooltip, like whether it is open or not. See the <a href="#status">status section</a>.</td>
</tr>
</table>
<br /><br />
<p>Example of the first syntax:</p>
<pre class="prettyprint">
// initialize your tooltip as usual:
$('#my-tooltip').tooltipster({});
// at some point you may decide to update its content:
$('#my-tooltip').tooltipster('content', 'My new content');
// ...and open it:
$('#my-tooltip').tooltipster('open');
// NOTE: most methods are actually chainable, as you would expect them to be:
$('#my-other-tooltip')
.tooltipster({})
.tooltipster('content', 'My new content')
.tooltipster('open');</pre>
<p>Example of the second syntax:</p>
<pre class="prettyprint">
$('.tooltip').tooltipster({
functionBefore: function(instance, helper) {
instance.content('My new content');
}
});</pre>
<h3 id="core_methods">Core methods</h3>
<p>Core methods are methods which may affect/handle several tooltips at once. You call them with: <span class="code">$.tooltipster.methodName([argument]);</span></p>
<br />
<table class="table_methods" border="0" cellpadding="0" cellspacing="0">
<tr>
<td><b>Method name</b></td>
<td><b>Arguments</b></td>
<td><b>Description</b></td>
</tr>
<tr>
<td><h4>instances</h4></td>
<td>None<br />OR selector<br />OR HTML element</td>
<td>Returns the instances of Tooltipster of all tooltips set on the element(s) matched by the argument. If there is no argument, then all instances of all tooltips present in the page are returned.</td>
</tr>
<tr>
<td><h4>instancesLatest</h4></td>
<td>None</td>
<td>Returns the instances of Tooltipster which were generated during the last initializing call.</td>
</tr>
<tr>
<td><h4>on, one, off, triggerHandler</h4></td>
<td></td>
<td>Handle Tooltipster's events coming from any instances. See the <a href="#events">events</a> section.</td>
</tr>
<tr>
<td><h4>origins</h4></td>
<td>None<br />OR selector</td>
<td>Returns an array of all HTML elements in the page which have one or several tooltips initialized. If a selector is passed, the results will be limited to the descendants of the matched elements.</td>
</tr>
<tr>
<td><h4>setDefaults</h4></td>
<td>options</td>
<td>Changes the default options that will apply to any tooltips created from now on.</td>
</tr>
</table>
<br /><br />
<p>Examples:</p>
<pre class="prettyprint">
// Set default options for all future tooltip instantiations
$.tooltipster.setDefaults({
side: 'bottom',
...
});
// The `instances` method, when used without a second parameter, allows you to access all tooltips present in the page.
// That may be useful to close all tooltips at once for example:
var instances = $.tooltipster.instances();
$.each(instances, function(i, instance){
instance.close();
});
$('.tooltip1').tooltipster();
$('.tooltip2').tooltipster();
// this method call will only return an array with the instances created for the elements that matched '.tooltip2' because that's the latest initializing call.
var instances = $.tooltipster.instancesLatest();
</pre>
</section>
<section id="usecases">
<h2>Common use cases <a href="#">⇑</a></h2>
<ul>
<li><a href="#styling">Styling your tooltips with a custom look</a></li>
<li><a href="#apicontent">Updating a tooltip's content</a></li>
<li><a href="#ajax">Using AJAX to generate your tooltip content</a></li>
<li><a href="#sides">Forcing or disabling sides</a></li>
<li><a href="#triggers">Opening and closing a tooltip: the built-in triggers</a></li>
<li><a href="#openclose">Opening and closing a tooltip: the method calls</a></li>
<li><a href="#positioning">Achieving custom positioning</a></li>
<li><a href="#htmlcontentalt">Alternative ways of setting HTML content</a></li>
<li><a href="#data-attributes">Specifying options through data-attributes</a></li>
<li><a href="#formatting">Working with data sets</a></li>
<li><a href="#status">Status: getting information about the tooltip</a></li>
<li><a href="#object-oriented">Object-oriented Tooltipster</a></li>
<li><a href="#multiple">Using multiple tooltips on a single element</a></li>
<li><a href="#delegation">Dynamic live binding on newly created elements</a></li>
<li><a href="#events">Event-driven Tooltipster</a></li>
<li><a href="#plugins">Tooltipster's plugin system</a></li>
<li><a href="#nested">Nested tooltips</a></li>
<li><a href="#grouped">Grouped tooltips</a></li>
<li><a href="#svg">Tooltips on SVG elements</a></li>
<li><a href="#accessibility">Making tooltips accessible to persons with disabilities</a></li>
<li><a href="#community">Community submitted use cases</a></li>
</ul>
<h3 id="styling">Styling your tooltips with a custom look <a href="#usecases">⇑</a></h3>
<p>Tooltipster makes it very easy to go from one of the packaged themes and customize a few properties of your choice. To do so, we recommend that you create a so-called "secondary theme" which will override some properties of a packaged theme.</p>
<p>Create a new css file and include it in your page. Inside the file, declare your customized rules like this:</p>
<pre class="prettyprint lang-css">
/* This is how you would create a custom secondary theme on top of tooltipster-noir: */
.tooltipster-sidetip.tooltipster-noir.tooltipster-noir-customized .tooltipster-box {
background: grey;
border: 3px solid red;
border-radius: 6px;
box-shadow: 5px 5px 2px 0 rgba(0,0,0,0.4);
}
.tooltipster-sidetip.tooltipster-noir.tooltipster-noir-customized .tooltipster-content {
color: blue;
padding: 8px;
}</pre>
<p>For your secondary theme to be applied, provide an array of themes instead of just one. You may even provide more than two themes if you create a secondary theme to your secondary theme! In other words, this allows sub-themes, sub-sub-themes, etc. for your tooltips.</p>
<pre class="prettyprint">
$('.tooltip').tooltipster({
theme: ['tooltipster-noir', 'tooltipster-noir-customized']
});</pre>
<p>Changing the size of the arrow might be the only challenging customization but it's doable! We encourage you to see what we have done in the different themes and work from there.</p>
<h3 id="apicontent">Updating a tooltip's content <a href="#usecases">⇑</a></h3>
<p>It's easy as pie to update a tooltip's content - whether it's open or closed. Depending on your selector, you can update multiple tooltips at once or just one:</p>
<pre class="prettyprint">
$('#myelement').tooltipster('content', 'My new content');
// or when you have the instance of the tooltip:
instance.content('My new content');
</pre>
<p>Tooltipster plays a subtle animation when the content changes. This animation may be changed or disabled through the <span class="code">updateAnimation</span> option.</p>
<h3 id="ajax">Using AJAX to generate your tooltip content <a href="#usecases">⇑</a></h3>
<p>Tooltipster gives you the ability to fire a custom function when a tooltip is initialized (<span class="code">functionInit</span>), but also every time the tooltip is about to open (<span class="code">functionBefore</span>), when it has opened (<span class="code">functionReady</span>) or after it has closed (<span class="code">functionAfter</span>).</p>
<p>One great use for this is to grab dynamic content for your tooltips via AJAX. In this example we will use <span class="code">functionBefore</span> to load data the first time the tooltip is opened. Until the data has been loaded, we will display a "Loading..." notification:</p>
<pre class="prettyprint">
$('.tooltip').tooltipster({
content: 'Loading...',
// 'instance' is basically the tooltip. More details in the "Object-oriented Tooltipster" section.
functionBefore: function(instance, helper) {
var $origin = $(helper.origin);
// we set a variable so the data is only loaded once via Ajax, not every time the tooltip opens
if ($origin.data('loaded') !== true) {
$.get('http://example.com/ajax.php', function(data) {
// call the 'content' method to update the content of our tooltip with the returned data.
// note: this content update will trigger an update animation (see the updateAnimation option)
instance.content(data);
// to remember that the data has been loaded
$origin.data('loaded', true);
});
}
}
});</pre>
<p>In addition to this, you may provide a function as the callback argument of the open/close methods. If the tooltip is already in the state you are asking for (open & stable/closed), the callback is executed immediately. Please note that if the open/close action is somehow cancelled before it has completed its animation, the callback function will never be called.</p>
<pre class="prettyprint">
$(document).ready(function() {
$('.tooltip').tooltipster();
$('#example').tooltipster('open', function(instance, helper) {
alert('The tooltip is now fully shown. Its content is: ' + instance.content());
});
$(window).keypress(function() {
$('#example').tooltipster('close', function(instance, helper) {
alert('The tooltip is now fully hidden');
});
});
});
</pre>
<h3 id="sides">Forcing or disabling sides <a href="#usecases">⇑</a></h3>
<p>Let's hover a little on how the <span class="code">side</span> option works.<br />You have two options: provide either a string, like <span class="code">side: 'top'</span>, or an array of strings, like <span class="code">side: ['top', 'bottom']</span> for example.</p>
<h4>What happens when I provide a string, like <span class="code">'top'</span> ?</h4>
<p>This tells Tooltipster that you'd prefer the tooltip to be above the tooltipped element, but allows the tooltip to be positioned differently if need be.<br />This means that if there is not enough space on top for your tooltip, the other sides may be used a fallbacks. Here is the order of fallbacks, depending on what side you chose:</p>
<pre class="prettyprint">
// ... is the same as ...
'top' => ['top', 'bottom', 'right', 'left']
'bottom' => ['bottom', 'top', 'right', 'left']
'right' => ['right', 'left', 'top', 'bottom']
'left' => ['left', 'right', 'top', 'bottom']</pre>
<h4>When should I provide an array instead ?</h4>
<p>There are two reasons to do so.</p>
<p>Firstly, if you are not happy with the four default orders of sides fallbacks. For example you might want: <span class="code">side: ['top', 'left', 'bottom', 'right']</span>.</p>
<p>Secondly if you want to disable totally one or more sides. For example, with <span class="code">['top', 'right', 'left']</span>, the tooltip will never be positioned on the bottom. With <span class="code">['right']</span>, the tooltip will always be on the right, even if it has to overflow the document.</p>
<h3 id="triggers">Opening and closing a tooltip: the built-in triggers <a href="#usecases">⇑</a></h3>
<h4 id="triggers_predefined">Predefined behaviors</h4>
<p>The easiest way to set when a tooltip should open or close is to set the <span class="code">trigger</span> option to one of the two predefined values: <span class="code">'hover'</span> or <span class="code">'click'</span>.</p>
<p>You can see how they perform with our demos at the top of this page. Note that these two behaviors also apply to their touch-gesture equivalents.</p>
<p>If you feel that you need a different behavior or more flexibility, set the <span class="code">trigger</span> option to <span class="code">'custom'</span> and read on.</p>
<h4 id="triggers_custom">Creating a customized behavior</h4>
<p>There are many actions that may cause a tooltip to open or close, should we want to. These action are called "open triggers" and "close triggers".</p>
<p>Tooltipster supports a number of them out of the box, the list lies below. Plugins may provide support for additional triggers.</p>
<h5>1) Open triggers</h5>
<p><span class="code">click</span> When the origin is clicked by a mouse.</p>
<p><span class="code">mouseenter</span> When a mouse comes over the origin. The <span class="code">delay</span> option is taken into account as the delay before opening.</p>
<p><span class="code">touchstart</span> When the origin is pressed on a touch screen. The <span class="code">delayTouch</span> option is taken into account as the delay before opening.</p>
<p><span class="code">tap</span> When the origin is tapped (ie pressed and then released) on a touch screen.</p>
<h5>2) Close triggers</h5>
<p><span class="code">click</span> When a mouse click happens anywhere in the page. However, if the <span class="code">interactive</span> option is set to <span class="code">true</span>, a click happening inside the tooltip will not close it.</p>
<p><span class="code">mouseleave</span> When the mouse goes away from the origin. The <span class="code">delay</span> option is taken into account as the delay before closing.</p>
<p><span class="code">originClick</span> When the origin is clicked by a mouse. This mimics a behavior that browsers usually have and is meant to be used with the <span class="code">mouseenter</span> open trigger.</p>
<p><span class="code">scroll</span> When scrolling happens in the window or in a scrollable area which is a parent of the origin.</p>
<p><span class="code">tap</span> When the finger taps (ie presses and releases) anywhere in the touch screen.</p>
<p><span class="code">touchleave</span> When the finger is removed from the touch screen or if the interaction was stopped by the device. The <span class="code">delayTouch</span> option is taken into account as the delay before closing.</p>
<h5>Examples</h5>
<p>Once that the <span class="code">trigger</span> option is set to <span class="code">'custom'</span>, all open and close triggers are disabled by default. Use the <span class="code">triggerOpen</span> and <span class="code">triggerClose</span> options to reactivate the triggers of your choice, as shown below.</p>
<p>Let's assume that you'd like a tooltip to open upon mouse hovering, but close only when either a mouse click or scrolling happens. Write this:</p>
<pre class="prettyprint">
$('#example').tooltipster({
trigger: 'custom',
triggerOpen: {
mouseenter: true
},
triggerClose: {
click: true,
scroll: true
}
});</pre>
<p>This works well on desktops but not on touch devices, because we have not enabled any touch triggers. Let's fix this by enabling the <span class="code">touchstart</span> and <span class="code">tap</span> triggers as well:</p>
<pre class="prettyprint">
$('#example').tooltipster({
trigger: 'custom',
triggerOpen: {
mouseenter: true,
touchstart: true
},
triggerClose: {
click: true,
scroll: true,
tap: true
}
});</pre>
<h5>« Ok but wait... then what do the predefined 'hover' and 'click' behaviors do exactly? »</h5>
<p>Good question. Setting <span class="code">trigger: 'hover'</span> or <span class="code">trigger: 'click'</span> is nothing but a shorthand.</p>
<p>Having <span class="code">trigger: 'hover'</span> is actually the same as having:</p>
<pre class="prettyprint">
$('#example').tooltipster({
trigger: 'custom',
triggerOpen: {
mouseenter: true,
touchstart: true
},
triggerClose: {
mouseleave: true,
originClick: true,
touchleave: true
}
});</pre>
<p>And having <span class="code">trigger: 'click'</span> is the same as having:</p>
<pre class="prettyprint">
$('#example').tooltipster({
trigger: 'custom',
triggerOpen: {
click: true,
tap: true
},
triggerClose: {
click: true,
tap: true
}
});</pre>
<h3 id="openclose">Opening and closing a tooltip: the method calls</h3>
<p>In parallel to (or instead of) using the built-in triggers, you may want to open/close a tooltip yourself on a specific occasion.</p>
<p>To achieve this, Tooltipster has the <span class="code">open</span> and <span class="code">close</span> methods. Both of them may receive an optional callback argument, which represents a function you'd like to be called when the tooltip is done animating.</p>
<p>Here's an example of how you could launch a specific tooltip on page load and close it when any key on your keyboard is pressed.</p>
<pre class="prettyprint">
<span id="example" class="tooltip" title="My tooltip content">Example</span>
</pre>
<pre class="prettyprint">
$(document).ready(function() {
// first on page load, initialize all tooltips
$('.tooltip').tooltipster();
// then immediately open the tooltip of the element named "example"
$('#example').tooltipster('open');
// as soon as a key is pressed on the keyboard, close the tooltip.
$(window).keypress(function() {
$('#example').tooltipster('close');
});
});
</pre>
<h3 id="positioning">Achieving custom positioning <a href="#usecases">⇑</a></h3>
<p>This is for advanced users who are comfortable with Javascript and CSS.</p>
<p>When the tooltip needs to be positioned or repositioned, Tooltipster runs all kinds of tests to find the best option. But before the computed position is applied, you have the option to edit it using the <span class="code">functionPosition</span> option.</p>
<p>When you provide custom coordinates for the tooltip and its arrow, they have to be relative to the top and left edges of the viewport. This makes custom positioning in Tooltipster both very fast and very simple. Doing your calculations, <a href="https://developer.mozilla.org/fr/docs/Web/API/Element/getBoundingClientRect" target="_blank"><span class="code">element.getBoundingClientRect</span></a> will become your new best friend, so make sure you check it out.</p>
<p>Your <span class="code">functionPosition</span> callback is called with three parameters. The first two ones are <span class="code">instance</span> and a <span class="code">helper</span>, <a href="#callback_arguments">as usual</a>. The third argument is an object with the position properties proposed by Tooltipster, that you may edit. <b>You must return</b> the edited third argument for the changes to get applied.</p>
<p><span class="code">helper.mode</span> (will be <span class="code">'natural'</span> or <span class="code">'constrained'</span>) indicates if Tooltipster adapted the size of the tooltip for it to fit in.</p>
<p><span class="code">helper.tooltipClone</span> is a clone of the tooltip which exists in the DOM at the time the callback is called.</p>
<p><span class="code">helper.geo</span> includes useful pre-calculated data about the page layout. It will help you avoid putting the tooltip accidentally off screen, for example. This object is in this form:</p>