forked from jsplumb/jsplumb
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathcontent.html
3964 lines (3630 loc) · 184 KB
/
content.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
<html>
<head>
<title>jsPlumb 1.4.0 - documentation</title>
<link rel="stylesheet" href="jsPlumbDoc.css">
<link href='http://fonts.googleapis.com/css?family=Open+Sans' rel='stylesheet' type='text/css'>
</head>
<body>
<div class="content">
<div class="section">
<h3><a id="summary">Summary</a></h3>
jsPlumb allows you to connect elements on the screen using SVG, Canvas or VML, depending on the capabilities of the browser.
<p>
It can be used with jQuery, MooTools or YUI3 (or another library of your choice if you feel like implementing an adapter for it).
</p>
<h5>Browser Compatibility</h5>
<p>jsPlumb 1.4.0 runs on everything from IE6 up. There are some caveats, though, because of various browser/library bugs:</p>
<ul>
<li class="bullet">jQuery 1.6.x and 1.7.x have a bug in their SVG implementation for IE9 that causes hover events to not get fired.</li>
<li class="bullet">Safari 5.1 has an SVG bug that prevents mouse events from being passed through the transparent area of an SVG element (Safari 6.x does not seem to have the same problem)</li>
<li class="bullet">MooTools has a bug when using SVG in Firefox 11</li>
</ul>
</div>
<div class="section">
<h3><a id="changes">Changes between 1.4.0 and 1.3.16</a></h3>
<h5>Backwards Compatibility</h5>
<ul>
<li class="bullet">Flowchart connectors do not support minStubLength anymore. Use <strong>stub</strong>.</li>
<li class="bullet">Perimeter anchor names now have a capitalised first letter: 'circle' is now 'Circle', for instance. This brings their naming convention
into line with the various other names used throughout jsPlumb.</li>
</ul>
<h5>New Features</h5>
<ul>
<li class="bullet">jsPlumb now registers as an AMD module if an AMD loader is found in the page. Two registrations are made:
<strong>jsplumb</strong> for the static instance, and <strong>jsplumbinstance</strong></li>
<li class="bullet">internally, all Connectors are now composed of a set of Segments, of which there are three types - Bezier, Straight, and Arc. </li>
<li class="bullet">setType/addType methods now support a parameter object</li>
<li class="bullet">added 'remove' function to jsPlumb: removes an element from the DOM and its associated
Endpoints and their Connections.</li>
<li class="bullet">flowchart connectors support a 'cornerRadius' parameter, which allows you
to specify a radius for curved corners. default is 5 pixels.</li>
<li class="bullet">Straight connectors now support the 'stub' parameter.</li>
<li class="bullet">added 'addClass' and 'removeClass' methods to Connection and Endpoint, and to the return value of
jsPlumb.select and jsPlumb.selectEndpoints.</li>
<li class="bullet">add 'hoverClass' member to jsPlumb; this is set when hovering over a Connection or Endpoint. default is
'_jsPlumb_hover'.</li>
</ul>
<h5>Issues Resolved</h5>
<ul>
<li><strong>283</strong> - Firefox: SVG line repaint issues</li>
<li><strong>289</strong> - JS errors after dropping a target endpoint on a source</li>
<li><strong>290</strong> - setId doesn't work.</li>
<li><strong>292</strong> - fire connectionDrag event when dragging a new connection.</li>
<li><strong>296</strong> - documentation refers to 'removeEveryEndpoint' instead of 'deleteEveryEndpoint'.</li>
<li><strong>297</strong> - cannot use connection types</li>
<li><strong>300</strong> - typo in unmakeSource</li>
<li><strong>302</strong> - removeAllEndpoints not functioning correctly</li>
<li><strong>303</strong> - mixture of continuous and static anchors causes paint issues</li>
</ul>
<h5>Miscellaneous</h5>
<ul>
<li class="bullet">jsPlumb overlay class and custom overlay class now set correctly on VML arrow overlays</li>
<li class="bullet">couple of fixes for jsPlumbUtil merge function</li>
</ul>
The full changelog can be found on GitHub <a href="https://github.com/sporritt/jsPlumb/blob/master/changelog.txt" target="_blank">here</a>.
</div>
<div class="section">
<h3><a id="init">Setup</a></h3>
<h4><a id="imports">Required Imports</a></h4>
<h4>jQuery</h4>
<ul>
<li class="bullet">jQuery 1.3.x or higher.</li>
<li class="bullet">jQuery UI 1.7.x or 1.8.x (if you wish to support drag and drop). Note that if you use
jQuery 1.8.x you must use jQuery UI 1.8.22 or higher.</li>
</ul>
<div class="code">
<pre><script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.8.1/jquery.min.js"></script>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8.23/jquery-ui.min.js"></script>
<script type="text/javascript" src="PATH_TO/jquery.jsPlumb-1.4.0-all-min.js "></script></pre>
</div>
<h4>MooTools</h4>
<ul>
<li class="bullet">MooTools Core 1.2.4 or higher. jsPlumb has been tested with 1.2.4 and 1.3.3.</li>
<li class="bullet">Drag.Move from MooTools More 1.2.4.4 or higher (if you wish to support drag and drop).</li>
</ul>
<div class="code">
<pre><script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/mootools/1.3.3/mootools-yui-compressed.js"></script>
<script type="text/javascript" src="PATH_TO_MOO_TOOLS_MORE_1_3_2_1"></script>
<script type="text/javascript" src="PATH_TO/mootools.jsPlumb-1.4.0-all-min.js "></script></pre>
</div>
<h4>YUI3</h4>
<ul>
<li class="bullet">YUI 3.3.x. jsPlumb has been tested on 3.3.0 only; it is possible other 3.x.x versions will work.</li>
</ul>
<div class="code">
<pre><script type="text/javascript" src="http://yui.yahooapis.com/3.3.0/build/simpleyui/simpleyui-min.js"></script>
<script type="text/javascript" src="PATH_TO/yui.jsPlumb-1.4.0-all-min.js "></script></pre>
</div>
<h4><a id="renderMode">Render Mode</a></h4>
jsPlumb can use SVG or VML to render the various objects it adds to the display. Most modern browsers support SVG; IE<9 browsers supports only VML.
<p>
By default, jsPlumb attempts to use <strong>jsPlumb.SVG</strong>falling back to <strong>jsPlumb.VML</strong> if the
browser is IE<9. You can change the render mode by making this call:
</p>
<div class="code">
<pre>jsPlumb.setRenderMode(jsPlumb.SVG);</pre>
</div>
if, for some reason, you set the render mode to be <strong>jsPlumb.VML</strong> but you're in any browser other than IE, jsPlumb will use SVG. The only real reason to use
this method is when you're in IE9 and, for some reason, you want to use VML.
<p>
The <strong>jsPlumb.setRenderMode</strong> method returns you the render mode that jsPlumb actually ended up setting. Valid values for setRenderMode are:
</p>
<ul>
<li class="bullet">jsPlumb.SVG</li>
<li class="bullet">jsPlumb.VML</li>
</ul>
<h4><a id="initializing">Initializing jsPlumb</a></h4>
You should not start making calls to jsPlumb until the DOM has been initialized - perhaps no surprises there. With YUI, though, the asynchronous
nature of the script loading process means that you are not guaranteed that jsPlumb is ready as soon as the DOM is. To handle this,
you should bind to the "ready" event on jsPlumb (or the instance of jsPlumb you are working with):
<div class="code">
<pre>jsPlumb.bind("ready", function() {
...
// your jsPlumb related init code goes here
...
});
</pre>
</div>
There's a helper method that can save you a few precious characters:
<div class="code">
<pre>jsPlumb.ready(function() {
...
// your jsPlumb related init code goes here
...
});
</pre>
</div>
<p>
For jQuery and MooTools you do not actually need to do this; by the time the DOM ready event is fired in each of those libraries you can be sure
all the JS we need has been loaded. But in terms of explicitly calling out that you are waiting for jsPlumb, it seems like a good practice to bind to the "ready" event.
</p>
<p>
If you bind to the "ready" event after jsPlumb has already been initialized, your callback will be executed immediately.
</p>
<h4><a id="multipleInstances">Multiple jsPlumb instances</a></h4>
jsPlumb is registered on the browser's Window by default, providing one static instance
for the whole page to use. Should you need to, though, you can instantiate independent
instances of jsPlumb, using the <strong>getInstance</strong> method, for example:
<div class="code">
<pre>
var firstInstance = jsPlumb.getInstance();
</pre>
</div>
The variable 'firstInstance' can now be treated exactly as you would treat the 'jsPlumb' variable - you can set
defaults, call the connect method, whatever:
<div class="code">
<pre>
firstInstance.importDefaults({
Connector : [ "Bezier", { curviness: 150 } ],
Anchors : [ "TopCenter", "BottomCenter" ]
});
firstInstance.connect({source:"element1", target:"element2", scope:"someScope" });
</pre>
</div>
<strong>getInstance</strong> optionally takes an object that provides the defaults:
<div class="code">
<pre>
var secondInstance = jsPlumb.getInstance({
PaintStyle:{ lineWidth:6, strokeStyle:"#567567", outlineColor:"black", outlineWidth:1 },
Connector:[ "Bezier", { curviness: 30 } ],
Endpoint:[ "Dot", { radius:5 } ],
EndpointStyle : { fillStyle: "#567567" },
Anchor : [ 0.5, 0.5, 1, 1 ]
});
secondInstance.connect({ source:"element4", target:"element3", scope:"someScope" });
</pre>
</div>
<h4><a id="zIndex">Z-index Considerations</a></h4>
<p>
You need to pay attention to the z-indices of the various parts of your UI when
using jsPlumb, in particular to ensure that the elements that jsPlumb adds to
the DOM do not overlay other parts of the interface.
</p>
<p>
jsPlumb adds an element to the DOM for each Endpoint, Connector and Overlay. So
for a connection having visible Endpoints at each end and a label in the middle,
jsPlumb adds four elements to the DOM. The actual elements it adds depend on the
renderer in use (Canvas/SVG/VML).
</p>
<p>
To help you organise z-indices correctly, jsPlumb adds a CSS class to each type of
element it adds. They are as follows:
</p>
<table style="color:black;width:70%;font-size:90%;">
<tr><td><strong>type of element</strong></td><td><strong>class added</strong></td></tr>
<tr><td>Endpoint</td><td>_jsPlumb_endpoint</td></tr>
<tr><td>Connector</td><td>_jsPlumb_connector</td></tr>
<tr><td>Overlay</td><td>_jsPlumb_overlay</td></tr>
</table>
<p>
In addition, whenever the mouse is hovering over an Endpoint or Connection, that component is
assigned the class <strong>_jsPlumb_hover</strong>.
</p>
<h4><a id="containerDefault">Where does jsPlumb add elements?</a></h4>
<p>
It's important to understand where in the DOM jsPlumb will add any elements it creates,
as it has a bearing on the markup you can use with jsPlumb.
</p>
<p>
Prior to 1.3.0, jsPlumb added everything to the end of the <em>body</em> element. This
has the advantage of being the most flexible arrangement in terms of supporting what
elements can be connected, but in certain use cases produced unexpected results. Consider
the arrangement where you have some connected elements in a tab: you would
expect jsPlumb to add elements inside the tab, so that when the user switches tabs and
the current one is hidden, all the jsPlumb stuff is hidden too. But when the elements are
on the body, this does not happen!
</p>
<p>
For this reason, from 1.3.0 onwards, jsPlumb's default behaviour is to attach Endpoint elements to the parent
of the element the Endpoint is attached to (<strong>not</strong> the actual element
the Endpoint is attached to), and to attach Connector elements to the parent of
the source Endpoint in the Connection. This results in all the elements of the
Connection being siblings inside the same parent node, which jsPlumb requires, for
various reasons arising from the trade off between doing lots of maths and the
performance of the whole thing.
</p>
<p>
In general, the default behaviour means that you cannot do things like this:
</p>
<div class="code">
<pre>
<body>
<div id="container0">
<div id="node0"></div>
</div>
<div id="container1">
<div id="node1"></div>
</div>
</body>
<script type="text/javascript">
var e0 = jsPlumb.addEndpoint("node0"),
e1 = jsPlumb.addEndpoint("node1");
jsPlumb.connect({ source:e0, target:e1 });
</script>
</pre>
</div>
<p>
because the elements created for 'e0' and 'e1' would have different parent nodes, and an attempt
to make a Connection between them would not work. For the example just given, you would need to
register the Endpoints on the 'container' divs (and then quite possibly throw away the 'node' divs):
</p>
<div class="code">
<pre>
<body>
<div id="container0">
</div>
<div id="container1">
</div>
</body>
<script type="text/javascript">
var e0 = jsPlumb.addEndpoint("container0"),
e1 = jsPlumb.addEndpoint("container1");
jsPlumb.connect({ source:e0, target:e1 });
</script>
</pre>
</div>
now 'e0' and 'e1' have the same parent - the <em>body</em> element.
<p>Remember that you can use the <strong>anchor</strong> parameter to an <strong>addEndpoint</strong>
call to specify where on an element you want an Endpoint to appear. Used in conjunction with
CSS classes (discussed below), you can have an Endpoint on top of some element wherever you like.
</p>
<p><strong>Note regarding the drawEndpoints option on jsPlumb.connect</strong>: with the default behaviour, jsPlumb uses the offsetParent of
the source endpoint in a connection to make final adjustments to the position of a connector. When drawEndpoints is set to false, there is no
offsetParent of the source endpoint because it is not visible. If your connection lies inside some container other than the document body,
the connector will not be able to take that container's offset into account, and will most likely not be in the right place. You should either
use the "Blank" endpoint when you don't want to see one, or instruct jsPlumb to attach everything to the document body (see below).
</p>
<h4><a id="overrideContainer">Overriding the default behaviour</a></h4>
<p>
From version 1.3.3, the <strong>container</strong> concept was reintroduced into jsPlumb, because there are use cases in which the default behaviour makes it difficult or impossible to build the UI you want. You can instruct jsPlumb to use some element as the parent of everything jsPlumb adds to the UI through usage of the <strong>jsPlumb.Defaults.Container</strong> property, or you can set a <strong>container</strong> parameter on calls to <strong>addEndpoint</strong> or <strong>connect</strong> (if this is set and a default is also set, this default value is actually used. This may seem counter-intuitive, and could of course be changed if there is feedback from the community that this would be a good idea). Some examples:
</p>
Set a container to use as the default container, using a jQuery selector (you can supply MooTools/YUI selectors if that's the library you're using), and then add an Endpoint. The canvas (or SVG/VML element) created will be a child of the document body:
<div class="code">
<pre>
jsPlumb.Defaults.Container = $("body");
...
jsPlumb.addEndpoint(someDiv, { endpoint options });
</pre>
</div>
Set a container to use as the default container, using an element id,
and then connect two elements. The elements created in this example will be children of the element with id "containerId":
<div class="code">
<pre>
jsPlumb.Defaults.Container = "containerId";
...
jsPlumb.connect({ source:someDiv, target:someOtherDiv });
</pre>
</div>
Pass a container to use into a jsPlumb.connect call, using a selector. The elements created in this example will be children of the element with id "containerId":
<div class="code">
<pre>
jsPlumb.connect({ source:someDiv, target:someOtherDiv, container:$("#containerId") });
</pre>
</div>
Pass a container to use into a jsPlumb.addEndpoint call, using an element id. The element created in this example will be a child of the element with id "containerId":
<div class="code">
<pre>
jsPlumb.addEndpoint(someDiv, { ..., container:"containerId" });
</pre>
</div>
<h4><a id="elementDragging">Element Dragging</a></h4>
A common feature of interfaces using jsPlumb is that the elements are draggable. Unless you absolutely need to configure this behaviour using your library's underlying method, you should use <strong>jsPlumb.draggable(...)</strong>:
<div class="code">
<pre>jsPlumb.draggable("elementId");</pre>
</div>
You can also pass a selector from your library in to this method:
<div class="code">
<pre>jsPlumb.draggable($(".someClass"));</pre>
</div>
This method is just a wrapper for the underlying library's draggable functionality, and there is a two-argument version in which the second argument is passed down to the underlying library. A common requirement when using jQuery, for instance, is to set the containment of elements that you are making draggable. Here's how you would tell jsPlumb to initialise some set of elements to be draggable but only inside their parent:
<div class="code">
<pre>jsPlumb.draggable($(".someClass"), {
containment:"parent"
});</pre>
</div>
<h4><a id="draggingNested">Dragging nested elements</a></h4>
jsPlumb takes nesting into account when handling draggable elements. For example, say you have this markup:
<div class="code">
<pre>
<div id="container">
<div class="childType1"></div>
<div class="childType2"></div>
</div>
</pre>
</div>
..and then you connect one of those child divs to something, and make "container" draggable:
<div class="code">
<pre>
jsPlumb.connect({
source:$("#container .childType1"),
target:"somewhere else"
});
jsPlumb.draggable("container");
</pre>
</div>
Now when you drag "container", jsPlumb will have noticed that there are nested elements that have connections, and they will be updated. Note that the order of operations is not important here: if "container" was already draggable when you connected one of its children to something, you would get the same result.
<h4><a id="nestedElementOffsets">Nested Element offsets</a></h4>
For performance reasons, jsPlumb caches the offset of each nested element relative to its draggable ancestor. If you
make changes to the draggable ancestor that will have resulted in the offset of one or more nested elements changing,
you need to tell jsPlumb about it, using the <strong>recalculateOffsets</strong> function.
<p>
Consider the example from
before, but with a change to the markup after initializing everything:
</p>
<div class="code">
<pre>
<div id="container">
<div class="header" style="height:20px;background-color:blue;">header</div>
<div class="childType1"></div>
<div class="childType2"></div>
</div>
</pre>
</div>
..and then you connect one of those child divs to something, and make "container" draggable:
<div class="code">
<pre>
jsPlumb.connect({
source:$("#container .childType1"),
target:"somewhere else"
});
jsPlumb.draggable("container");
...
$("#container .header).hide(); // hide the header bar. this will alter the offset of the other child elements...
jsPlumb.recalculateOffsets("container"); // tell jsPlumb that the internal dimensions have changed.
// you can also use a selector, eg $("#container")
</pre>
</div>
</div>
<div class="section">
<h3><a id="jsPlumbBasics">Basic Concepts</a></h3>
jsPlumb is all about connecting things together, so the core abstraction in jsPlumb is the <strong>Connection</strong> object, which is itself
broken down into these four concepts:
<ul>
<li class="bullet"><strong>Anchor</strong> - a location, relative to an element's origin, at which an Endpoint can exist. You do not create these yourself; you
supply hints to the various jsPlumb functions, which create them as needed. They have no visual representation; they are a logical position only. Anchors can be referenced by name, for the Anchors that jsPlumb ships with, or a four element array describing [ x, y, x orientation, y orientation ].
See the <a href="#anchors">anchors</a> section for more detail.<br/><br/></li>
<li class="bullet"><strong>Endpoint</strong> - the visual representation of one end of a Connection. You can create and attach these to elements yourself, which you are required to do to support drag and drop, or have jsPlumb create them when creating a Connection programmatically using jsPlumb.connect(...). You can also join two Endpoints programmatically, by passing them as arguments to jsPlumb.connect(...).<br/><br/></li>
<li class="bullet"><strong>Connector</strong> - the visual representation of the line connecting two elements in the page. jsPlumb has four types of these
available as defaults - a Bezier curve, a straight line, 'flowchart' connectors and 'state machine' connectors. You do not interact with Connectors;
you just specify definitions of them when you need to - see <a href="#definitions">Connector, Endpoint & Overlay Definitions</a> <br/><br/></li>
<li class="bullet"><strong>Overlay</strong> - a UI component that is used to decorate a Connector, such as a Label, Arrow, etc.<br/><br/></li>
</ul>
<p>One Connection is made up of two Endpoints, a Connector, and zero or more Overlays working together to join two elements.</p>
<p>jsPlumb's public API exposes only Connection and Endpoint, handling the creation and configuration of everything else internally. But you still need to be across the concepts encapsulated by Anchor, Connector and Overlay.
</p>
</div>
<div class="section">
<h3><a id="anchors">Anchors</a></h3>
An Anchor models the notion of where on an element a Connector should connect. There are four main types of Anchors:
<ul>
<li class="bullet">'Static' anchors - these are fixed to some point on an element and do not move. They can be specified using a string to
identify one of the defaults that jsPlumb ships with, or an array describing the location (see below)<br/><br/></li>
<li class="bullet">'Dynamic' anchors - these are lists of Static anchors from which jsPlumb picks the most appropriate one each time a Connection
is painted. The algorithm used to determine the most appropriate anchor picks the one that is closest to the center of the other element in
the Connection. A future version of jsPlumb might support a pluggable algorithm to make this decision.<br/><br/></li>
<li class="bullet">'Perimeter' anchors - these are anchors that follow the perimeter of some given shape. They are, in essence, Dynamic
anchors whose locations are chosen from the perimeter of the underlying shape.<br/><br/></li>
<li class="bullet">'Continuous' anchors - These anchors are not fixed to any specific location; they are assigned to one of
the four faces of an element depending on that element's orientation to the other element in the associated Connection. Continuous anchors are slightly
more computationally intensive than Static or Dynamic anchors because jsPlumb is required to calculate the position of every Connection during a paint cycle,
rather than just Connections belonging to the element in motion. <br/><br/></li>
</ul>
<h4><a id="staticAnchors">Static Anchors</a></h4>
jsPlumb has nine default anchor locations you can use to specify where the Connectors connect to elements: these are the four corners of an element,
the center of the element, and the midpoint of each edge of the element:
<ul>
<li class="bullet">TopCenter (also aliased as Top)</li>
<li class="bullet">TopRight</li>
<li class="bullet">RightMiddle (also aliased as Right)</li>
<li class="bullet">BottomRight</li>
<li class="bullet">BottomCenter (also aliased as Bottom)</li>
<li class="bullet">BottomLeft</li>
<li class="bullet">LeftMiddle (also aliased as Left)</li>
<li class="bullet">TopLeft</li>
</ul>
Each of these string representations is just a wrapper around the underlying array-based syntax [x, y, dx, dy], where x and y are coordinates in the interval [0,1] specifying the position of the
anchor, and dx and dy are coordinates in the interval [-1, 1] specifying the orientation of the curve incident to the anchor. For example, [0, 0.5, -1, 0] defines a "LeftCenter" anchor with a connector curve that emanates leftward from the anchor. Similarly, [0.5, 0, 0, -1] defines a "CenterTop" anchor with a connector curve emanating upwards.
<div class="code">
<pre>
jsPlumb.connect({...., anchor:"BottomCenter", ... });
</pre>
</div>
is identical to:
<div class="code">
<pre>
jsPlumb.connect({...., anchor:[ 0.5, 1, 0, 1 ], ... });
</pre>
</div>
<h5>Anchor Offsets</h5>
In addition to supplying the location and orientation of an anchor, you can optionally supply two more parameters that define an offset in pixels from the given location. Here's the anchor specified above, but with a 50 pixel offset below the element in the y axis:
<div class="code">
<pre>
jsPlumb.connect({...., anchor:[ 0.5, 1, 0, 1, 0, 50 ], ... });
</pre>
</div>
<h4><a id="dynamicAnchors">Dynamic Anchors</a></h4>
These are Anchors that can be positioned in one of a number of locations, choosing the one that is most appropriate each time something moves or is painted in the UI.
<p>
There is no special syntax for creating a DynamicAnchor; you just provide an array of individual Static Anchor specifications, eg:
</p>
<div class="code">
<pre>
var dynamicAnchors = [ [ 0.2, 0, 0, -1 ], [ 1, 0.2, 1, 0 ],
[ 0.8, 1, 0, 1 ], [ 0, 0.8, -1, 0 ] ];
jsPlumb.connect({...., anchor:dynamicAnchors, ... });
</pre>
</div>
<h4> Default Dynamic Anchor</h4>
jsPlumb provides a dynamic anchor called "AutoDefault" that chooses from TopCenter, RightMiddle, BottomCenter and LeftMiddle:
<div class="code">
<pre>jsPlumb.connect({...., anchor:"AutoDefault", ... });</pre>
</div>
<h4> Location Selection</h4>
The algorithm that decides which location to choose just calculates which location is closest to the center of the
other element in the Connection. It is possible that future versions of jsPlumb could support more sophisticated choice algorithms, if the need arose.
<h4>Draggable Connections</h4>
Dynamic Anchors and Draggable Connections can interoperate: jsPlumb locks the position of a dynamic anchor when you start to drag a connection from it,
and unlocks it once the connection is either established or abandoned. At that point you may see the position of the dynamic anchor change, as jsPlumb
optimises the connection. <p>You can see this behaviour in the <a href="../jquery/draggableConnectorsDemo.html" target="_blank">draggable connections</a> demonstration, when
you drag a connection from the blue endpoint on window 1 to the blue endpoint on window 3 - the connection is established and then window 1's blue
endpoint jumps down to a location that is closer to window 3.</p>
<h4><a id="perimeterAnchors">Perimeter Anchors</a></h4>
These are a form of Dynamic anchor in which the anchor locations are chosen from the perimeter of some given shape. jsPlumb
supports six shapes:
<ul>
<li class="bullet">Circle</li>
<li class="bullet">Ellipse</li>
<li class="bullet">Triangle</li>
<li class="bullet">Diamond</li>
<li class="bullet">Rectangle</li>
<li class="bullet">Square</li>
</ul>
'Rectangle' and 'Square', are not, strictly speaking, necessary, since rectangular shapes are the norm in a web page. But they
are included for completeness.
<div class="code">
<pre>
jsPlumb.addEndpoint("someElement", {
endpoint:"Dot",
anchor:[ "Perimeter", { shape:"Circle" } ]
});
</pre>
</div>
In this example our anchor will travel around the path inscribed by a circle whose diameter is the width and height of the
underlying element. Note that the 'Circle' shape is therefore identical to 'Ellipse', since it is assumed the underlying
element will have equal width and height, and if it does not, you will get an ellipse. 'Rectangle' and 'Square' have the
same relationship.
<p>By default, jsPlumb approximates the perimeter with 60 anchor locations. You can change this, though:</p>
<div class="code">
<pre>
jsPlumb.addEndpoint("someDiv", {
endpoint:"Dot",
anchor:[ "Perimeter", { shape:"Square", anchorCount:150 }]
});
</pre>
</div>
Obviously, the more points the smoother the operation. But also the more work your browser has to do.
<p>'Triangle' and 'Diamond' both assume that there is a point at the top center of the shape. This may or may not turn
out to be acceptable for all applications, in which case it might be possible to add support for a 'rotation' argument to the
anchor constructor.</p>
Here's a triangle and diamond example, just for kicks:
<div class="code">
<pre>
jsPlumb.connect({
source:"someDiv",
target:"someOtherDiv",
endpoint:"Dot",
anchors:[
[ "Perimeter", { shape:"Triangle" } ],
[ "Perimeter", { shape:"Diamond" } ]
]
});
</pre>
</div>
<h5>Perimeter Anchor Rotation</h5>
You can supply a 'rotation' value to a Perimeter anchor - an example can be seen in <a href="../jquery/perimeterAnchorsDemo.html" target="_blank">this demo</a>. Here's how you would use it:
<div class="code">
<pre>
jsPlumb.connect({
source:"someDiv",
target:"someOtherDiv",
endpoint:"Dot",
anchors:[
[ "Perimeter", { shape:"Triangle", rotation:25 } ],
[ "Perimeter", { shape:"Triangle", rotation:-335 } ]
]
});
</pre>
</div>
Note that the value must be supplied <strong>in degrees</strong>, not radians, and the number may be either positive or negative. In the example above, both triangles are of course rotated by the same amount.
<h4><a id="continuousAnchors">Continuous Anchors</a></h4>
As discussed above, these are anchors whose positions are calculated by jsPlumb according to the orientation between elements in a Connection, and also how
many other Continuous anchors happen to be sharing the element. You specify that you want to use Continuous anchors using the string syntax you would use
to specify one of the default Static Anchors, for example:
<div class="code">
<pre>
jsPlumb.connect({
source:someDiv,
target:someOtherDiv,
anchor:"Continuous"
});
</pre>
</div>
Note in this example I specified only "anchor", rather than "anchors" - jsPlumb will use the same spec for both anchors. But I could have said this:
<div class="code">
<pre>
jsPlumb.connect({
source:someDiv,
target:someOtherDiv,
anchors:["BottomCenter", "Continuous"]
});
</pre>
</div>
...which would have resulted in the source element having a Static Anchor at BottomCenter. In practise, though, it seems the Continuous Anchors work best if both
elements in a Connection are using them.
<p>Note also that Continuous Anchors can be specified on <strong>addEndpoint</strong> calls:</p>
<div class="code">
<pre>
jsPlumb.addEndpoint(someDiv, {
anchor:"Continuous",
paintStyle:{ fillStyle:"red" }
});
</pre>
</div>
...and in <strong>makeSource</strong>/<strong>makeTarget</strong>:
<div class="code">
<pre>
jsPlumb.makeSource(someDiv, {
anchor:"Continuous",
paintStyle:{ fillStyle:"red" }
});
jsPlumb.makeTarget(someDiv, {
anchor:"Continuous",
paintStyle:{ fillStyle:"red" }
});
</pre>
</div>
... and in the jsPlumb defaults:
<div class="code">
<pre>
jsPlumb.Defaults.Anchor = "Continuous";
</pre>
</div>
<h5>Continuous Anchor Faces</h5>
By default, a Continuous anchor will choose points from all four faces of the element on
which it resides. You can control this behaviour, though, with the <strong>faces</strong>
parameter on the anchor spec:
<div class="code">
<pre>
jsPlumb.makeSource(someDiv, {
anchor:["Continuous", { faces:["top", "left"] } ]
});
</pre>
</div>
Allowed values are:
<ul>
<li class="bullet">top</li>
<li class="bullet">left</li>
<li class="bullet">right</li>
<li class="bullet">bottom</li>
</ul>
If you provide an empty array for the 'faces' parameter, jsPlumb will default to using all four faces.
</div>
<div class="section">
<h4><a id="definitions">Connector, Endpoint & Overlay Definitions</a></h4>
Before we discuss Connector, Endpoints and Overlays, a quick word on definitions: whenever you need to define a Connector, Endpoint or Overlay, you must use a "definition" of it, rather than constructing one directly. This definition can be either a string that nominates the artifact you want to create:
<div class="code">
<pre>jsPlumb.connect({
source:"someDiv",
target:"someOtherDiv",
endpoint:"Rectangle"
});
</pre>
</div>
or an array consisting of both the artifact's name and the arguments you want to pass to its constructor:
<div class="code">
<pre>jsPlumb.connect({
source:"someDiv",
target:"someOtherDiv",
endpoint:[ "Rectangle", { cssClass:"myEndpoint", width:30, height:10 } ]
});
</pre>
</div>
There is also a three-argument method that allows you to specify two sets of parameters, which jsPlumb will merge together for you. The idea behind this is that you will often want to define common characteristics somewhere and reuse them across a bunch of different calls:
<div class="code">
<pre>var common = {
cssClass : "myCssClass",
hoverClass : "myHoverClass"
};
jsPlumb.connect({
source:"someDiv",
target:"someOtherDiv",
endpoint:[ "Rectangle", { width:30, height:10 }, common ]
});
</pre>
</div>
This syntax is supported for all Endpoint, Connector and Overlay definitions. Here's an example using definitions for all three:
<div class="code">
<pre>var common = {
cssClass:"myCssClass"
};
jsPlumb.connect({
source:"someDiv",
target:"someOtherDiv",
endpoint:[ "Dot", { radius:5, hoverClass:"myEndpointHover" }, common ],
connector:[ "Bezier", { curviness:100 }, common ],
overlays: [
[ "Arrow", { foldback:0.2 }, common ],
[ "Label", { cssClass:"labelClass" } ]
]
});
</pre>
The allowed constructor parameters are different for each artifact you create, but every artifact takes a single JS object as argument, with the parameters as [key,value] pairs in that object. See the relevant sections on <a href="#connectors">Connectors</a>, <a href="#endpoints">Endpoints</a> and <a href="#overlays">Overlays</a> for information on supported parameters.
</div>
<div class="section">
<h3><a id="connectors">Connectors</a></h3>
<p>Connectors are the lines that actually join elements of the UI. jsPlumb has four connector implementations - a straight line, a Bezier curve, "flowchart", and "state machine". The default connector is the Bezier curve.</p>
<p>You optionally specify a Connector by setting the 'connector' property on a call to jsPlumb.connect, jsPlumb.addEndpoint(s), jsPlumb.makeSource or jsPlumb.makeTarget. If you do not supply a value for 'connector', the default will be used (see <a href="#defaults">defaults</a>).</p>
<p>You specify Connectors using the syntax described above in <a href="#definitions">Connector, Endpoint & Overlay Definitions.</a> Allowed constructor values for each Connector type are described below:</p>
<h4><a id="bezierConnector">Bezier Connector</a></h4>
<p>The Bezier Connector provides a cubic Bezier path between the two Endpoints. It supports a single constructor argument:</p>
<p>
<strong>curviness</strong> - Optional; defaults to 150. This defines the distance in pixels that
the Bezier's control points are situated from the anchor points. This does not mean that your
connector will pass through a point at this distance from your curve. It is a hint to how you want the
curve to travel. Rather than discuss Bezier curves at length here, we
refer you to <a href="http://en.wikipedia.org/wiki/B%C3%A9zier_curve" target="_blank">Wikipedia.</a>
</p>
<h4><a id="straightConnector">Straight Connector</a></h4>
<p>The Straight Connector draws a straight line between the two endpoints. No constructor arguments are supported; use the <strong>endpointStyle</strong> and/or <strong>cssClass</strong>/<strong>connectorClass</strong> to a <strong>connect</strong>, <strong>addEndpoint</strong>, <strong>makeSource</strong> or <strong>makeTarget</strong> call to control the appearance of one of these Connectors.
</p>
<h4><a id="flowchartConnector">Flowchart Connector</a></h4>
<p>This type of Connector draws a connection that consists of a series of vertical or horizontal segments - the classic flowchart look. Two constructor arguments are supported:</p>
<strong>stub</strong> - this is the minimum length, in pixels, of the initial stub that emanates from an Endpoint. This is an optional parameter, and can be either an integer, which specifies the stub fo each end of the connector, or an array of two integers, specifying the stub for the [source, target] endpoints in the connection. This parameter is optional, and defaults to an integer with value 30 pixels.<br/>
<strong>gap</strong> - optional, defaults to 0 pixels. Lets you specify a gap between the end of the connector and the elements to which it is attached.
<strong>midpoint</strong> - optional, defaults to 0.5. This is the distance between the two elements that the longest section of the flowchart connector will be drawn at. This parameter is useful for those cases where you have programmatic control of the drawing and perhaps want to avoid some other element on the page.
<p>This Connector supports Connections that start and end on the same element.</p>
<h4><a id="stateMachineConnector">State Machine Connector</a></h4>
<p>This Connector draws slightly curved lines (they are actually quadratic Bezier curves), similar to the State Machine connectors you may have seen in software like GraphViz. Connections in which some element is both the source and the target (so-called 'loopback') are supported by these Connectors (as they are with Flowchart Connectors); in this case you get a circle. Supported parameters are:
</p>
<p>
<strong>margin</strong> - Optional; defaults to 5. Defines the distance from the element that the connector begins/ends.
</p>
<p>
<strong>curviness</strong> - Optional, defaults to 10. This has a similar effect to the curviness parameter on Bezier curves.
</p>
<p>
<strong>proximityLimit</strong> - Optional, defaults to 80. The minimum distance between the two ends of the Connector before it paints itself as
a straight line rather than a quadratic Bezier curve.
</p>
</div>
<div class="section">
<h3><a id="endpoints">Endpoint Types</a></h3>
<p>An Endpoint is the UI component that marks the location of an Anchor, ie. the place where a Connector joins an
element. jsPlumb comes with four Endpoint implementations - <strong>Dot</strong>, <strong>Rectangle</strong>, <strong>Blank</strong> and <strong>Image</strong>. You optionally specify Endpoint properties using the
<strong>endpoint</strong> parameter in a call to jsPlumb.connect, jsPlumb.addEndpoint, jsPlumb.makeSource or jsPlumb.makeTarget.
</p>
<p>As with Connectors and Overlays, you specify Endpoints using the syntax described above in <a href="#definitions">Connector, Endpoint & Overlay Definitions.</a></p>
The four available Endpoint types, and their constructor arguments, are as follows:
<h4><a id="dotEndpoint">Dot Endpoint</a></h4>
This Endpoint draw a dot on the screen. It supports three constructor parameters:
<p>
<strong>radius</strong> - Optional; defaults to 10 pixels. Defines the radius of the dot.
</p>
<p>
<strong>cssClass</strong> - Optional. A CSS class to attach to the element the Endpoint creates.
</p>
<p>
<strong>hoverClass</strong> - Optional. A CSS class to attach to the element the Endpoint creates whenever the mouse is hovering over the
element or an attached Connection.
</p>
<h4><a id="rectangleEndpoint">Rectangle Endpoint</a></h4>
Draws a rectangle. Supported constructor parameters are:
<p>
<strong>width</strong> - Optional; defaults to 20 pixels. Defines the width of the rectangle.
</p>
<p>
<strong>height</strong> - Optional; defaults to 20 pixels. Defines the height of the rectangle.
</p>
<p>
<strong>cssClass</strong> - Optional. A CSS class to attach to the element the Endpoint creates.
</p>
<p>
<strong>hoverClass</strong> - Optional. A CSS class to attach to the element the Endpoint creates whenever the mouse is hovering over the
element or an attached Connection.
</p>
<h4><a id="imageEndpoint">Image Endpoint</a></h4>
Draws an image from a given URL. This Endpoint supports three constructor parameters:
<p>
<strong>src</strong> - Required. Specifies the URL of the image to use.
</p>
<p>
<strong>cssClass</strong> - Optional. A CSS class to attach to the element the Endpoint creates.
</p>
<p>
<strong>hoverClass</strong> - Optional. A CSS class to attach to the element the Endpoint creates whenever the mouse is hovering over the
element or an attached Connection.
</p>
<h4><a id="blankEndpoint">Blank Endpoint</a></h4>
Does not draw anything visible to the user. As discussed previously, this Endpoint is probably not what you want if you need your users to be able to drag existing Connections - for that, use a Rectangle or Dot Endpoint and assign to it a CSS class that causes it to be transparent.
</div>
<div class="section">
<h3><a id="overlays">Overlay Types</a></h3>
<p>
Overlays are UI elements that are painted onto connections, such as labels or arrows.
</p>
<p>
jsPlumb comes with five types of Overlays:
</p>
<ul>
<li class="bullet"><strong>Arrow</strong> - a configurable arrow that is painted at some point along the connector. You can control the length and width of the Arrow, the 'foldback' point - a point the tail points fold back into, and the direction (allowed values are 1 and -1; 1 is the default and means point in the direction of the connection)</li>
<li class="bullet"><strong>Label</strong> - a configurable label that is painted at some point along the connector.</li>
<li class="bullet"><strong>PlainArrow</strong> - an Arrow shaped as a triangle, with no foldback.</li>
<li class="bullet"><strong>Diamond</strong> - as the name suggests, a diamond.</li>
<li class="bullet"><strong>Custom</strong> - allows you to create the Overlay yourself - your Overlay may be any DOM element you like.</li>
</ul>
PlainArrow and Diamond are actually just configured instances of the generic Arrow overlay (see examples).
<p>All Overlays support these two methods for getting/setting their location (location is either a number between 0 and 1 inclusive, indicating some point along the path inscribed by the associated Connector, or an absolute number of pixels, where negative values mean distance from the target of the connection):</p>
<ul>
<li class="bullet"><strong>getLocation</strong> - returns the current location</li>
<li class="bullet"><strong>setLocation</strong> - sets the current location; valid values are decimals in the range 0-1 inclusive, or an integer less than 0 (to express distance from the target), or an integer greater than 1 (to express distance from the source)</li>
</ul>
<p>You can specify one or more overlays when making a call to jsPlumb.connect, jsPlumb.addEndpoint or jsPlumb.makeSource (but not jsPlumb.makeTarget; overlays
are always derived from what the source of a Connection defines) The three cases are discussed below:</p>
1. Specifying one or more overlays on a jsPlumb.connect call. In this example we'll create an Arrow with the default options for an Arrow, and
a label with the text "foo":
<div class="code">
<pre>jsPlumb.connect({
...
overlays:[
"Arrow",
[ "Label", { label:"foo", location:0.25, id:"myLabel" } ]
],
...
});
</pre>
</div>
This connection will have an arrow located halfway along it, and the label "foo" one quarter of the way along. Notice the <strong>id</strong>
parameter; it can be used later if you wish to remove the Overlay or change its visibility (see below).<br/><br/>
Another example, this time with an absolute location of 50 pixels from the source:
<div class="code">
<pre>jsPlumb.connect({
...
overlays:[
"Arrow",
[ "Label", { label:"foo", location:50, id:"myLabel" } ]
],
...
});
</pre>
</div>
2. Specifying one or more overlays on a jsPlumb.addEndpoint call. Note in this example that we use the parameter 'connectorOverlays' and not
'overlays' as in the last example. This is because 'overlays' would refer to Endpoint Overlays:
<div class="code">
<pre>jsPlumb.addEndpoint("someDiv", {
...
connectorOverlays:[
[ "Arrow", { width:10, length:30, location:1, id:"arrow" } ],
[ "Label", { label:"foo", id:"label" } ]
],
...
});</pre>
</div>
This connection will have a 10x30 Arrow located right at the head of the connection, and the label "foo" located at the halfway point. Again,
note that <strong>id</strong> parameter passed in to each Overlay spec.<br/><br/>
3. Specifying one or more overlays on a jsPlumb.makeSource call. Note in this example that we again use the parameter 'connectorOverlays' and not
'overlays'. The 'endpoint' parameter to jsPlumb.makeSource supports everything you might pass to the second argument of a jsPlumb.addEndpoint call:
<div class="code">
<pre>jsPlumb.makeSource("someDiv", {
...
endpoint:{
connectorOverlays:[
[ "Arrow", { width:10, length:30, location:1, id:"arrow" } ],
[ "Label", { label:"foo", id:"label" } ]
]
}
...
});</pre>
</div>
This connection will have a 10x30 Arrow located right at the head of the connection, and the label "foo" located at the halfway point. Again,
note that <strong>id</strong> parameter passed in to each Overlay spec.<br/><br/>
<h4><a id="arrowOverlay">Arrow Overlay</a></h4>
<p>This overlay draws an arrow, using four points: the head and two tail points, and a 'foldback' point, which permits the tail
of the arrow to be indented. Available constructor arguments for this Overlay are </p>
<ul>
<li><strong>width</strong> - width of the tail of the arrow</li>
<li><strong>length</strong> - distance from the tail of the arrow to the head</li>
<li><strong>location</strong> - where, either as a proportional value from 0 to 1 inclusive, or as an absolute value (negative values mean distance from target; positive values greater than 1 mean distance from source) the Arrow should appear on the Connector</li>
<li><strong>direction</strong> - which way to point. Allowed values are 1 (the default, meaning forwards) and -1, meaning backwards </li>
<li><strong>foldback</strong> - how far along the axis of the arrow the tail points foldback in to. Default is 0.623.</li>
<li><strong>paintStyle</strong> - a style object in the form used for paintStyle values for Endpoints and Connectors</li>
</ul>
<h4><a id="plainArrowOverlay">PlainArrow Overlay</a></h4>
<p>This is just a specialized instance of Arrow in which jsPlumb hardcodes 'foldback' to 1, meaning the tail of the Arrow is a flat edge. All of the constructor parameters from Arrow apply for PlainArrow.</p>
<h4><a id="diamondOverlay">Diamond Overlay</a></h4>
<p>This is a specialized instance of Arrow in which jsPlumb hardcodes 'foldback' to 2, meaning the Arrow turns into a Diamond. All of the constructor parameters from Arrow apply for Diamond.</p>
<h4><a id="labelOverlay">Label Overlay</a></h4>
This provides a text label to decorate Connectors with. The available constructor arguments are:
<ul>
<li><strong>label</strong> - The text to display. You can provide a function here instead of plain text: it is passed the Connection as an argument, and it should return a String.</li>
<li><strong>cssClass</strong> - Optional css class to use for the Label. This is now preferred over using the 'labelStyle' parameter.</li>
<li><strong>labelStyle</strong> - (deprecated, use cssClass instead) Optional arguments for the label's appearance. Valid entries in this JS object are:
<ul>
<li><em>font</em> - a font string in a format suitable for the Canvas element</li>
<li><em>fillStyle</em> - the color to fill the label's background with. Optional.</li>
<li><em>color</em> - the color of the label's text. Optional.</li>
<li><em>padding</em> - optional padding for the label. This is expressed as a proportion of the width of the label, not in pixels or ems.</li>
<li><em>borderWidth</em> - optional width in pixels for the label's border. Defaults to 0.</li>
<li><em>borderStyle</em> - optional. The color to paint the border, if there is one.</li>
</ul>
</li>
<li><strong>location</strong> - As for Arrow Overlay. Where, either proportionally from 0 to 1 inclusive, or as an absolute offset from either source or target, the label should appear.</li>
</ul>
The Label overlay offers two methods - getLabel and setLabel - for accessing/manipulating its content dynamically:
<div class="code">
<pre>
var c = jsPlumb.connect({
source:"d1",
target:"d2",
overlays:[
[ "Label", {label:"FOO", id:"label"}]
]
});
...
var label = c.getOverlay("label");
console.log("Label is currently", label.getLabel());
label.setLabel("BAR");
console.log("Label is now", label.getLabel());
</pre>
</div>
In this example you can see that the Label Overlay is assigned an id of "label" in the connect call, and then retrieved using that id in the call to Connection's getOverlay method.
<p>Both Connections and Endpoints support Label Overlays, and because changing labels is quite a common operation, <strong>setLabel</strong> and <strong>getLabel</strong> methods have been added to these objects:
<div class="code">
<pre>
var conn = jsPlumb.connect({
source:"d1",
target:"d2",
label:"FOO"
});
...
console.log("Label is currently", conn.getLabel());
conn.setLabel("BAR");
console.log("Label is now", conn.getLabel());
</pre>
</div>
These methods support passing in a Function instead of a String, and jsPlumb will create a label overlay for you if one does not yet exist when you call setLabel:
<div class="code">
<pre>
var conn = jsPlumb.connect({
source:"d1",
target:"d2"
});
...
conn.setLabel(function(c) {
var s = new Date();
return s.getTime() + "milliseconds have elapsed since 01/01/1970";
});
console.log("Label is now", conn.getLabel());
</pre>