content.html 136 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894
  1. <html>
  2. <head>
  3. <title>jsPlumb 1.3.6 - documentation</title>
  4. <link rel="stylesheet" href="/mp.css">
  5. <link rel="stylesheet" href="jsPlumbDoc.css">
  6. </head>
  7. <body>
  8. <div class="menu">
  9. <a href="http://jsplumb.org" class="mplink" target="_top">view demo</a>
  10. &nbsp;|&nbsp;<a href="mailto:simon.porritt@gmail.com" class="mplink">contact me</a>
  11. &nbsp;|&nbsp;<a href="http://jsplumb.tumblr.com" class="mplink">jsPlumb on Tumblr</a>
  12. </div>
  13. <!--
  14. GWT
  15. http://fishfilosophy.blogspot.com/2011/12/how-to-connect-gwt-widgets-using.html?spref=tw
  16. -->
  17. <div class="content">
  18. <div class="section">
  19. <h3><a id="summary">Summary</a></h3>
  20. jsPlumb allows you to connect elements on the screen using SVG, Canvas or VML, depending on the capabilities of the browser.
  21. <p>
  22. It can be used with jQuery, MooTools or YUI3 (or another library of your choice if you feel like implementing an adapter for it).
  23. </p>
  24. <h5>Browser Compatibility</h5>
  25. <p>jsPlumb 1.3.6 has been tested on the following browsers:
  26. <ul>
  27. <li class="bullet">IE 6 on Windows XP</li>
  28. <li class="bullet">IE 7 on Windows XP</li>
  29. <li class="bullet">IE 8 on Windows XP</li>
  30. <li class="bullet">Firefox 3.5.8 on Windows XP</li>
  31. <li class="bullet">IE 9 on Windows 7</li>
  32. <li class="bullet">Chrome 12 on Windows 7</li>
  33. <li class="bullet">Firefox 3.5.8 on Windows 7</li>
  34. <li class="bullet">Firefox 3.6.3 on Ubuntu 10.04</li>
  35. <li class="bullet">Chrome on Ubuntu 11.04</li>
  36. <li class="bullet">Safari 4 on Mac Leopard</li>
  37. <li class="bullet">Chrome on Mac Leopard</li>
  38. <li class="bullet">Safari 4 on Windows Vista</li>
  39. <li class="bullet">Safari 5.0.5 on Windows 7</li>
  40. <li class="bullet">Opera 10.54 on Windows XP</li>
  41. </ul>
  42. </p>
  43. </div>
  44. <div class="section">
  45. <h3><a id="changes">Changes between 1.3.6 and 1.3.5</a></h3>
  46. <h5>Backwards Compatibility</h5>
  47. <ul>
  48. <li class="bullet"><strong>makeSource</strong> and <strong>makeTarget</strong> calls are now honoured by subsquent calls to jsPlumb.connect. So if you call makeTarget on some element, providing an endpoint spec, and then later on call jsPlumb.connect with that element as the target, jsPlumb will use the endpoint spec you provided to makeTarget. The thinking behind this is that typically you will want to setup some sources and/or targets for interactive connections, but then possibly load some initial state for the UI. Prior to this change you would have to provide the same information twice.<br/></li>
  49. <li class="bullet">The second argument to <strong>makeSource</strong> and <strong>makeTarget</strong> no longer requires the nested 'endpoint' parameter - they take the exact same object that you would pass to the second argument to addEndpoint. Of course that object can itself have an 'endpoint' parameter, which is used to specify the type of endpoint (Dot, Rectangle etc) - kind of confusing, and yet another reason to unify the API a little.<br/></li>
  50. <li class="bullet">- Mouse events are always enabled from 1.3.6 onwards. The default setting <strong>MouseEventsEnabled</strong> and the method <strong>setMouseEventsEnabled</strong> have both been removed.
  51. </ul>
  52. <h5>New Features</h5>
  53. The following new features have been added:
  54. <ul>
  55. </ul>
  56. <h5>Issues Resolved</h5>
  57. <ul>
  58. <li class="bullet">
  59. <strong>98</strong> - Endpoints nested inside draggable element are not refreshed on drag
  60. </li>
  61. <li class="bullet">
  62. <strong>195</strong> - deleteEndpointsOnDetach was being ignored by makeTarget method
  63. </li>
  64. <li class="bullet">
  65. <strong>204</strong> - add importDefaults method
  66. </li>
  67. <!--li class="bullet">
  68. <strong>187</strong> - dynamic anchors broken for Endpoints
  69. </li>
  70. <li class="bullet">
  71. <strong>189</strong> - Endpoints draggable when they should not be
  72. </li>
  73. <li class="bullet">
  74. <strong>190</strong> - getInstance regressions
  75. </li>
  76. <li class="bullet">
  77. <strong>191</strong> - offsets calculated wrongly in certain situations
  78. </li-->
  79. </ul>
  80. </div>
  81. <div class="section">
  82. <h3><a id="init">Setup</a></h3>
  83. <h4><a id="imports">Required Imports</a></h4>
  84. <h4>jQuery</h4>
  85. <ul>
  86. <li class="bullet">jQuery 1.3.x or higher.</li>
  87. <li class="bullet">jQuery UI 1.7.x or 1.8.x (if you wish to support drag and drop).</li>
  88. </ul>
  89. <div class="code">
  90. <pre>&lt;script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"&gt;&lt;/script&gt;
  91. &lt;script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8.13/jquery-ui.min.js"&gt;&lt;/script&gt;
  92. &lt;script type="text/javascript" src="PATH_TO/jquery.jsPlumb-1.3.6-all-min.js "&gt;&lt;/script&gt;</pre>
  93. </div>
  94. <h4>MooTools</h4>
  95. <ul>
  96. <li class="bullet">MooTools Core 1.2.4 or higher. jsPlumb has been tested with 1.2.4 and 1.3.3.</li>
  97. <li class="bullet">Drag.Move from MooTools More 1.2.4.4 or higher (if you wish to support drag and drop).</li>
  98. </ul>
  99. <div class="code">
  100. <pre>&lt;script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/mootools/1.3.3/mootools-yui-compressed.js"&gt;&lt;/script&gt;
  101. &lt;script type="text/javascript" src="PATH_TO_MOO_TOOLS_MORE_1_3_2_1"&gt;&lt;/script&gt;
  102. &lt;script type="text/javascript" src="PATH_TO/mootools.jsPlumb-1.3.6-all-min.js "&gt;&lt;/script&gt;</pre>
  103. </div>
  104. <h4>YUI3</h4>
  105. <ul>
  106. <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>
  107. </ul>
  108. <div class="code">
  109. <pre>&lt;script type="text/javascript" src="http://yui.yahooapis.com/3.3.0/build/simpleyui/simpleyui-min.js"&gt;&lt;/script&gt;
  110. &lt;script type="text/javascript" src="PATH_TO/yui.jsPlumb-1.3.6-all-min.js "&gt;&lt;/script&gt;</pre>
  111. </div>
  112. <h4><a id="renderMode">Render Mode</a></h4>
  113. jsPlumb can use SVG, HTML5 Canvas elements or VML to render the various objects it adds to the display. Most modern browsers support
  114. Canvas and SVG; IE&lt;9 browsers support neither.
  115. <p>
  116. By default, jsPlumb attempts to use <strong>jsPlumb.SVG</strong> as the render mode (prior to 1.3.4, the default renderer was Canvas), falling back to <strong>jsPlumb.VML</strong> if the
  117. browser is IE&lt;9. You can change the render mode by making this call:
  118. </p>
  119. <div class="code">
  120. <pre>jsPlumb.setRenderMode(jsPlumb.CANVAS);</pre>
  121. </div>
  122. if, for some reason, you set the render mode to be <strong>jsPlumb.VML</strong> but you're in any browser other than IE&lt;9, jsPlumb
  123. will use SVG.
  124. <p>
  125. The <strong>jsPlumb.setRenderMode</strong> method returns you the render mode that jsPlumb actually ended up setting. Valid values for setRenderMode are:
  126. </p>
  127. <ul>
  128. <li class="bullet">jsPlumb.CANVAS</li>
  129. <li class="bullet">jsPlumb.SVG</li>
  130. <li class="bullet">jsPlumb.VML</li>
  131. </ul>
  132. <h5>Performance Considerations</h5>
  133. <p>
  134. SVG uses less memory than Canvas and has support for mouse events built in, so I recommend using
  135. SVG unless you have a really good reason for wanting Canvas.
  136. </p>
  137. <h4><a id="initializing">Initializing jsPlumb</a></h4>
  138. You should not start making calls to jsPlumb until the DOM has been initialized - perhaps no surprises there. With YUI, though, the asynchronous
  139. 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,
  140. you should bind to the "ready" event on jsPlumb (or the instance of jsPlumb you are working with):
  141. <div class="code">
  142. <pre>jsPlumb.bind("ready", function() {
  143. ...
  144. // your jsPlumb related init code goes here
  145. ...
  146. });
  147. </pre>
  148. </div>
  149. There's a helper method that can save you approximately 9 (count them!) characters:
  150. <div class="code">
  151. <pre>jsPlumb.ready(function() {
  152. ...
  153. // your jsPlumb related init code goes here
  154. ...
  155. });
  156. </pre>
  157. </div>
  158. <p>
  159. 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
  160. 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.
  161. </p>
  162. <p>
  163. If you bind to the "ready" event after jsPlumb has already been initialized, your callback will be executed immediately.
  164. </p>
  165. <h4><a id="unload">Unloading jsPlumb</a></h4>
  166. jsPlumb offers a method you can call when your page is unloading. You should do this to insure
  167. against memory leaks. You configure it like this:
  168. <div class="code">
  169. <pre>
  170. &lt;body onunload="jsPlumb.unload();"&gt;
  171. ...
  172. &lt;/body&gt;
  173. </pre>
  174. </div>
  175. <h4><a id="multipleInstances">Multiple jsPlumb instances</a></h4>
  176. jsPlumb is registered on the browser's Window by default, providing one static instance
  177. for the whole page to use. Should you need to, though, you can instantiate independent
  178. instances of jsPlumb, using the <strong>getInstance</strong> method, for example:
  179. <div class="code">
  180. <pre>
  181. var firstInstance = jsPlumb.getInstance();
  182. </pre>
  183. </div>
  184. The variable 'firstInstance' can now be treated exactly as you would treat the 'jsPlumb' variable - you can set
  185. defaults, call the connect method, whatever:
  186. <div class="code">
  187. <pre>
  188. firstInstance.Defaults.Connector = [ "Bezier", { curviness: 150 } ];
  189. firstInstance.Defaults.Anchors = [ "TopCenter", "BottomCenter" ];
  190. firstInstance.connect({source:"element1", target:"element2", scope:"someScope" });
  191. </pre>
  192. </div>
  193. <strong>getInstance</strong> optionally takes an object that provides the defaults:
  194. <div class="code">
  195. <pre>
  196. var secondInstance = jsPlumb.getInstance({
  197. PaintStyle:{ lineWidth:6, strokeStyle:"#567567", outlineColor:"black", outlineWidth:1 },
  198. Connector:[ "Bezier", { curviness: 30 } ],
  199. Endpoint:[ "Dot", { radius:5 } ],
  200. EndpointStyle : { fillStyle: "#567567" },
  201. Anchor : [ 0.5, 0.5, 1, 1 ]
  202. });
  203. secondInstance.connect({ source:"element4", target:"element3", scope:"someScope" });
  204. </pre>
  205. </div>
  206. <h4><a id="zIndex">Z-index Considerations</a></h4>
  207. <p>
  208. You need to pay attention to the z-indices of the various parts of your UI when
  209. using jsPlumb, in particular to ensure that the elements that jsPlumb adds to
  210. the DOM do not overlay other parts of the interface.
  211. </p>
  212. <p>
  213. jsPlumb adds an element to the DOM for each Endpoint, Connector and Overlay. So
  214. for a connection having visible Endpoints at each end and a label in the middle,
  215. jsPlumb adds four elements to the DOM. The actual elements it adds depend on the
  216. renderer in use (Canvas/SVG/VML).
  217. </p>
  218. <p>
  219. To help you organise z-indices correctly, jsPlumb adds a CSS class to each type of
  220. element it adds. They are as follows:
  221. </p>
  222. <table style="color:black;width:70%;font-size:90%;">
  223. <tr><td><strong>type of element</strong></td><td><strong>class added</strong></td></tr>
  224. <tr><td>Endpoint</td><td>_jsPlumb_endpoint</td></tr>
  225. <tr><td>Connector</td><td>_jsPlumb_connector</td></tr>
  226. <tr><td>Overlay</td><td>_jsPlumb_overlay</td></tr>
  227. </table>
  228. <h4><a id="containerDefault">Where does jsPlumb add elements?</a></h4>
  229. <p>
  230. It's important to understand where in the DOM jsPlumb will add any elements it creates,
  231. as it has a bearing on the markup you can use with jsPlumb.
  232. </p>
  233. <p>
  234. Prior to 1.3.0, jsPlumb added everything to the end of the <em>body</em> element. This
  235. has the advantage of being the most flexible arrangement in terms of supporting what
  236. elements can be connected, but in certain use cases produced unexpected results. Consider
  237. the arrangement where you have some connected elements in a tab: you would
  238. expect jsPlumb to add elements inside the tab, so that when the user switches tabs and
  239. the current one is hidden, all the jsPlumb stuff is hidden too. But when the elements are
  240. on the body, this does not happen!
  241. </p>
  242. <p>
  243. For this reason, from 1.3.0 onwards, jsPlumb's default behaviour is to attach Endpoint elements to the parent
  244. of the element the Endpoint is attached to (<strong>not</strong> the actual element
  245. the Endpoint is attached to), and to attach Connector elements to the parent of
  246. the source Endpoint in the Connection. This results in all the elements of the
  247. Connection being siblings inside the same parent node, which jsPlumb requires, for
  248. various reasons arising from the trade off between doing lots of maths and the
  249. performance of the whole thing.
  250. </p>
  251. <p>
  252. In general, the default behaviour means that you cannot do things like this:
  253. </p>
  254. <div class="code">
  255. <pre>
  256. &lt;body&gt;
  257. &lt;div id="container0"&gt;
  258. &lt;div id="node0"&gt;&lt;/div&gt;
  259. &lt;/div&gt;
  260. &lt;div id="container1"&gt;
  261. &lt;div id="node1"&gt;&lt;/div&gt;
  262. &lt;/div&gt;
  263. &lt;/body&gt;
  264. &lt;script type="text/javascript"&gt;
  265. var e0 = jsPlumb.addEndpoint("node0"),
  266. e1 = jsPlumb.addEndpoint("node1");
  267. jsPlumb.connect({ source:e0, target:e1 });
  268. &lt;/script&gt;
  269. </pre>
  270. </div>
  271. <p>
  272. because the elements created for 'e0' and 'e1' would have different parent nodes, and an attempt
  273. to make a Connection between them would not work. For the example just given, you would need to
  274. register the Endpoints on the 'container' divs (and then quite possibly throw away the 'node' divs):
  275. </p>
  276. <div class="code">
  277. <pre>
  278. &lt;body&gt;
  279. &lt;div id="container0"&gt;
  280. &lt;/div&gt;
  281. &lt;div id="container1"&gt;
  282. &lt;/div&gt;
  283. &lt;/body&gt;
  284. &lt;script type="text/javascript"&gt;
  285. var e0 = jsPlumb.addEndpoint("container0"),
  286. e1 = jsPlumb.addEndpoint("container1");
  287. jsPlumb.connect({ source:e0, target:e1 });
  288. &lt;/script&gt;
  289. </pre>
  290. </div>
  291. now 'e0' and 'e1' have the same parent - the <em>body</em> element.
  292. <p>Remember that you can use the <strong>anchor</strong> parameter to an <strong>addEndpoint</strong>
  293. call to specify where on an element you want an Endpoint to appear. Used in conjunction with
  294. CSS classes (discussed below), you can have an Endpoint on top of some element wherever you like.
  295. </p>
  296. <p><strong>Note regarding the drawEndpoints option on jsPlumb.connect</strong>: with the default behaviour, jsPlumb uses the offsetParent of
  297. 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
  298. offsetParent of the source endpoint because it is not visible. If your connection lies inside some container other than the document body,
  299. 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
  300. use the "Blank" endpoint when you don't want to see one, or instruct jsPlumb to attach everything to the document body (see below).
  301. </p>
  302. <h5>Overriding the default behaviour</h5>
  303. <p>
  304. 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:
  305. </p>
  306. 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:
  307. <div class="code">
  308. <pre>
  309. jsPlumb.Defaults.Container = $("body");
  310. ...
  311. jsPlumb.addEndpoint(someDiv, { endpoint options });
  312. </pre>
  313. </div>
  314. Set a container to use as the default container, using an element id,
  315. and then connect two elements. The elements created in this example will be children of the element with id "containerId":
  316. <div class="code">
  317. <pre>
  318. jsPlumb.Defaults.Container = "containerId";
  319. ...
  320. jsPlumb.connect({ source:someDiv, target:someOtherDiv });
  321. </pre>
  322. </div>
  323. 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":
  324. <div class="code">
  325. <pre>
  326. jsPlumb.connect({ source:someDiv, target:someOtherDiv, container:$("#containerId") });
  327. </pre>
  328. </div>
  329. 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":
  330. <div class="code">
  331. <pre>
  332. jsPlumb.addEndpoint(someDiv, { ..., container:"containerId" });
  333. </pre>
  334. </div>
  335. </div>
  336. <div class="section">
  337. <h3><a id="jsPlumbBasics">Basic Concepts</a></h3>
  338. jsPlumb is all about connecting things together, so the core abstraction in jsPlumb is the <strong>Connection</strong> object, which is itself
  339. broken down into these four concepts:
  340. <ul>
  341. <li><strong>Anchor</strong> - a location, relative to an element's origin, at which an Endpoint can exist. You do not create these yourself; you
  342. supply hints to the various jsPlumb functions, which create them as needed. They have no visual representation; they are a logical position only.
  343. 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 ].
  344. See the <a href="#anchors">anchors</a> section for more detail.<br/><br/></li>
  345. <li><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>
  346. <li><strong>Connector</strong> - the visual representation of the line connecting two elements in the page. jsPlumb has four types of these
  347. available as defaults - a Bezier curve, a straight line, 'flowchart' connectors and 'state machine connectors. You do not interact with Connectors;
  348. you just specify definitions of them when you need to - see <a href="#definitions">Connector, Endpoint &amp; Overlay Definitions</a> <br/><br/></li>
  349. <li><strong>Overlay</strong> - a UI component that is used to decorate a Connector, such as a Label, Arrow, etc.<br/><br/></li>
  350. </ul>
  351. <p>One Connection is made up of two Endpoints, a Connector, and zero or more Overlays working together to join two elements.</p>
  352. <p>jsPlumb's public API exposes only Connection and Endpoint, handling the creation and configuration of everything else internally.
  353. But you still need to be across the concepts encapsulated by Anchor, Connector and Overlay.
  354. </p>
  355. </div>
  356. <div class="section">
  357. <h3><a id="anchors">Anchors</a></h3>
  358. An Anchor models the notion of where on an element a Connector should connect. There are three main types of Anchors:
  359. <ul>
  360. <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
  361. identify one of the defaults that jsPlumb ships with, or an array describing the location (see below)</li>
  362. <li class="bullet">'Dynamic' anchors - these are lists of Static anchors from which jsPlumb picks the most appropriate one each time a Connection
  363. 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
  364. the Connection. A future version of jsPlumb might support a pluggable algorithm to make this decision.</li>
  365. <li class="bullet">'Continuous' anchors - These anchors, introduced in 1.3.4, are not fixed to any specific loction; they are assigned to one of
  366. the four faces of an element depending on that element's orientation to the other element in the associated Connection. Continuous anchors are
  367. slightly more computationally intensive than Static or Dynamic anchors because jsPlumb is required to calculate the position of every Connection
  368. during a paint cycle, rather than just Connections belonging to the element in motion. These anchors were designed for use with the StateMachine
  369. connector that was also introduced in 1.3.4, but will work with any combination of Connector and Endpoint.</li>
  370. </ul>
  371. <h4><a id="staticAnchors">Static Anchors</a></h4>
  372. 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,
  373. the center of the element, and the midpoint of each edge of the element:
  374. <ul>
  375. <li class="bullet">TopCenter</li>
  376. <li class="bullet">TopRight</li>
  377. <li class="bullet">RightMiddle</li>
  378. <li class="bullet">BottomRight</li>
  379. <li class="bullet">BottomCenter</li>
  380. <li class="bullet">BottomLeft</li>
  381. <li class="bullet">LeftMiddle</li>
  382. <li class="bullet">TopLeft</li>
  383. </ul>
  384. 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
  385. 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.
  386. <div class="code">
  387. <pre>
  388. jsPlumb.connect({...., anchor:"BottomCenter", ... });
  389. </pre>
  390. </div>
  391. is identical to:
  392. <div class="code">
  393. <pre>
  394. jsPlumb.connect({...., anchor:[ 0.5, 1, 0, 1 ], ... });
  395. </pre>
  396. </div>
  397. 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:
  398. <div class="code">
  399. <pre>
  400. jsPlumb.connect({...., anchor:[ 0.5, 1, 0, 1, 0, 50 ], ... });
  401. </pre>
  402. </div>
  403. <h4><a id="dynamicAnchors">Dynamic Anchors</a></h4>
  404. 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.
  405. <p>
  406. There is no special syntax to creating a DynamicAnchor; you just provide an array of individual Static Anchor specifications, eg:
  407. </p>
  408. <div class="code">
  409. <pre>
  410. var dynamicAnchors = [ [ 0.2, 0, 0, -1 ], [ 1, 0.2, 1, 0 ],
  411. [ 0.8, 1, 0, 1 ], [ 0, 0.8, -1, 0 ] ];
  412. jsPlumb.connect({...., anchor:dynamicAnchors, ... });
  413. </pre>
  414. </div>
  415. <h4> Default Dynamic Anchor</h4>
  416. jsPlumb provides a dynamic anchor called "AutoDefault" that chooses from TopCenter, RightMiddle, BottomCenter and LeftMiddle:
  417. <div class="code">
  418. <pre>jsPlumb.connect({...., anchor:"AutoDefault", ... });</pre>
  419. </div>
  420. <h4> Location Selection</h4>
  421. The initial implementation of the algorithm that decides which location to choose just calculates which location is closest to the center of the
  422. other element in the connection. It is possible that future versions of jsPlumb could support more sophisticated choice algorithms, if the need arose.
  423. <h4>Draggable Connections</h4>
  424. Dynamic Anchors and Draggable Connections can interoperate: jsPlumb locks the position of a dynamic anchor when you start to drag a connection from it,
  425. 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
  426. optimises the connection. <p>You can see this behaviour in the <a href="../html/jquery/draggableConnectorsDemo.html" target="_blank">draggable connections</a> demonstration, when
  427. 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
  428. endpoint jumps down to a location that is closer to window 3.</p>
  429. <h4><a id="continuousAnchors">Continuous Anchors</a></h4>
  430. As discussed above, these are anchors whose positions are calculated by jsPlumb according to the orientation between elements in a Connection, and also how
  431. 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
  432. to specify one of the default Static Anchors, for example:
  433. <div class="code">
  434. <pre>
  435. jsPlumb.connect({
  436. source:someDiv,
  437. target:someOtherDiv,
  438. anchor:"Continuous"
  439. });
  440. </pre>
  441. </div>
  442. 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:
  443. <div class="code">
  444. <pre>
  445. jsPlumb.connect({
  446. source:someDiv,
  447. target:someOtherDiv,
  448. anchors:["BottomCenter", "Continuous"]
  449. });
  450. </pre>
  451. </div>
  452. ..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
  453. elements in a Connection are using them.
  454. <p>Note also that Continuous Anchors can be specified on <strong>addEndpoint</strong> calls:</p>
  455. <div class="code">
  456. <pre>
  457. jsPlumb.addEndpoint(someDiv, {
  458. anchor:"Continuous",
  459. paintStyle:{ fillStyle:"red" }
  460. });
  461. </pre>
  462. </div>
  463. ...and in <strong>makeSource</strong>/<strong>makeTarget</strong>:
  464. <div class="code">
  465. <pre>
  466. jsPlumb.makeSource(someDiv, {
  467. anchor:"Continuous",
  468. paintStyle:{ fillStyle:"red" }
  469. });
  470. jsPlumb.makeTarget(someDiv, {
  471. anchor:"Continuous",
  472. paintStyle:{ fillStyle:"red" }
  473. });
  474. </pre>
  475. </div>
  476. ... and in the jsPlumb defaults:
  477. <div class="code">
  478. <pre>
  479. jsPlumb.Defaults.Anchor = "Continuous";
  480. </pre>
  481. </div>
  482. </div>
  483. <div class="section">
  484. <h4><a id="definitions">Connector, Endpoint &amp; Overlay Definitions</a></h4>
  485. 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:
  486. <div class="code">
  487. <pre>jsPlumb.connect({
  488. source:"someDiv",
  489. target:"someOtherDiv",
  490. endpoint:"Rectangle"
  491. });
  492. </pre>
  493. </div>
  494. or an array consisting of both the artifact's name and the arguments you want to pass to its constructor:
  495. <div class="code">
  496. <pre>jsPlumb.connect({
  497. source:"someDiv",
  498. target:"someOtherDiv",
  499. endpoint:[ "Rectangle", { cssClass:"myEndpoint", width:30, height:10 } ]
  500. });
  501. </pre>
  502. </div>
  503. 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:
  504. <div class="code">
  505. <pre>var common = {
  506. cssClass : "myCssClass",
  507. hoverClass : "myHoverClass"
  508. };
  509. jsPlumb.connect({
  510. source:"someDiv",
  511. target:"someOtherDiv",
  512. endpoint:[ "Rectangle", { width:30, height:10 }, common ]
  513. });
  514. </pre>
  515. </div>
  516. This syntax is supported for all Endpoint, Connector and Overlay definitions. Here's an example using definitions for all three:
  517. <div class="code">
  518. <pre>var common = {
  519. cssClass:"myCssClass"
  520. };
  521. jsPlumb.connect({
  522. source:"someDiv",
  523. target:"someOtherDiv",
  524. endpoint:[ "Dot", { radius:5, hoverClass:"myEndpointHover" }, common ],
  525. connector:[ "Bezier", { curviness:100 }, common ],
  526. overlays: [
  527. [ "Arrow", { foldback:0.2 }, common ],
  528. [ "Label", { cssClass:"labelClass" } ]
  529. ]
  530. });
  531. </pre>
  532. </div>
  533. 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.</a>
  534. </div>
  535. <div class="section">
  536. <h3><a id="connectors">Connectors</a></h3>
  537. <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>
  538. <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>
  539. <p>You specify Connectors using the syntax described above in <a href="#definitions">Connector, Endpoint &amp; Overlay Definitions.</a> Allowed constructor values for each Connector type are described below:</p>
  540. <h4><a id="bezierConnector">Bezier Connector</a></h4>
  541. <p>The Bezier Connector provides a cubic Bezier path between the two Endpoints. It supports a single constructor argument:</p>
  542. <p>
  543. <strong>curviness</strong> - Optional; defaults to 150. This defines the distance in pixels that
  544. the Bezier's control points are situated from the anchor points. This does not mean that your
  545. connector will pass through a point at this distance from your curve. It is a hint to how you want the
  546. curve to travel. Rather than discuss Bezier curves at length here, because they are a complex topic,
  547. refer instead to <a href="http://en.wikipedia.org/wiki/B%C3%A9zier_curve" target="_blank">Wikipedia.</a>
  548. </p>
  549. <h4><a id="straightConnector">Straight Connector</a></h4>
  550. <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.
  551. </p>
  552. <h4><a id="flowchartConnector">Flowchart Connector</a></h4>
  553. <p>This type of Connector draws a connection that consists of a series of vertical or horizontal segments - the classic flowchart look. A single constructor argument is supported:</p>
  554. <strong>stub</strong> - this is the minimum length, in pixels, of the initial stub that emanates from an Endpoint. This parameter is optional, and defaults to 30 pixels.
  555. <p>This Connector supports Connection that start and end on the same element.</p>
  556. <h4><a id="stateMachineConnector">State Machine Connector</a></h4>
  557. <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:
  558. </p>
  559. <p>
  560. <strong>margin</strong> - Optional; defaults to 5. Defines the distance from the element that the connector begins/ends.
  561. </p>
  562. <p>
  563. <strong>curviness</strong> - Optional, defaults to 10. This has a similar effect to the curviness parameter on Bezier curves.
  564. </p>
  565. <p>
  566. <strong>proximityLimit</strong> - Optional, defaults to 80. The minimum distance between the two ends of the Connector before it paints itself as
  567. a straight line rather than a quadratic Bezier curve.
  568. </p>
  569. </div>
  570. <div class="section">
  571. <h3><a id="endpoints">Endpoint Types</a></h3>
  572. <p>An Endpoint is the UI component that marks the location of an Anchor, ie. the place where a Connector joins an
  573. 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
  574. <strong>endpoint</strong> parameter in a call to jsPlumb.connect, jsPlumb.addEndpoint, jsPlumb.makeSource or jsPlumb.makeTarget.
  575. </p>
  576. <p>As with Connectors and Overlays, you specify Endpoints using the syntax described above in <a href="#definitions">Connector, Endpoint &amp; Overlay Definitions.</a></p>
  577. The four available Endpoint types, and their constructor arguments, are as follows:
  578. <h4><a id="dotEndpoint">Dot Endpoint</a></h4>
  579. This Endpoint draw a dot on the screen. It supports three constructor parameters:
  580. <p>
  581. <strong>radius</strong> - Optional; defaults to 10 pixels. Defines the radius of the dot.
  582. </p>
  583. <p>
  584. <strong>cssClass</strong> - Optional. A CSS class to attach to the element the Endpoint creates.
  585. </p>
  586. <p>
  587. <strong>hoverClass</strong> - Optional. A CSS class to attach to the element the Endpoint creates whenever the mouse is hovering over the
  588. element or an attached Connection.
  589. </p>
  590. <h4><a id="rectangleEndpoint">Rectangle Endpoint</a></h4>
  591. Draws a rectangle. Supported constructor parameters are:
  592. <p>
  593. <strong>width</strong> - Optional; defaults to 20 pixels. Defines the width of the rectangle.
  594. </p>
  595. <p>
  596. <strong>height</strong> - Optional; defaults to 20 pixels. Defines the height of the rectangle.
  597. </p>
  598. <p>
  599. <strong>cssClass</strong> - Optional. A CSS class to attach to the element the Endpoint creates.
  600. </p>
  601. <p>
  602. <strong>hoverClass</strong> - Optional. A CSS class to attach to the element the Endpoint creates whenever the mouse is hovering over the
  603. element or an attached Connection.
  604. </p>
  605. <h4><a id="imageEndpoint">Image Endpoint</a></h4>
  606. Draws an image from a given URL. This Endpoint supports three constructor parameters:
  607. <p>
  608. <strong>src</strong> - Required. Specifies the URL of the image to use.
  609. </p>
  610. <p>
  611. <strong>cssClass</strong> - Optional. A CSS class to attach to the element the Endpoint creates.
  612. </p>
  613. <p>
  614. <strong>hoverClass</strong> - Optional. A CSS class to attach to the element the Endpoint creates whenever the mouse is hovering over the
  615. element or an attached Connection.
  616. </p>
  617. <h4><a id="blankEndpoint">Blank Endpoint</a></h4>
  618. 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 ans assign to it a CSS class that causes it to be transparent.
  619. </div>
  620. <div class="section">
  621. <h3><a id="overlays">Overlay Types</a></h3>
  622. <p>
  623. Overlays are UI elements that are painted onto connections, such as labels or arrows.
  624. jsPlumb comes with four defaults:
  625. </p>
  626. <ul>
  627. <li><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>
  628. <li><strong>Label</strong> - a configurable label that is painted at some point along the connector.</li>
  629. <li><strong>PlainArrow</strong> - an Arrow shaped as a triangle, with no foldback.</li>
  630. <li><strong>Diamond</strong> - as the name suggests, a diamond.</li>
  631. </ul>
  632. The last two are actually just configured instances of the generic Arrow overlay (see examples).
  633. <p>All Overlays support these two methods for getting/setting their location (location is a number between 0 and 1 inclusive, indicating some point along the path
  634. inscribed by the associated Connector):</p>
  635. <ul>
  636. <li class="bullet"><strong>getLocation</strong> - returns the current location</li>
  637. <li class="bullet"><strong>setLocation</strong> - sets the current location; valid values are decimals in the range 0-1 inclusive</li>
  638. </ul>
  639. <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
  640. are always derived from what the source of a Connection defines) The three cases are discussed below:</p>
  641. 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
  642. a label with the text "foo":
  643. <div class="code">
  644. <pre>jsPlumb.connect({
  645. ...
  646. overlays:[
  647. "Arrow",
  648. [ "Label", { label:"foo", location:0.25 }, id:"myLabel" ]
  649. ],
  650. ...
  651. });
  652. </pre>
  653. </div>
  654. 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>
  655. parameter; it can be used later if you wish to remove the Overlay or change its visibility (see below).<br/><br/>
  656. 2. Specifying one or more overlays on a jsPlumb.addEndpoint call. Note in this example that we use the parameter 'connectorOverlays' and not
  657. 'overlays' as in the last example. This is because 'overlays' would refer to Endpoint Overlays:
  658. <div class="code">
  659. <pre>jsPlumb.addEndpoint("someDiv", {
  660. ...
  661. connectorOverlays:[
  662. [ "Arrow", { width:10, length:30, location:1, id:"arrow" } ],
  663. [ "Label", { label:"foo", id:"label" } ]
  664. ],
  665. ...
  666. });</pre>
  667. </div>
  668. 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,
  669. note that <strong>id</strong> parameter passed in to each Overlay spec.<br/><br/>
  670. 3. Specifying one or more overlays on a jsPlumb.makeSource call. Note in this example that we again use the parameter 'connectorOverlays' and not
  671. 'overlays'. The 'endpoint' parameter to jsPlumb.makeSource supports everything you might pass to the second argument of a jsPlumb.addEndpoint call:
  672. <div class="code">
  673. <pre>jsPlumb.makeSource("someDiv", {
  674. ...
  675. endpoint:{
  676. connectorOverlays:[
  677. [ "Arrow", { width:10, length:30, location:1, id:"arrow" } ],
  678. [ "Label", { label:"foo", id:"label" } ]
  679. ]
  680. }
  681. ...
  682. });</pre>
  683. </div>
  684. 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,
  685. note that <strong>id</strong> parameter passed in to each Overlay spec.<br/><br/>
  686. <h4><a id="arrowOverlay">Arrow Overlay</a></h4>
  687. <p>This overlay draws an arrow, using four points: the head and two tail points, and a 'foldback' point, which permits the tail
  688. of the arrow to be indented. Available constructor arguments for this Overlay are </p>
  689. <ul>
  690. <li><strong>width</strong> - width of the tail of the arrow</li>
  691. <li><strong>length</strong> - distance from the tail of the arrow to the head</li>
  692. <li><strong>location</strong> - where, as a proportional value from 0 to 1 inclusive, the Arrow should appear on the Connector</li>
  693. <li><strong>direction</strong> - which way to point. Allowed values are 1 (the default, meaning forwards) and -1, meaning backwards </li>
  694. <li><strong>foldback</strong> - how far along the axis of the arrow the tail points foldback in to. Default is 0.623.</li>
  695. <li><strong>paintStyle</strong> - a style object in the form used for paintStyle values for Endpoints and Connectors</li>
  696. </ul>
  697. <h4><a id="plainArrowOverlay">PlainArrow Overlay</a></h4>
  698. <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>
  699. <h4><a id="diamondOverlay">Diamond Overlay</a></h4>
  700. <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 PlainArrow.</p>
  701. <h4><a id="labelOverlay">Label Overlay</a></h4>
  702. This provides a text label to decorate Connectors with. The available constructor arguments are:
  703. <ul>
  704. <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>
  705. <li><strong>cssClass</strong> - Optional css class to use for the Label. This is now preferred over using the 'labelStyle' parameter.</li>
  706. <li><strong>labelStyle</strong> - (deprecated, use cssClass instead) Optional arguments for the label's appearance. Valid entries in this JS object are:
  707. <ul>
  708. <li><em>font</em> - a font string in a format suitable for the Canvas element</li>
  709. <li><em>fillStyle</em> - the color to fill the label's background with. Optional.</li>
  710. <li><em>color</em> - the color of the label's text. Optional.</li>
  711. <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>
  712. <li><em>borderWidth</em> - optional width in pixels for the label's border. Defaults to 0.</li>
  713. <li><em>borderStyle</em> - optional. The color to paint the border, if there is one.</li>
  714. </ul>
  715. </li>
  716. <li><strong>location</strong> - As for Arrow Overlay. Where, proportionally from 0 to 1 inclusive, the label should appear.</li>
  717. </ul>
  718. The Label overlay offers two methods - getLabel and setLabel - for accessing/manipulating its content dynamically:
  719. <div class="code">
  720. <pre>
  721. var c = jsPlumb.connect({
  722. source:"d1",
  723. target:"d2",
  724. overlays:[
  725. [ "Label", {label:"FOO", id:"label"}]
  726. ]
  727. });
  728. ...
  729. var label = c.getOverlay("label");
  730. console.log("Label is currently", label.getLabel());
  731. label.setLabel("BAR");
  732. console.log("Label is now", label.getLabel());
  733. </pre>
  734. </div>
  735. 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.
  736. <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:
  737. <div class="code">
  738. <pre>
  739. var conn = jsPlumb.connect({
  740. source:"d1",
  741. target:"d2",
  742. label:"FOO"
  743. });
  744. ...
  745. console.log("Label is currently", conn.getLabel());
  746. conn.setLabel("BAR");
  747. console.log("Label is now", conn.getLabel());
  748. </pre>
  749. </div>
  750. 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 getLabel:
  751. <div class="code">
  752. <pre>
  753. var conn = jsPlumb.connect({
  754. source:"d1",
  755. target:"d2"
  756. });
  757. ...
  758. conn.setLabel(function(c) {
  759. var s = new Date();
  760. return s.getTime() + "milliseconds have elapsed since 01/01/1970";
  761. });
  762. console.log("Label is now", conn.getLabel());
  763. </pre>
  764. </div>
  765. <h4><a id="hideshowOverlay">Hiding/Showing Overlays</a></h4>
  766. <p>You can control the visibility of Overlays using the <strong>setVisible</strong> method of Overlays themselves, or with
  767. <strong>showOverlay(id)</strong> or <strong>hideOverlay(id)</strong> on a Connection.</p>
  768. <p>Remember the <strong>id</strong> parameter that we specified in the examples above? This can be used to retrieve the Overlay
  769. from a Connection:</p>
  770. <div class="code">
  771. <pre>var connection = jsPlumb.connect({
  772. ...
  773. overlays:[
  774. "Arrow",
  775. [ "Label", { label:"foo", location:0.25 }, id:"myLabel" ]
  776. ],
  777. ...
  778. });
  779. // time passes
  780. var overlay = connection.getOverlay("myLabel");
  781. // now you can hide this Overlay:
  782. overlay.setVisible(false);
  783. // there are also hide/show methods:
  784. overlay.show();
  785. overlay.hide();
  786. </pre>
  787. </div>
  788. <p>However, Connection and Endpoint also have two convenience methods you could use instead:
  789. <div class="code">
  790. <pre>var connection = jsPlumb.connect({
  791. ...
  792. overlays:[
  793. "Arrow",
  794. [ "Label", { label:"foo", location:0.25 }, id:"myLabel" ]
  795. ],
  796. ...
  797. });
  798. // time passes
  799. connection.hideOverlay("myLabel");
  800. // more time passes
  801. connection.showOverlay("myLabel");
  802. </pre>
  803. </div>
  804. <h4><a id="hideshowOverlay">Removing Overlays</a></h4>
  805. <p>Connection and Endpoint also have a <strong>removeOverlay</strong> method, that does what you might expect:
  806. <div class="code">
  807. <pre>var connection = jsPlumb.connect({
  808. ...
  809. overlays:[
  810. "Arrow",
  811. [ "Label", { label:"foo", location:0.25 }, id:"myLabel" ]
  812. ],
  813. ...
  814. });
  815. // time passes
  816. connection.removeOverlay("myLabel");
  817. </pre>
  818. </div>
  819. </div>
  820. <div class="section">
  821. <h3><a id="defaults">Defaults</a></h3>
  822. The easiest way to set a look and feel for your plumbing is to override the defaults that jsPlumb uses. If you
  823. do not do this you are forced to provide your overridden values on every call. Every argument to the connect and addEndpoint methods has an
  824. associated default value in jsPlumb.<br/><br/>
  825. The defaults that ship with jsPlumb are stored in <em>jsPlumb.Defaults</em>, which is a Javascript object. Valid entries, and their initial values, are:
  826. <div class="code">
  827. <pre>
  828. Anchor : "BottomCenter",
  829. Anchors : [ null, null ],
  830. Connector : "Bezier",
  831. ConnectionOverlays : [ ],
  832. DragOptions : { },
  833. DropOptions : { },
  834. Endpoint : "Dot",
  835. EndpointOverlays : [ ],
  836. Endpoints : [ null, null ],
  837. EndpointStyle : { fillStyle : null },
  838. EndpointStyles : [ null, null ],
  839. EndpointHoverStyle : null,
  840. EndpointHoverStyles : [ null, null ],
  841. HoverPaintStyle : null,
  842. LabelStyle : { color : "black" },
  843. LogEnabled : false,
  844. Overlays : [ ],
  845. MaxConnections : 1,
  846. MouseEventsEnabled : true,
  847. PaintStyle : { lineWidth : 8, strokeStyle : "#456" },
  848. RenderMode : "svg",
  849. Scope : "_jsPlumb_DefaultScope"
  850. </pre>
  851. </div>
  852. <p>
  853. Note that in EndpointStyle, the default fillStyle is 'null'. This instructs jsPlumb to use the strokeStyle
  854. from the attached connector to fill the endpoint.</p>
  855. <p>Note also that you can specify either or both (or neither) of 'EndpointStyle' and 'EndpointStyles'. This allows you to specify a different
  856. end point for each end of a connection. 'Endpoint' and 'Endpoints' use the same concept. jsPlumb will look first in the
  857. individual endpoint/endpoint style arrays, and then fall back to the single default version.</p>
  858. you can override these defaults by including this in a script somewhere:
  859. <div class="code">
  860. <pre>
  861. jsPlumb.Defaults.PaintStyle = {
  862. lineWidth:13,
  863. strokeStyle: 'rgba(200,0,0,100)'
  864. }
  865. jsPlumb.Defaults.DragOptions = { cursor: "crosshair" };
  866. jsPlumb.Default.Endpoints = [ [ "Dot", 7 ], [ "Dot", 11 ] ];
  867. jsPlumb.Defaults.EndpointStyles = [{ fillStyle:"#225588" }, { fillStyle:"#558822" }];</pre>
  868. </div>
  869. after the jsPlumb script has been loaded of course! Here we have specified the following default behaviour:
  870. <ul>
  871. <li>- connectors are 13 pixels wide and painted with a semi-transparent red line</li>
  872. <li>- when dragging an element the crosshair cursor is used</li>
  873. <li>- the source endpoint is a dot of radius 7; the target endpoint is a dot of radius 11</li>
  874. <li>- the source endpoint is blue; the target endpoint is green</li>
  875. </ul>
  876. <h5>jsPlumb.importDefaults</h5>
  877. From version 1.3.6 onwards there is a helper method called <strong>importDefaults</strong> that allows you to import a set of values with just one call to jsPlumb. Here's the previous example using importDefaults:
  878. <div class="code">
  879. <pre>
  880. jsPlumb.importDefaults({
  881. PaintStyle : {
  882. lineWidth:13,
  883. strokeStyle: 'rgba(200,0,0,100)'
  884. },
  885. DragOptions : { cursor: "crosshair" },
  886. Endpoints : [ [ "Dot", 7 ], [ "Dot", 11 ] ],
  887. EndpointStyles : [{ fillStyle:"#225588" }, { fillStyle:"#558822" }]
  888. });</pre>
  889. </div>
  890. </div>
  891. <div class="section">
  892. <h3><a id="simpleConnections">Connections</a></h3>
  893. <h4><a id="simpleConnections">Programmatic Connections</a></h4>
  894. The most simple connection you can make with jsPlumb looks like this:
  895. <div class="code">
  896. <pre>
  897. jsPlumb.connect({source:"element1", target:"element2"});</pre>
  898. </div>
  899. In this example we have created a Connection from 'element1' to 'element2'. Remember that a Connection in jsPlumb consists of two Endpoints,
  900. a Connector, and zero or more Overlays. But this call to 'connect' supplied none of those things, so jsPlumb uses the default values wherever it needs to.
  901. In this case, default values have been used for the following:
  902. <ul>
  903. <li>- The type and appearance of each Endpoint in the Connection. jsPlumb's default for this is the "Dot" endpoint, of radius 10, with fill color "#456".</li>
  904. <li>- The Anchors that define where the connection's Endpoints appear on each element. The jsPlumb default is "BottomCenter"</li>
  905. <li>- Whether or not each Endpoint can be a source or target for new Connections. The default is false.</li>
  906. <li>- The type and appearance of the Connection's Connector. The default is a "Bezier" connector of line width 8, and color "#456".</li>
  907. </ul>
  908. <p>
  909. So this call will result in an 8px Bezier, colored "#456", from the bottom center of 'element1' to the bottom center of 'element2', and each
  910. Endpoint will be a 10px radius Dot Endpoint, colored "#456".
  911. </p>
  912. <p>
  913. Let's beef up this call a little and tell jsPlumb what sort of Endpoints we want, and where we want them:
  914. </p>
  915. <div class="code">
  916. <pre>
  917. jsPlumb.connect({
  918. source:"element1",
  919. target:"element2",
  920. anchors:["RightMiddle", "LeftMiddle" ],
  921. endpoint:"Rectangle",
  922. endpointStyle:{ fillStyle: "yellow" }
  923. });
  924. </pre>
  925. </div>
  926. <p>This is what we have told jsPlumb we want this time:</p>
  927. <ul>
  928. <li><strong>anchors</strong> - this array tells jsPlumb where the source and target Endpoints should be located on their parent elements. In this case,
  929. we use the shorthand syntax to name one of jsPlumb's default anchors; you can also specify custom locations (see <a href="#anchors">anchors</a>).
  930. Instead of <strong>anchors</strong> you can use <strong>anchor</strong>, if you want the source and target Endpoints to be located at the
  931. same place on their parent elements. <br/>
  932. </li>
  933. <li>
  934. <strong>endpoint</strong> - this tells jsPlumb to use the "Rectangle" Endpoint for both the source and target of the Connection. As with anchors,
  935. <strong>endpoint</strong> has a plural version that allows you to specify a different Endpoint for each end of the Connection.<br/>
  936. </li>
  937. <li>
  938. <strong>endpointStyle</strong> - this is the definition of the appearance of the Endpoint you specified above. Again, there is a
  939. plural equivalent of this that allows you to specify a different style for each end of the Connection. For more information about
  940. allowed values for this value, see <a href="#paintstyles">Connector, Endpoint & Overlay Styles</a>.
  941. </li>
  942. </ul>
  943. <h5>Reusing common settings between jsPlumb.connect calls</h5>
  944. <p>
  945. A fairly common situation you will find yourself in is wanting to create a bunch of Connections that have only minor differences
  946. between them. To support that, <strong>jsPlumb.connect</strong> takes an optional second argument. For example:
  947. </p>
  948. <div class="code">
  949. <pre>
  950. var common = {
  951. anchors:[ "BottomCenter", "TopCenter" ],
  952. endpoints:["Dot", "Blank" ]
  953. };
  954. jsPlumb.connect({ source:"someElement", target:"someOtherElement" }, common);
  955. jsPlumb.connect({ source:"aThirdElement", target:"yetAnotherElement" }, common);
  956. </pre>
  957. </div>
  958. <h5>Endpoints created by jsPlumb.connect</h5>
  959. <p>If you supply an element id or selector for either the source or target , jsPlumb.connect will automatically create an Endpoint on the
  960. given element. These automatically created Endpoints are not marked as drag source or targets, and cannot
  961. be interacted with. For some situations this behaviour is perfectly fine, but for more interactive UIs you should set things up using the drag and drop
  962. method discussed below.</p>
  963. <p>Given that jsPlumb.connect creates its own Endpoints in some circumstances, in order to avoid leaving orphaned Endpoints around the place, if the Connection is subsequently
  964. deleted, these created Endpoints are deleted too. Should you want to, you can override this behaviour by setting <strong>deleteEndpointsOnDetach</strong> to
  965. false in the connect call:</p>
  966. <div class="code">
  967. <pre>
  968. jsPlumb.connect({
  969. source:"aThirdElement",
  970. target:"yetAnotherElement",
  971. deleteEndpointsOnDetach:false
  972. });
  973. </pre>
  974. </div>
  975. <h4><a id="draggableConnections">Connections using Drag and Drop</a></h4>
  976. To support drag and drop connections, you first need to set a few things up. Every drag and drop connection needs at least a source
  977. Endpoint that the user can drag a connection from. Here's a simple example of how to create an Endpoint:
  978. <div class="code">
  979. <pre>
  980. var endpointOptions = { isSource:true };
  981. var endpoint = jsPlumb.addEndpoint('elementId', endpointOptions);
  982. </pre>
  983. </div>
  984. This Endpoint will act as a source for new Connections, and will use the jsPlumb defaults for its own appearance and that of any Connections that are drawn from it.
  985. <h5>Tip: use the three-argument addEndpoint method for common data </h5>
  986. One thing that happens quite often is that you have an Endpoint whose appearance and behaviour is largely the
  987. same between usages on different elements, with just a few differences.
  988. <div class="code">
  989. <pre>
  990. var exampleGreyEndpointOptions = {
  991. endpoint:"Rectangle",
  992. paintStyle:{ width:25, height:21, fillStyle:'#666' },
  993. isSource:true,
  994. connectorStyle : { strokeStyle:"#666" },
  995. isTarget:true
  996. };
  997. </pre>
  998. </div>
  999. Notice there is no 'anchor' set. Here we apply it to two elements, at a different location in each:
  1000. <div class="code">
  1001. <pre>
  1002. jsPlumb.addEndpoint('element1', { anchor:"BottomCenter" }, exampleGreyEndpointOptions));
  1003. jsPlumb.addEndpoint('element2', { anchor:"TopCenter" }, exampleGreyEndpointOptions));
  1004. </pre>
  1005. </div>
  1006. <p>
  1007. Now that you have a source Endpoint, you need to either create a target Endpoint on some element, or notify jsPlumb that you wish to make an
  1008. entire element a drop target. Let's look at how to attach a target Endpoint first:
  1009. </p>
  1010. <div class="code">
  1011. <pre>var endpointOptions = { isTarget:true, endpoint:"Rectangle", paintStyle:{ fillStyle:"gray" } };
  1012. var endpoint = jsPlumb.addEndpoint("otherElementId", endpointOptions);
  1013. </pre>
  1014. </div>
  1015. <p>
  1016. This Endpoint, a gray rectangle, has declared that it can act as a drop target for Connections.
  1017. </p>
  1018. <p>
  1019. jsPlumb also supports marking entire elements as drag sources or drag targets, using the <strong>makeSource</strong> and <strong>makeTarget</strong> methods. This is a useful function for certain applications. Each of these methods takes an Endpoint declaration which defines the Endpoint that jsPlumb will create after a Connection has been attached. Let's take a look at makeTarget first:
  1020. </p>
  1021. <h4><a id="sourcesAndTargets">Elements as sources &amp; targets</a></h4>
  1022. jsPlumb also supports turning entire elements into Connection sources and targets, using the methods <strong>makeSource</strong> and <strong>makeTarget</strong>. With these methods you mark an element as a source or target, and provide an Endpoint specification for jsPlumb to use when a Connection is established. makeSource also gives you the ability to mark some child element as the place from which you wish to drag Connections, but still have the Connection on the main element after it has been established.
  1023. <p>These methods honour the jsPlumb defaults - if, for example you set up the default Anchors to be this:</p>
  1024. <div class="code">
  1025. <pre>
  1026. jsPlumb.Defaults.Anchors = [ "LeftMiddle", "BottomRight" ];
  1027. </pre>
  1028. </div>
  1029. ... and then used makeSource and makeTarget without specifying Anchor locations, jsPlumb would use "LeftMiddle" for the makeSource element and "BottomRight" for the makeTarget element.
  1030. <p>
  1031. A further thing to note about makeSource and makeTarget is that from 1.3.6 onwards any prior calls to one of these methods is honoured by subsequent calls to jsPlumb.connect. This helps when you're building a UI that uses this functionality at runtime but which loads some initial data, and you want the statically loaded data to have the same appearance and behaviour as dynamically created connections (obviously quite a common use case).
  1032. <p>For example:</p>
  1033. <div class="code">
  1034. <pre>
  1035. jsPlumb.makeSource("el1", {
  1036. anchor:"Continuous",
  1037. endpoint:["Rectangle", { width:40, height:20 }]
  1038. });
  1039. ...
  1040. jsPlumb.connect({source:"el1", target:"el2"});
  1041. </pre>
  1042. </div>
  1043. In this example, the source of the connection will be a Rectangle of size 40x20, having a Continuous Anchor.
  1044. <p>You can override this behaviour by setting a <strong>newConnection</strong> parameter on the connect call:</p>
  1045. <div class="code">
  1046. <pre>
  1047. jsPlumb.makeSource("el1", {
  1048. anchor:"Continuous",
  1049. endpoint:["Rectangle", { width:40, height:20 }]
  1050. });
  1051. ...
  1052. jsPlumb.connect({ source:"el1", target:"el2", newConnection:true });
  1053. </pre>
  1054. </div>
  1055. <h5><a id="makeTarget">jsPlumb.makeTarget</a></h5>
  1056. <p>
  1057. This method takes two arguments, the first of which specifies some element (or list of elements); the second specifies the Endpoint you wish to create on that element whenever a Connection is established on it. In this example we will use the exact same target Endpoint we used before - the gray rectangle - but we will tell jsPlumb that the element "aTargetDiv" will be the drop target:
  1058. </p>
  1059. <div class="code">
  1060. <pre>var endpointOptions = {
  1061. isTarget:true,
  1062. maxConnections:5,
  1063. endpoint:"Rectangle",
  1064. paintStyle:{ fillStyle:"gray" }
  1065. };
  1066. jsPlumb.makeTarget("aTargetDiv", endpointOptions);
  1067. </pre>
  1068. </div>
  1069. <p>
  1070. The allowed values in 'endpointOptions' are identical for both the <strong>jsPlumb.addEndpoint</strong> and <strong>jsPlumb.makeTarget</strong> methods, but makeTarget supports an extended
  1071. anchor syntax that allows you more control over the location of the target endpoint. This is discussed below.
  1072. </p>
  1073. <p>Notice in the 'endpointOptions' object above there is a 'isTarget' parameter set - this may seem incongruous, since you know you're going to make some element a target. Remember that the endpointOptions object is the information jsPlumb will use to create an Endpoint on the given target element each time a Connection is established to it. It takes the exact same format as you would pass to addEndpoint; makeTarget is essentially a deferred addEndpoint call followed by a connect call. So in this case, we're telling jsPlumb that any Endpoints it happens to create on some element that was configured by the makeTarget call are themselves Connection targets.
  1074. </p>
  1075. <h5>Unique Endpoint per Target </h5>
  1076. <p>jsPlumb will create a new Endpoint using the supplied information every time a new Connection is established on the target element, by default, but you can override this behaviour and tell jsPlumb that it should create at most one Endpoint, which it should attempt to use for subsequent Connections:
  1077. </p>
  1078. <div class="code">
  1079. <pre>var endpointOptions = {
  1080. isTarget:true,
  1081. uniqueEndpoint:true,
  1082. endpoint:"Rectangle",
  1083. paintStyle:{ fillStyle:"gray" }
  1084. };
  1085. jsPlumb.makeTarget("aTargetDiv", endpointOptions);
  1086. </pre>
  1087. </div>
  1088. Here, the <strong>uniqueEndpoint</strong> parameter tells jsPlumb that there should be at most one Endpoint on this element. Notice that 'maxConnections' is not set: the default is 1, so in this setup we have told jsPlumb that "aTargetDiv" can receive one Connection and no more.
  1089. <h5>Deleting Endpoints on Detach</h5>
  1090. By default, any Endpoints created using makeTarget have <strong>deleteEndpointsOnDetach</strong> set to true, which means that once all Connections to that Endpoint are removed, the Endpoint is deleted. You can override this by setting the flag to true on the makeTarget call:
  1091. <div class="code">
  1092. <pre>var endpointOptions = {
  1093. isTarget:true,
  1094. maxConnections:5,
  1095. uniqueEndpoint:true,
  1096. deleteEndpointsOnDetach:false,
  1097. endpoint:"Rectangle",
  1098. paintStyle:{ fillStyle:"gray" }
  1099. };
  1100. jsPlumb.makeTarget("aTargetDiv", endpointOptions);
  1101. </pre>
  1102. </div>
  1103. In this setup we have told jsPlumb to create an Endpoint the first time "aTargetElement" is connected to, and to not delete it even if there are no longer any Connections to it. The created Endpoint will be reused for subsequent Connections, and can support a maximum of 5.
  1104. <h5>Target Anchors positions with makeTarget</h5>
  1105. <p>When using the makeTarget method, jsPlumb allows you to provide a callback function to be used to determine
  1106. the appropriate location of a target anchor for every new Connection dropped on the given target. It may be the
  1107. case that you want to take some special action rather than just relying on one of the standard anchor mechanisms.
  1108. </p>
  1109. <p>This is achieved through an extended anchor syntax (note that this syntax is <strong>not supported</strong> in
  1110. the <strong>jsPlumb.addEndpoint</strong> method) that supplies a "positionFinder" to the anchor specification. jsPlumb
  1111. provides two of these by default; you can register your own on jsPlumb and refer to them by name, or just
  1112. supply a function. Here's a few examples:</p>
  1113. Instruct jsPlumb to place the target anchor at the exact location at which the mouse button was released on the
  1114. target element. Note that you tell jsPlumb the anchor is of type "Assign", and you then provide a "position"
  1115. parameter, which can be the name of some position finder, or a position finder function itself:
  1116. <div class="code">
  1117. <pre>
  1118. jsPlumb.makeTarget("someElement", {
  1119. anchor:[ "Assign", {
  1120. position:"Fixed"
  1121. }]
  1122. });
  1123. </pre>
  1124. </div>
  1125. <p><strong>Fixed</strong> is one of the two default position finders provided by jsPlumb. The other is <strong>Grid</strong>:
  1126. <div class="code">
  1127. <pre>
  1128. jsPlumb.makeTarget("someElement", {
  1129. anchor:[ "Assign", {
  1130. position:"Grid",
  1131. grid:[3,3]
  1132. }]
  1133. });
  1134. </pre>
  1135. </div>
  1136. The Grid position finder takes a "grid" parameter that defines the size of the grid required. [3,3] means
  1137. 3 rows and 3 columns.
  1138. <h5>Supplying your own position finder</h5>
  1139. <p>To supply your own position finder to jsPlumb you first need to create the callback function. First let's take a look at what the source code for the Grid position finder looks like:</p>
  1140. <div class="code">
  1141. <pre>
  1142. function(eventOffset, elementOffset, elementSize, constructorParams) {
  1143. var dx = eventOffset.left - elementOffset.left, dy = eventOffset.top - elementOffset.top,
  1144. gx = elementSize[0] / (constructorParams.grid[0]),
  1145. gy = elementSize[1] / (constructorParams.grid[1]),
  1146. mx = Math.floor(dx / gx), my = Math.floor(dy / gy);
  1147. return [ ((mx * gx) + (gx / 2)) / elementSize[0], ((my * gy) + (gy / 2)) / elementSize[1] ];
  1148. }
  1149. </pre>
  1150. </div>
  1151. The four arguments are:
  1152. <ul>
  1153. <li class="bullet"><strong>eventOffset</strong> - Page left/top where the mouse button was released (a JS object containing left/top members like you get from a jQuery offset call)</li>
  1154. <li class="bullet"><strong>elementOffset</strong> - JS offset object containing offsets for the element on which the Connection is to be created</li>
  1155. <li class="bullet"><strong>elementSize</strong> - [width, height] array of the dimensions of the element on which the Connection is to be created</li>
  1156. <li class="bullet"><strong>constructorParams</strong> - the parameters that were passed to the Anchor's constructor. In the example given above, those parameters are 'position' and 'grid'; you can pass arbitrary parameters.
  1157. </ul>
  1158. The return value of this function is an array of [x, y] - proportional values between 0 and 1 inclusive, such as you can pass to a static Anchor.
  1159. <p>To make your own position finder you need to create a function that takes those four arguments and returns an [x, y] position for the anchor, for example:</p>
  1160. <div class="code">
  1161. <pre>
  1162. jsPlumb.AnchorPositionFinders.MyFinder = function(dp, ep, es, params) {
  1163. ...
  1164. return [ some maths ];
  1165. };
  1166. </pre>
  1167. </div>
  1168. Then refer to it in a makeTarget call:
  1169. <div class="code">
  1170. <pre>
  1171. jsPlumb.makeTarget("someElement", {
  1172. anchor:[ "Assign", {
  1173. position:"MyFinder",
  1174. myCustomParameter:"foo",
  1175. anInteger:5
  1176. }]
  1177. });
  1178. </pre>
  1179. </div>
  1180. <h5><a id="makeSource">jsPlumb.makeSource</a></h5>
  1181. There are two use cases supported by this method. The first is the case that you want to drag a Connection from the element itself and have an Endpoint attached to the element when a Connection is established. The second is a more specialised case: you want to drag a Connection from the element, but once the Connection is established you want jsPlumb to move it so that its source is on some other element. For an example of this second case, check out the <a href="../../demo/jquery/stateMachineDemo.html">State Machine Connectors</a> demonstration.
  1182. <p>Here's an example code snippet for the basic use case of makeSource:</p>
  1183. <div class="code">
  1184. <pre>
  1185. jsPlumb.makeSource(someDiv, {
  1186. paintStyle:{ fillStyle:"yellow" },
  1187. endpoint:"Blank",
  1188. anchor:"BottomCenter"
  1189. });
  1190. </pre>
  1191. </div>
  1192. <p>
  1193. Notice again that the second argument is the same as the second argument to an addEndpoint call. makeSource is, essentially, a type of addEndpoint call. In this example we have told jsPlumb that we will support dragging Connections directly from 'someDiv'. Whenever a Connection is established between 'someDiv' and some other element, jsPlumb assigns an Endpoint at BottomCenter of 'someDiv', fills it yellow, and sets that Endpoint as the newly created Connection's source.
  1194. </p>
  1195. <p>Configuring an element to be an entire Connection source using makeSource means that the element cannnot itself be draggable. There would be no way for jsPlumb to distinguish between the user attempting to drag the element and attempting to drag a Connection from the element. If your UI works in such a way that that is acceptable then you'll be fine to use this method. But if you want to drag Connections from some element but also have the element be draggable itself, you might want to consider the second use case. First, a code snippet:</p>
  1196. <div class="code">
  1197. <pre>
  1198. jsPlumb.makeSource("someConnectionSourceDiv", {
  1199. paintStyle:{ fillStyle:"yellow" },
  1200. endpoint:"Blank",
  1201. anchor:"BottomCenter",
  1202. parent:"someDiv"
  1203. });
  1204. </pre>
  1205. </div>
  1206. <p>The only difference here is the inclusion of the 'parent' parameter. It instructs jsPlumb to configure the source Endpoint on the element specified - in this case, "someDiv" (the value of this parameter may be a String id or a selector).</p>
  1207. <p>Again, I'd suggest taking a look at the <a href="../../demo/jquery/stateMachineDemo.html">State Machine Connectors demonstration</a> for an example of this.</p>
  1208. <p>
  1209. There are many things you can set in an Endpoint options object; for a thorough list see the API documentation for Endpoint.
  1210. </p>
  1211. <p>Here's an example of specifying that you want an Arrow overlay halfway along any Connection dragged from this Endpoint:</p>
  1212. <div class="code">
  1213. <pre>
  1214. var exampleGreyEndpointOptions = {
  1215. endpoint:"Rectangle",
  1216. paintStyle:{ width:25, height:21, fillStyle:'#666' },
  1217. isSource:true,
  1218. connectorStyle : { strokeStyle:"#666" },
  1219. isTarget:true,
  1220. connectorOverlays: [ [ "Arrow", { location:0.5 } ] ]
  1221. };
  1222. </pre>
  1223. </div>
  1224. This is an Endpoint that moves around the element it is attached to dependent on the location of other elements in the connections it is attached to (a 'dynamic' anchor):
  1225. <div class="code">
  1226. <pre>
  1227. var exampleGreyEndpointOptions = {
  1228. endpoint:"Rectangle",
  1229. paintStyle:{ width:25, height:21, fillStyle:'#666' },
  1230. isSource:true,
  1231. connectorStyle : { strokeStyle:"#666" },
  1232. isTarget:true,
  1233. connectorOverlays: [ [ "Arrow", { location:0.5 } ] ]
  1234. anchor:[ "TopCenter","RightMiddle","BottomCenter","LeftMiddle" ]
  1235. };
  1236. </pre>
  1237. </div>
  1238. <h5><a id="dragOptions">Drag Options</a></h5>
  1239. These are options that will be passed through to the supporting library's drag API. jsPlumb passes everything you supply here through, inserting
  1240. wrapping functions if necessary for the various lifecycle events that jsPlumb needs to know about. So if, for example, you pass a function to be
  1241. called when dragging starts, jsPlumb will wrap that function with a function that does what jsPlumb needs to do, then call yours.
  1242. <p>
  1243. At the time of writing, jsPlumb supports jQuery, MooTools and YUI3, and each of those libraries uses different terminology. In addition, jQuery's API is
  1244. more fully featured, providing easy support for setting the zIndex and opacity of elements being dragged, as well as the 'scope' for a drag/drop (allowing
  1245. you to specify more than one type of drag/drop pair), and hover classes for when a draggable is on the move or
  1246. over a droppable. If you're using jQuery you can of course just supply these values on the dragOptions; to make it easier, jsPlumb's MooTools and YUI3 adapters recognize
  1247. these options and add appropriate callbacks for you.
  1248. </p>
  1249. <p>
  1250. Given that the options here are library-specific, and they are all well-documented, we're going to discuss just the three drag options
  1251. that behave the same way in all (see below for hoverClass):
  1252. <ul>
  1253. <li><strong>opacity</strong> - the opacity of an element that is being dragged. Should be a fraction between 0 and 1 inclusive.</li>
  1254. <li><strong>zIndex</strong> - the zIndex of an element that is being dragged.</li>
  1255. <li><strong>scope</strong> - the scope of the draggable. can only be dropped on a droppable with the same scope. this is discussed below.</li>
  1256. </ul>
  1257. </p>
  1258. <p>For more information about drag options, take a look at the <a href="http://docs.jquery.com/UI/Draggable" target="_blank">jQuery</a>, <a href="http://mootools.net/docs/more/Drag/Drag.Move" target="_blank">MooTools</a>, or <a href="http://developer.yahoo.com/yui/3/dd/" target="_blank">YUI3</a> docs.
  1259. </p>
  1260. <p><strong>NOTE: there is an issue in Chrome that affects the 'cursor' argument to drag options in jQuery. See these links:</strong>
  1261. </p><p>
  1262. <a href="http://forum.jquery.com/topic/draggable-cursor-option-does-not-work" target="_blank">http://forum.jquery.com/topic/draggable-cursor-option-does-not-work</a><br/>
  1263. <a href="http://forum.jquery.com/topic/chrome-text-select-cursor-on-drag" target="_blank">http://forum.jquery.com/topic/chrome-text-select-cursor-on-drag</a>
  1264. </p>
  1265. You should put something like this at the top of your JS to avoid it (perhaps not something so drastic as a document-wide override):
  1266. <div class="code">
  1267. <pre>document.onselectstart = function () { return false; };</pre>
  1268. </div>
  1269. <h5><a id="dropOptions">Drop Options</a></h5>
  1270. Drop options are treated by jsPlumb in the same way as drag options - they are passed through to the underlying library. MooTools does not have drop options like jQuery and YUI3 do; droppable functionality in MooTools
  1271. is actually implemented by the Drag.Move class - the one used to initialise a draggable. But when you setup an Endpoint in jsPlumb you should ignore
  1272. that fact, and treat droppables like you would in jQuery or YUI3. jsPlumb wires everything up for you under the hood.
  1273. <p>There are three jQuery droppable options that jsPlumb treats as shortcuts in MooTools and YUI3, for the sake of consistency:</p>
  1274. <ul>
  1275. <li><strong>hoverClass</strong> - the CSS class to attach to the droppable when a draggable is hovering over it.</li>
  1276. <li><strong>activeClass</strong> - the CSS class to attach to the droppable when a draggable is, um, being dragged.</li>
  1277. <li><strong>scope</strong> - the scope of the draggable. The draggable can only be dropped on a droppable with the same scope. This is discussed below.</li>
  1278. </ul>
  1279. <p>For more information about drop options when using jQuery, see <a href="http://docs.jquery.com/UI/Droppable" target="_blank">here</a>.</p>
  1280. <h5><a id="dragAndDropScope">Drag and Drop Scope</a></h5>
  1281. jsPlumb borrowed the concept of 'scope' from jQuery's drag/drop implementation: the notion of
  1282. which draggables can be dropped on which droppables. In jsPlumb you can provide a 'scope' entry when
  1283. creating an Endpoint. Here's the example grey Endpoint example with 'scope' added:
  1284. <div class="code">
  1285. <pre>
  1286. var exampleGreyEndpointOptions = {
  1287. endpoint:"Rectangle",
  1288. paintStyle:{ width:25, height:21, fillStyle:"#666" },
  1289. isSource:true,
  1290. connectionStyle : { strokeStyle:"#666" },
  1291. isTarget:true,
  1292. scope:"exampleGreyConnection"
  1293. };</pre>
  1294. </div>
  1295. If you do not provide a 'scope' entry, jsPlumb uses a default scope. Its value is accessible through this method:
  1296. <div class="code">
  1297. <pre>
  1298. jsPlumb.getDefaultScope();
  1299. </pre>
  1300. </div>
  1301. If you want to change it for some reason you can do so with this method:
  1302. <div class="code">
  1303. <pre>
  1304. jsPlumb.setDefaultScope("mySpecialDefaultScope");
  1305. </pre>
  1306. </div>
  1307. You can also, should you want to, provide the scope value separately on the drag/drop options, like this:
  1308. <div class="code">
  1309. <pre>
  1310. var exampleGreyEndpointOptions = {
  1311. endpoint:"Rectangle",
  1312. paintStyle:{ width:25, height:21, fillStyle:'#666' },
  1313. isSource:true,
  1314. connectionStyle : { strokeStyle:"#666" },
  1315. isTarget:true,
  1316. dragOptions:{ scope:"dragScope" },
  1317. dropOptions:{ scope:"dropScope" }
  1318. };</pre>
  1319. </div>
  1320. </div>
  1321. <div class="section">
  1322. <h3><a id="beforeDrop">Interceptors</a></h3>
  1323. <p>
  1324. Interceptors were new in jsPlumb 1.3.4. They are basically event handlers from which you can return a value that tells jsPlumb to abort what it is that
  1325. it was doing. There are currently two interceptors supported - <strong>beforeDrop</strong>, which is called when the user has dropped a Connection onto some target,
  1326. and <strong>beforeDetach</strong>, which is called when the user is attempting to detach a Connection.
  1327. </p>
  1328. <p>Interceptors can be registered via the <strong>bind</strong> method on jsPlumb just like any other event listeners, and they can also be passed in to
  1329. the <strong>jsPlumb.addEndpoint</strong>, <strong>jsPlumb.makeSource</strong> and <strong>jsPlumb.makeTarget</strong>
  1330. methods. A future version of jsPlumb will support registering interceptors on Endpoints using the <strong>bind</strong> method as you can now with the jsPlumb object.
  1331. Note that binding 'beforeDrop' (as an example) on jsPlumb itself is like a catch-all: it will be called every time a Connection is dropped on _any_
  1332. Endpoint. But passing a 'beforeDrop' callback into an Endpoint (and in the future, registering one using 'bind') constrains that callback to just the
  1333. Endpoint in question.
  1334. <h4><a id="beforeDrop">Before Drop</a></h4>
  1335. This is called when the user has released the mouse button over a Connection target. Your callback is passed the
  1336. a JS object containing these fields:
  1337. <ul>
  1338. <li>sourceId</li>
  1339. <li>targetId</li>
  1340. <li>scope</li>
  1341. </ul>
  1342. <p>Returning false - or nothing - from this callback will cause the drag to be abandoned, and the new Connection removed from the UI.</p>
  1343. <h4><a id="beforeDetach">Before Detach</a></h4>
  1344. This is called when the user has detached a Connection, which can happen for a number of reasons: by default, jsPlumb allows users to drag Connections
  1345. off of target Endpoints, but this can also result from a programmatic 'detach' call. Every case is treated the same by jsPlumb, so in fact it is possible
  1346. for you to write code that attempts to detach a Connection but then denies itself! You might want to be careful with that.
  1347. <p>Note that this interceptor is passed the actual Connection object; this is different from the beforeDrop
  1348. interceptor discussed above: in this case, we've already got a Connection, but with beforeDrop we are yet
  1349. to confirm that a Connection should be created.</p>
  1350. <p>Returning false - or nothing - from this callback will cause the detach to be abandoned, and the Connection will be reinstated/left on its current target.</p>
  1351. </div>
  1352. <div class="section">
  1353. <h3><a id="paintstyles">Paint Styles</a></h3>
  1354. Defining the appearance of Connectors, Endpoints (and Overlays, but this is deprecated in favour of using CSS classes) is achieved through a 'paintStyle' (or a quite similar name...keep reading)
  1355. object passed as a parameter to one of jsPlumb.connect, jsPlumb.addEndpoint, jsPlumb.makeSource or jsPlumb.makeTarget. Depending on the method you are
  1356. calling, the parameter names vary.
  1357. <h5>Connector Paint Styles</h5>
  1358. These are specified in a <em>paintStyle</em> parameter on a call to <strong>jsPlumb.connect</strong>:
  1359. <div class="code">
  1360. <pre>
  1361. jsPlumb.connect({
  1362. source:"el1",
  1363. target:"el2",
  1364. paintStyle:{ strokeStyle:"blue", lineWidth:10 }
  1365. });
  1366. </pre>
  1367. </div>
  1368. or in the <em>connectorPaintStyle</em> parameter on a call to <strong>jsPlumb.addEndpoint</strong> or <strong>jsPlumb.makeSource</strong>:
  1369. <div class="code">
  1370. <pre>
  1371. jsPlumb.addEndpoint("el1", {
  1372. paintStyle:{ fillStyle:"blue", outlineColor:"black", outlineWidth:1 },
  1373. connectorPaintStyle:{ strokeStyle:"blue", lineWidth:10 }
  1374. });
  1375. </pre>
  1376. </div>
  1377. <div class="code">
  1378. <pre>
  1379. jsPlumb.makeSource("el1", {
  1380. paintStyle:{ fillStyle:"blue", outlineColor:"black", outlineWidth:1 },
  1381. connectorPaintStyle:{ strokeStyle:"blue", lineWidth:10 }
  1382. });
  1383. </pre>
  1384. </div>
  1385. Notice the <em>paintStyle</em> parameter in those examples: it is the paint style for the Endpoint, which we'll discuss below.
  1386. <h5>Endpoint Paint Styles</h5>
  1387. These are specified in a <em>paintStyle</em> parameter on a call to <strong>addEndpoint</strong>. This is the example from just above:
  1388. <div class="code">
  1389. <pre>
  1390. jsPlumb.addEndpoint("el1", {
  1391. paintStyle:{ fillStyle:"blue", outlineColor:"black", outlineWidth:1 },
  1392. connectorPaintStyle:{ strokeStyle:"blue", lineWidth:10 }
  1393. });
  1394. </pre>
  1395. </div>
  1396. ...or as the <em>endpointStyle</em> parameter to a <strong>connect</strong> call:
  1397. <div class="code">
  1398. <pre>
  1399. jsPlumb.connect({
  1400. source:"el1",
  1401. target:"el2",
  1402. endpointStyle:{ fillStyle:"blue", outlineColor:"black", outlineWidth:1 },
  1403. paintStyle:{ strokeStyle:"blue", lineWidth:10 }
  1404. });
  1405. </pre>
  1406. </div>
  1407. ... or as an entry in the <em>endpointStyles</em> array passed to a <strong>jsPlumb.connect</strong> call:
  1408. <div class="code">
  1409. <pre>
  1410. jsPlumb.connect({
  1411. source:"el1",
  1412. target:"el2",
  1413. endpointStyles:[
  1414. { fillStyle:"blue", outlineColor:"black", outlineWidth:1 },
  1415. { fillStyle:"green" }
  1416. ],
  1417. paintStyle:{ strokeStyle:"blue", lineWidth:10 }
  1418. });
  1419. </pre>
  1420. </div>
  1421. or as the <em>paintStyle</em> parameter passed to a <strong>makeTarget</strong> or <strong>makeSource</strong> call:
  1422. <div class="code">
  1423. <pre>
  1424. jsPlumb.makeTarget("el1", {
  1425. ...
  1426. paintStyle:{ fillStyle:"blue", outlineColor:"black", outlineWidth:1 },
  1427. ...
  1428. });
  1429. </pre>
  1430. </div>
  1431. <div class="code">
  1432. <pre>
  1433. jsPlumb.makeSource("el1", {
  1434. paintStyle:{ fillStyle:"blue", outlineColor:"black", outlineWidth:1 }
  1435. parent:"someOtherDivIJustPutThisHereToRemindYouYouCanDoThis"
  1436. });
  1437. </pre>
  1438. </div>
  1439. In the first example we made "el1" into a drop target, and defined a paint style for the Endpoint jsPlumb will create when a Connection is
  1440. established. In the second we made "el1" a connection source and assigned the same values for the Endpoint jsPlumb will create when a Connection
  1441. is dragged from that element.
  1442. <h5>Overlay Paint Styles</h5>
  1443. The preferred way to set paint styles for Overlays is to use the <em>cssClass</em> parameter in the constructor arguments of an Overlay definition.
  1444. <h4>Paint Style Parameters</h4>
  1445. This is the full list of parameters you can set in a paintStyle object, but note that <strong>fillStyle</strong> is ignored by Connectors,
  1446. and <strong>strokeStyle</strong> is ignored by Endpoints. Also, if you create a Connection using jsPlumb.connect and do not specify any
  1447. Endpoint styles, the Endpoints will derive their fillStyle from the Connector's strokeStyle.
  1448. <p>
  1449. fillStyle, strokeStyle and outlineColor can be specified using any valid CSS3 syntax.
  1450. </p>
  1451. <ul>
  1452. <li><strong>fillStyle</strong> - color for an Endpoint, eg. rgba(100,100,100,50), "blue", "#456", "#993355", rgb(34, 56, 78).</li>
  1453. <li><strong>strokeStyle</strong> - color for a Connector. see fillStyle examples.</li>
  1454. <li><strong>lineWidth</strong> - width of a Connector's line. An integer.</li>
  1455. <li><strong>outlineWidth</strong> - width of the outline for an Endpoint or Connector. An integer.</li>
  1456. <li><strong>outlineColor</strong> - color of the outline for an Endpoint or Connector. see fillStyle examples.</li>
  1457. <li><strong>dashstyle</strong> - VML and SVG only. This comes from VML, and allows you to create dashed or dotted lines. It has a
  1458. better syntax than the equivalent attribute in SVG (<em>stroke-dasharray</em>, discussed below), so jsPlumb supports this for both renderers.
  1459. The <em>dashstyle</em> attribute is specified as an array of strokes and spaces, where each value is some multiple of <em>the width of
  1460. the Connector</em>, and that's where it's better than SVG, which uses pixels.
  1461. <p>
  1462. <a href="http://www.w3.org/TR/NOTE-VML" target="_blank">The VML spec</a> is a good place to find valid values for dashstyle. Note that
  1463. jsPlumb does not support the string values for this attribute ("solid", "dashdot", etc).
  1464. </p>
  1465. <p>
  1466. In SVG render mode, jsPlumb uses the <em>lineWidth</em> parameter in conjunction with the values in a <em>dashstyle</em> attribute
  1467. to create an appropriate value for <em>stroke-dasharray</em>.
  1468. </p>
  1469. </li>
  1470. <li><strong>stroke-dasharray</strong> - SVG only. This is the SVG equivalent of <em>dashstyle</em>.
  1471. <a href="http://www.w3.org/TR/SVG/painting.html" target="_blank">The SVG spec</a> discusses valid values for this parameter. But be aware
  1472. that jsPlumb does not convert this into a valid <em>dashstyle</em> attribute when using the VML renderer. Better to use <em>dashstyle</em>.
  1473. </li>
  1474. <li><strong>stroke-dashoffset</strong> - SVG only. This is used in SVG to specify how far into the dash pattern to start painting. For more information,
  1475. see <a href="http://www.w3.org/TR/SVG/painting.html" target="_blank">the SVG spec.</a></li>
  1476. <li><strong>joinstyle</strong> - VML and SVG only. As with <em>dashstyle</em>, this is a VML attribute that jsPlumb supports for both VML
  1477. and SVG - jsPlumb turns this into a <em>stroke-linejoin</em> attribute when rendering with SVG. This attribute specifies how you want individual
  1478. segments of connectors to be joined; the VML and SVG specs both have examples of this, of which many are the same between the two, which is
  1479. why jsPlumb will automatically convert this attribute into the SVG equivalent.
  1480. </li>
  1481. <li><strong>stroke-linejoin</strong> - SVG only. This is the equivalent of VML's <em>joinstyle</em> attribute, but as with <em>stroke-dasharray</em>,
  1482. jsPlumb does not convert this into something approriate for VML. So, using <em>joinstyle</em> will enable you to support more browsers with
  1483. less effort.
  1484. </li>
  1485. </ul>
  1486. <h3><a id="hoverpaintstyles">Hover Paint Styles</a></h3>
  1487. Connectors and Endpoints both support the concept of a "hover" paint style - a paint style to use when the mouse is hovering over
  1488. the component. These are specified in the exact same format as paint styles discussed above, but hover paint styles also inherit
  1489. any values from the main paint style. This is because you will typically want to just change the color, or perhaps outline color, of
  1490. a Connector or Endpoint when the mouse is hovering, but leave everything else the same. So having hover paint styles inherit their
  1491. values precludes you from having to define things in more than one place.
  1492. <p>
  1493. The naming convention adopted for hover paint styles is pretty much to insert the word 'hover' into the corresponding main paint
  1494. style parameters. Here are a couple of examples:
  1495. </p>
  1496. <div class="code">
  1497. <pre>
  1498. jsPlumb.connect({
  1499. source:"el1",
  1500. target:"el2",
  1501. paintStyle:{ strokeStyle:"blue", lineWidth:10 },
  1502. hoverPaintStyle:{ strokeStyle:"red" },
  1503. endpointStyle:{ fillStyle:"blue", outlineColor:"black", outlineWidth:1 },
  1504. endpointHoverStyle:{ fillStyle:"red" }
  1505. });
  1506. </pre>
  1507. </div>
  1508. In this example we specified a hover style for both the Connector, and each of its Endpoints. Here's the same thing, but using the plural version, to specify a different hover style for each Endpoint:
  1509. <div class="code">
  1510. <pre>
  1511. jsPlumb.connect({
  1512. source:"el1",
  1513. target:"el2",
  1514. paintStyle:{ strokeStyle:"blue", lineWidth:10 },
  1515. hoverPaintStyle:{ strokeStyle:"red" },
  1516. endpointStyle:{ fillStyle:"blue", outlineColor:"black", outlineWidth:1 },
  1517. endpointHoverStyles:[ { fillStyle:"red" }, { fillStyle:"yellow" } ]
  1518. });
  1519. </pre>
  1520. </div>
  1521. Calls to <strong>addEndpoint</strong>, <strong>makeSource</strong> and <strong>makeTarget</strong> can also specify various hover paint styles:
  1522. <div class="code">
  1523. <pre>
  1524. jsPlumb.addEndpoint("el1", {
  1525. paintStyle:{ fillStyle:"blue", outlineColor:"black", outlineWidth:1 },
  1526. hoverPaintStyle:{ fillStyle:"red" },
  1527. connectorPaintStyle:{ strokeStyle:"blue", lineWidth:10 },
  1528. connectorHoverPaintStyle:{ strokeStyle:"red", outlineColor:"yellow", outlineWidth:1 }
  1529. });
  1530. jsPlumb.makeSource("el2", {
  1531. paintStyle:{ fillStyle:"transparent", outlineColor:"yellow", outlineWidth:1 },
  1532. hoverPaintStyle:{ fillStyle:"red" },
  1533. connectorPaintStyle:{ strokeStyle:"green", lineWidth:3 },
  1534. connectorHoverPaintStyle:{ strokeStyle:"#678", outlineColor:"yellow", outlineWidth:1 }
  1535. });
  1536. jsPlumb.makeTarget("el3", {
  1537. paintStyle:{ fillStyle:"transparent", outlineColor:"yellow", outlineWidth:1 },
  1538. hoverPaintStyle:{ fillStyle:"red" }
  1539. });
  1540. </pre>
  1541. </div>
  1542. In these examples we specified a hover paint style for both the Endpoint we are adding, and any Connections to/from the Endpoint.
  1543. <p>
  1544. Note that <strong>makeTarget</strong> does not support Connector parameters. It is for creating targets only; Connector parameters will be set by the source Endpoint in any Connections that are made to the element that you turned into a target by using this method.</p>
  1545. <h4><a id="gradients">Gradients</a></h4>
  1546. The Canvas and SVG renderers both support gradients. The VML renderer does not. jsPlumb uses its own syntax to define gradients, to abstract out the differences between the syntax required by canvas and that required by SVG.
  1547. <p>There are two types of gradients available - a 'linear' gradient, which consists of colored lines all
  1548. going in one direction, and a 'radial' gradient, which consists of colored circles emanating from one circle to another.
  1549. Because of their basic shape, jsPlumb supports only <em>linear</em> gradients for
  1550. Connectors. But for Endpoints, jsPlumb supports both <em>linear</em> and <em>radial</em> gradients.</p>
  1551. <h5>Connector gradients</h5>
  1552. To specify a linear gradient to use in a Connector, you must add a <em>gradient</em> object to your
  1553. Connector's <em>paintStyle</em>, for instance:
  1554. <div class="code">
  1555. <pre>jsPlumb.connect({
  1556. source : "window2",
  1557. target : "window3",
  1558. paintStyle:{
  1559. gradient:{
  1560. stops:[[0,"green"], [1,"red"]]
  1561. },
  1562. lineWidth:15
  1563. }
  1564. });
  1565. </pre>
  1566. </div>
  1567. Here we have connected window2 to window3 with a 15 pixel wide connector that has a gradient from green to red.</p><p> Notice the <strong>gradient</strong> object and the
  1568. <strong>stops</strong> list inside it - the gradient consists of an arbitrary number of these "color stops". Each color stop is comprised
  1569. of two values - [position, color]. Position must be a decimal value between 0 and 1 (inclusive), and indicates where the color
  1570. stop is situated as a fraction of the length of the entire gradient. Valid values for
  1571. the colors in the <strong>stops</strong> list are the same as those that are valid for <strong>strokeStyle</strong> when describing a color.
  1572. </p>
  1573. As mentioned, the <strong>stops</strong> list can hold an arbitrary number of entries. Here's an example of a gradient that goes from red to blue to green, and back again through blue to red:
  1574. <div class="code">
  1575. <pre>jsPlumb.connect({
  1576. source : 'window2',
  1577. target : 'window3',
  1578. paintStyle : {
  1579. gradient:{
  1580. stops:[[0,'red'], [0.33,'blue'], [0.66,'green'], [0.33,'blue'], [1,'red']]
  1581. },
  1582. lineWidth : 15
  1583. }
  1584. });
  1585. </pre>
  1586. </div>
  1587. <strong>Note:</strong> when using the VML renderer, jsPlumb will simply ignore the gradient directive
  1588. so it is best to ensure you also supply a <em>strokeStyle</em> in your paintStyle object, to give jsPlumb something to fall back on. If you do not supply
  1589. a <em>strokeStyle</em> your Connectors will be painted black. The previous example might look like this, for instance:
  1590. <div class="code">
  1591. <pre>jsPlumb.connect({
  1592. source : 'window2',
  1593. target : 'window3',
  1594. paintStyle:{
  1595. strokeStyle:'red',
  1596. gradient:{
  1597. stops:[[0,'red'], [0.33,'blue'], [0.66,'green'], [0.33,'blue'], [1,'red']]
  1598. },
  1599. lineWidth:15
  1600. }
  1601. });
  1602. </pre>
  1603. </div>
  1604. Notice the <strong>strokeStyle:'red'</strong> directive at the beginning of the parameter list in <strong>paintStyle</strong>.
  1605. <h5>Endpoint gradients</h5>
  1606. Endpoint gradients are specified using the same syntax as Connector gradients. You put the gradient specifier either in the
  1607. <strong>endpoint</strong> member, or if you are specifying different Endpoints for each end of the Connector, in one or both of
  1608. the values in the <strong>endpoints</strong> array. Also, this information applies to the case that you are creating standalone
  1609. Endpoints that you will be configuring for drag and drop creation of new Connections.
  1610. <p>
  1611. This is an example of an Endpoint gradient that is different for each Endpoint in the Connector. This comes from the main demo; it is
  1612. the Connector joining Window 2 to Window 3:
  1613. </p>
  1614. <div class="code">
  1615. <pre>var w23Stroke = 'rgb(189,11,11)';
  1616. jsPlumb.connect({
  1617. source : 'window2',
  1618. target : 'window3',
  1619. paintStyle:{
  1620. lineWidth:8,
  1621. strokeStyle:w23Stroke
  1622. },
  1623. anchors:[ [0.3,1,0,1], "TopCenter" ],
  1624. endpoint:"Rectangle",
  1625. endpointStyles:[
  1626. { gradient : {stops:[[0, w23Stroke], [1, '#558822']] } },
  1627. { gradient : {stops:[[0, w23Stroke], [1, '#882255']] } }
  1628. ]
  1629. });
  1630. </pre>
  1631. </div>
  1632. The first entry in the gradient will be the one that is on the Connector end of the Endpoint. You can of course have as many color stops as
  1633. you want in this gradient, just like with Connector gradients.
  1634. <h5>Applying the gradient in Endpoints</h5>
  1635. Only the Dot and Rectangle endpoints honour the presence of a gradient (and, remember, not in VML). The Image endpoint of course ignores a gradient
  1636. as it does no painting of its own.
  1637. <p>The type of gradient you will see depends on the Endpoint type:</p>
  1638. <ul>
  1639. <li><strong>Dot</strong> - renders a radial endpoint, with color stop 0 on the outside, progressing inwards as we move through color stops.
  1640. <p>Radial gradients actually require more data than linear gradients - in a linear gradient we just move from one point to another, whereas
  1641. in a radial gradient we move from one <em>circle</em> to another. By default, jsPlumb will render a radial gradient using a source
  1642. circle of the same radius as the Endpoint itself, and a target circle of 1/3 of the radius of the Endpoint (both circles share the
  1643. same center as the Endpoint itself). This circle will be offset by radius/2 in each direction.</p>
  1644. <p>You can supply your own values for these inside the gradient descriptor:</p>
  1645. <div class="code">
  1646. <pre>var w34Stroke = 'rgba(50, 50, 200, 1)';
  1647. var w34HlStroke = 'rgba(180, 180, 200, 1)';
  1648. jsPlumb.connect({
  1649. source : 'window3',
  1650. target : 'window4',
  1651. paintStyle:{
  1652. lineWidth:10,
  1653. strokeStyle:w34Stroke
  1654. },
  1655. anchors:[ "RightMiddle", "LeftMiddle" ],
  1656. endpointStyle:{
  1657. gradient : {
  1658. stops:[ [0, w34Stroke], [1, w34HlStroke] ],
  1659. offset:37.5,
  1660. innerRadius:40
  1661. },
  1662. radius:55
  1663. }
  1664. });
  1665. </pre>
  1666. </div>
  1667. Here we have instructed jsPlumb to make the gradient's inner radius 10px instead of the default 25/3 = 8 ish pixels, and the offset in each direction
  1668. will be 5px, instead of the default radius / 2 = 12.5 pixels.
  1669. <p>It is also possible to specify the offset and inner radius as percentages - enter the values as strings with a '%' symbol on the end:</p>
  1670. <div class="code">
  1671. <pre>var w34Stroke = 'rgba(50, 50, 200, 1)';
  1672. var w34HlStroke = 'rgba(180, 180, 200, 1)';
  1673. jsPlumb.connect({
  1674. source : 'window3',
  1675. target : 'window4',
  1676. paintStyle:{
  1677. lineWidth:10,
  1678. strokeStyle:w34Stroke
  1679. },
  1680. anchors:[ "RightMiddle", "LeftMiddle" ],
  1681. endpointStyle:{
  1682. gradient : {
  1683. stops:[ [0, w34Stroke], [1, w34HlStroke] ],
  1684. offset:'68%',
  1685. innerRadius:'73%'
  1686. },
  1687. radius:25
  1688. }
  1689. });
  1690. </pre>
  1691. </div>
  1692. This will give roughly the same output as the example above (the percentages are not entirely exact).<br/><br/>
  1693. </li>
  1694. <li><strong>Rectangle</strong> - renders a linear endpoint, with color stop 0 closest to the end of the Connector</li>
  1695. </ul>
  1696. <h4><a id="svgvmlcss">Styling SVG/VML using CSS</a></h4>
  1697. A nice way of controlling your UI's appearance is to make use of the fact that both SVG and VML can be styled using CSS.
  1698. <p>This section will be expanded in the next few weeks to give some decent examples of how to do so</p>
  1699. </div>
  1700. <div class="section">
  1701. <h3><a id="cssclasses">CSS Class Reference</a></h3>
  1702. jsPlumb attaches classes to each of the UI components it creates.
  1703. <p>These class names are exposed on the jsPlumb object and can be overridden if you need to do so (see the third column in the table) </p>
  1704. <table width="70%" class="table">
  1705. <tr><th>Component</th><th>CSS Class</th><th>jsPlumb Member</th></tr>
  1706. <tr><td>Connector</td><td>_jsPlumb_connector</td><td>connectorClass</td></tr>
  1707. <tr><td>Endpoint</td><td>_jsPlumb_endpoint</td><td>endpointClass</td></tr>
  1708. <tr><td>Overlay</td><td>_jsPlumb_overlay</td><td>overlayClass</td></tr>
  1709. </table>
  1710. <p>You would typically use these to establish appropriate z-indices for your UI.</p>
  1711. </div>
  1712. <div class="section">
  1713. <h3><a id="animation">Animation</a></h3>
  1714. jsPlumb offers an 'animate' function, which wraps the underlying animation engine for whichever library you happen to be using and
  1715. inserts a callback for jsPlumb to repaint whatever it needs to at each step. You could of course do this yourself; it's a convenience
  1716. method really.
  1717. <p>The method signature is:</p>
  1718. <div class="code">
  1719. <pre>
  1720. jsPlumb.animate : function(el, properties, options)
  1721. </pre>
  1722. </div>
  1723. The arguments are as follows:
  1724. <ul>
  1725. <li><strong>el</strong> - element id, or element object from the library you're using.</li>
  1726. <li><strong>properties</strong> - properties for the animation, such as duration etc.</li>
  1727. <li><strong>options</strong> - options for the animation, such as callbacks etc.</li>
  1728. </ul>
  1729. <h4>jQuery and the 'revert' option</h4>
  1730. jQuery offers a 'revert' option that you can use to instruct it to revert a drag under some condition. This is
  1731. rendered in the UI as an animation that returns the drag object from its current location to wherever it started
  1732. out. It's a nice feature. Unfortunately, the animation that runs the revert does not offer any lifecycle
  1733. callback methods - no 'step', no 'complete' - so its not possible for jsPlumb to know that the revert
  1734. animation is taking place.
  1735. </div>
  1736. <div class="section">
  1737. <h3><a id="connectionInfo">Retrieving Connection Information</a></h3>
  1738. jsPlumb offers one fairly versatile method - <strong>getConnections</strong> - to retrieve information about the
  1739. currently managed connections.
  1740. <p>Before you use this method you should understand jsPlumb's notion of 'scope' - documentation
  1741. is <a href="#dragAndDropScope">here</a> </p>
  1742. <h4>Retrieving connections for a single scope</h4>
  1743. <p>To do this, you call getConnections with either no arguments, in which case jsPlumb uses the default scope, or with a string
  1744. specifying one scope</p>
  1745. <div class="code">
  1746. <pre>var connectionList = jsPlumb.getConnections(); // you get a list of Connection objects that are in the default scope.
  1747. </pre>
  1748. </div>
  1749. Compare this with:
  1750. <div class="code">
  1751. <pre>var connectionList = jsPlumb.getConnections("myScope"); // you get a list of Connection objects that are in "myScope".
  1752. </pre>
  1753. </div>
  1754. <h4>More advanced filtering</h4>
  1755. getConnections optionally takes a JS object specifying filter parameters, of which there are three:
  1756. <ul>
  1757. <li>scope - the scope(s) of the connection type(s) you wish to retrieve</li>
  1758. <li>source - limits the returned connections to those that have this source id</li>
  1759. <li>target - limits the returned connections to those that have this target id</li>
  1760. </ul>
  1761. Each of these three parameters may be supplied as a string, or a list of strings - see the examples below.
  1762. <p>
  1763. The return value of a call to getConnection using a JS object as parameter varies on how many scopes you defined. If you defined only
  1764. a single scope then jsPlumb returns you a list of Connections in that scope. Otherwise the return value is a dictionary whose keys are
  1765. scope names, and whose values are lists of Connections. For example, the following call:
  1766. </p>
  1767. <div class="code">
  1768. <pre>
  1769. jsPlumb.getConnections({scope:["someScope", "someCustomScope"]});
  1770. </pre>
  1771. </div>
  1772. would result in this output:
  1773. <div class="code">
  1774. <pre>
  1775. {
  1776. "someScope" : [ 1..n Connections ],
  1777. "someCustomScope": [ 1..m Connections ]
  1778. }
  1779. </pre>
  1780. </div>
  1781. The following examples show the various ways you can get connection information:
  1782. <ul>
  1783. <li>Get all connections:
  1784. <div class="code">
  1785. <pre>
  1786. var c = jsPlumb.getAllConnections();
  1787. </pre>
  1788. </div>
  1789. </li>
  1790. <li>Get all connections for the default scope only (return value is a list):
  1791. <div class="code">
  1792. <pre>
  1793. var c = jsPlumb.getConnections();
  1794. </pre>
  1795. </div>
  1796. </li>
  1797. <li>Get all connections for the given scope (return value is a list):
  1798. <div class="code">
  1799. <pre>
  1800. var c = jsPlumb.getConnections({scope:"myTestScope"});
  1801. </pre>
  1802. </div>
  1803. </li>
  1804. <li>Get all connections for the given scopes (return value is a map of scope names to connection lists):
  1805. <div class="code">
  1806. <pre>
  1807. var c = jsPlumb.getConnections({scope:["myTestScope", "yourTestScope"]});
  1808. </pre>
  1809. </div>
  1810. </li>
  1811. <li>Get all connections for the given source (return value is a map of scope names to connection lists):
  1812. <div class="code">
  1813. <pre>
  1814. var c = jsPlumb.getConnections({source:"mySourceElement"});
  1815. </pre>
  1816. </div>
  1817. </li>
  1818. <li>Get all connections for the given sources (return value is a map of scope names to connection lists):
  1819. <div class="code">
  1820. <pre>
  1821. var c = jsPlumb.getConnections({source:["mySourceElement", "yourSourceElement"]});
  1822. </pre>
  1823. </div>
  1824. </li>
  1825. <li>Get all connections for the given target (return value is a map of scope names to connection lists):
  1826. <div class="code">
  1827. <pre>
  1828. var c = jsPlumb.getConnections({target:"myTargetElement"});
  1829. </pre>
  1830. </div>
  1831. </li>
  1832. <li>Get all connections for the given source and targets (return value is a map of scope names to connection lists):
  1833. <div class="code">
  1834. <pre>
  1835. var c = jsPlumb.getConnections({source:"mySourceElement", target:["target1", "target2"]});
  1836. </pre>
  1837. </div>
  1838. </li>
  1839. <li>Get all connections for the given scope, with the given source and target (return value is a list of connections):
  1840. <div class="code">
  1841. <pre>
  1842. var c = jsPlumb.getConnections({scope:'myScope", source:"mySourceElement", target:"myTargetElement"});
  1843. </pre>
  1844. </div>
  1845. </li>
  1846. </ul>
  1847. </div>
  1848. <div class="section">
  1849. <h3><a id="events">Events</a></h3>
  1850. jsPlumb supports binding to several different events on Connections, Endpoints and Overlays, and also on the jsPlumb
  1851. object itself.
  1852. <h4><a id="jsPlumbEvents">jsPlumb Events</a></h4>
  1853. <p>To bind an event to jsPlumb itself, use <strong>jsPlumb.bind(event, callback)</strong>:</p>
  1854. <div class="code">
  1855. <pre>
  1856. jsPlumb.bind("jsPlumbConnection", function(info) {
  1857. .. update your model in here, maybe.
  1858. });
  1859. </pre>
  1860. </div>
  1861. <p>These are the events you can bind to on the jsPlumb class:</p>
  1862. <ul>
  1863. <li class="bullet"><strong>jsPlumbConnection</strong> - notification a Connection was established.
  1864. <p>
  1865. The callback is passed an object with the following properties:
  1866. </p>
  1867. <div class="code">
  1868. <pre>
  1869. {
  1870. connection : the new Connection. you can register listeners on this etc.
  1871. sourceId : id of the source element in the Connection
  1872. targetId : id of the target element in the Connection
  1873. source : the source element in the Connection
  1874. target : the target element in the Connection
  1875. sourceEndpoint : the source Endpoint in the Connection
  1876. targetEndpoint : the targetEndpoint in the Connection
  1877. }
  1878. </pre>
  1879. </div>
  1880. <p>
  1881. All of the source/target properties are actually available inside the Connection object, but - for one of those rubbish historical
  1882. reasons - are provided separately because of a vagary of the <em>jsPlumbConnectionDetached</em> callback, which is discussed below.
  1883. </p>
  1884. </li>
  1885. <li class="bullet"><strong>jsPlumbConnectionDetached</strong> - notification a Connection was detached.
  1886. <p>
  1887. As with <em>jsPlumbConnection</em>, the callback is passed an object with the following properties:
  1888. </p>
  1889. <div class="code">
  1890. <pre>
  1891. {
  1892. connection : the Connection that was detached.
  1893. sourceId : id of the source element in the Connection <em>before it was detached</em>
  1894. targetId : id of the target element in the Connection before it was detached
  1895. source : the source element in the Connection before it was detached
  1896. target : the target element in the Connection before it was detached
  1897. sourceEndpoint : the source Endpoint in the Connection before it was detached
  1898. targetEndpoint : the targetEndpoint in the Connection before it was detached
  1899. }
  1900. </pre>
  1901. </div>
  1902. <p>
  1903. As mentioned above, the source/target properties are provided separately from the Connection, because this event is fired whenever
  1904. a Connection is either detached and abandoned, or detached from some Endpoint and attached to another. In the latter case, the
  1905. Connection that is passed to this callback is in an indeterminate state (that is, the Endpoints are still in the state they are
  1906. in when dragging, and do not reflect static reality), and so the source/target properties give you the real story.
  1907. </p>
  1908. <p> Like I said above, this is really just for rubbish historical reasons. I'm attempting to document my way out of it!</p>
  1909. </li>
  1910. <li class="bullet"><strong>click</strong> - notification a Connection was clicked. The callback is passed the Connection and the original mouse event.</li>
  1911. <li class="bullet"><strong>dblclick</strong> - notification a Connection was double-clicked. The callback is passed the Connection and the original mouse event.</li>
  1912. <li class="bullet"><strong>endpointClick</strong> - notification an Endpoint was clicked. The callback is passed the Endpoint and the original mouse event.</li>
  1913. <li class="bullet"><strong>endpointDblClick</strong> - notification an Endpoint was double-clicked. The callback is passed the Endpoint and the original mouse event.</li>
  1914. <li class="bullet"><strong>contextmenu</strong> - a right-click on some given component. jsPlumb will report right clicks on both Connections and Endpoints; the callback is passed the component that received the right-click.
  1915. <li class="bullet"><strong>beforeDrag</strong>
  1916. This event is fired when a new connection is about to be dragged. Your callback function
  1917. is passed the Connection that jsPlumb has just created. If you return false (or nothing)
  1918. from this callback, the new Connection is aborted.
  1919. </li>
  1920. <li class="bullet"><strong>beforeDrop</strong>
  1921. This event is fired when a new connection has been dropped. Your callback function
  1922. is passed the Connection that jsPlumb has just created. If you return false (or nothing)
  1923. from this callback, the new Connection is aborted and removed from the UI.
  1924. </li>
  1925. </ul>
  1926. <h4><a id="connectionEvents">Connection Events</a></h4>
  1927. <p>To bind to an event on a Connection, you also use the <strong>bind</strong> method:</p>
  1928. <div class="code">
  1929. <pre>
  1930. var connection = jsPlumb.connect({source:"d1", target:"d2"});
  1931. connection.bind("click", function(conn) {
  1932. console.log("you clicked on ", conn);
  1933. });
  1934. </pre>
  1935. </div>
  1936. <p>These are the Connection events to which you can bind a listener:</p>
  1937. <ul>
  1938. <li class="bullet"><strong>click</strong> - notification a Connection was clicked. The callback is passed the Connection and the original mouse event.</li>
  1939. <li class="bullet"><strong>dblclick</strong> - notification a Connection was double-clicked. The callback is passed the Connection and the original mouse event.</li>
  1940. <li class="bullet"><strong>contextmenu</strong> - a right-click on the Connection. The callback is passed the Connection and the original event.
  1941. <li class="bullet"><strong>mouseenter</strong> - notification the mouse entered the Connection's path. The callback is passed the Connection and the original mouse event.</li>
  1942. <li class="bullet"><strong>mouseexit</strong> - notification the mouse exited the Connection's. The callback is passed the Connection and the original mouse event.</li>
  1943. </ul>
  1944. <h4><a id="endpointEvents">Endpoint Events</a></h4>
  1945. <p>To bind to an event on a Endpoint, you again use the <strong>bind</strong> method:</p>
  1946. <div class="code">
  1947. <pre>
  1948. var endpoint = jsPlumb.addEndpoint("d1", { someOptions } );
  1949. endpoint.bind("click", function(endpoint) {
  1950. console.log("you clicked on ", endpoint);
  1951. });
  1952. </pre>
  1953. </div>
  1954. <p>These are the Endpoint events to which you can bind a listener:</p>
  1955. <ul>
  1956. <li class="bullet"><strong>click</strong> - notification an Endpoint was clicked. The callback is passed the Endpoint and the original mouse event.</li>
  1957. <li class="bullet"><strong>dblclick</strong> - notification an Endpoint was double-clicked. The callback is passed the Endpoint and the original mouse event.</li>
  1958. <li class="bullet"><strong>contextmenu</strong> - a right-click on the Endpoint. The callback is passed the Endpoint and the original event.
  1959. <li class="bullet"><strong>mouseenter</strong> - notification the mouse entered the Endpoint. The callback is passed the Endpoint and the original mouse event.</li>
  1960. <li class="bullet"><strong>mouseexit</strong> - notification the mouse exited the Endpoint. The callback is passed the Endpoint and the original mouse event.</li>
  1961. </ul>
  1962. <h4><a id="overlayEvents">Overlay Events</a></h4>
  1963. Registering event listeners on an Overlay is a slightly different procedure - you provide them as arguments to the Overlay's
  1964. constructor. This is because you never actually act on an 'Overlay' object. Here's how to register a click listener on an Overlay:
  1965. <div class="code">
  1966. <pre>jsPlumb.connect({
  1967. source:"el1",
  1968. target:"el2",
  1969. overlays:[
  1970. [ "Label", {
  1971. events:{
  1972. click:function(labelOverlay, originalEvent) { alert("you clicked on the label overlay for this connection :" + labelOverlay.connection) }
  1973. }
  1974. }]
  1975. ]
  1976. });
  1977. </pre>
  1978. </div>
  1979. </div>
  1980. <div class="section">
  1981. <a id="examples"><h3>jsPlumb.connect Examples</h3></a>
  1982. This section provides examples of how to use the programmatic API to establish Connections.
  1983. <p>
  1984. The basic syntax of a call is that you execute 'connect', providing a source and a target, and optionally a paintStyle and preferences for where you
  1985. want the plumbing to be anchored on each element, as well as the type of connector to use.
  1986. </p>
  1987. <ul>
  1988. <li>Connect window1 to window2 with the default settings:
  1989. <div class="code">
  1990. <pre>jsPlumb.connect({source:"window1", target:"window2"});</pre>
  1991. </div>
  1992. This connects 'window1' to 'window2' using the jsPlumb defaults - a red Bezier curve Connector and black Dot Endpoints.
  1993. </li>
  1994. <li>Connect window1 to window2 with a 15 pixel wide yellow Connector, and a slightly brighter endpoint (remember the default Endpoint is a Dot):
  1995. <div class="code">
  1996. <pre>jsPlumb.connect({
  1997. source:'window1',
  1998. target:'window2',
  1999. paintStyle:{lineWidth:15,strokeStyle:'rgb(243,230,18)'},
  2000. endpointStyle:{fillStyle:'rgb(243,229,0)'}
  2001. });</pre>
  2002. </div>
  2003. </li>
  2004. <li>Connect window1 to window2 with a 15 pixel wide yellow Connector, and a slightly brighter endpoint:
  2005. <div class="code">
  2006. <pre>jsPlumb.connect({
  2007. source:'window1',
  2008. target:'window2',
  2009. paintStyle:{lineWidth:15,strokeStyle:'rgb(243,230,18)'},
  2010. endpointStyle:{fillStyle:'rgb(243,229,0)'}
  2011. });</pre>
  2012. </div>
  2013. </li>
  2014. <li>Connect window3 to 'window4' with a 10 pixel wide, semi opaque blue Connector, anchored to the left middle of window3, and the right middle of window4, with a Rectangle endpoint of width 10 and height 8:
  2015. <div class="code">
  2016. <pre>jsPlumb.connect({
  2017. source:'window3',
  2018. target:'window4',
  2019. paintStyle:{ lineWidth:10, strokeStyle:'rgba(0, 0, 200, 0.5)' },
  2020. anchors:["RightMiddle", "LeftMiddle"],
  2021. endpoint:[ "Rectangle", { width:10, height:8 } ]
  2022. });</pre>
  2023. </div>
  2024. </li>
  2025. <li>Connect window2 to window3 with a default Connector from the top center of window2 to the bottom center of window3, and rectangular endpoints:
  2026. <div class="code">
  2027. <pre>jsPlumb.connect({
  2028. source:'window2',
  2029. target:'window3',
  2030. paintStyle:{lineWidth:8, strokeStyle:'rgb(189,11,11)'},
  2031. anchors:["BottomCenter", "TopCenter"],
  2032. endpoint:"Rectangle"
  2033. });</pre>
  2034. </div>
  2035. </li>
  2036. <li>Connect window1 to window2 with a 15 px wide yellow Bezier. endpoints are a slightly lighter shade of yellow.
  2037. <div class="code">
  2038. <pre>jsPlumb.connect({
  2039. source:'window1',
  2040. target:'window2',
  2041. anchors:["BottomCenter", [0.75,0,0,-1]],
  2042. paintStyle:{lineWidth:15,strokeStyle:'rgb(243,230,18)'},
  2043. endpointStyle:{fillStyle:'rgb(243,229,0)'}
  2044. });</pre>
  2045. </div></li>
  2046. <li>Connect window3 to window4 with a 10px wide blue-ish half transparent Bezier. put endpoints underneath the element they attach to.
  2047. the endpoints have a radial gradient. both ways of specifying gradient positioning are shown here.
  2048. <div class="code">
  2049. <pre>var w34Stroke = 'rgba(50, 50, 200, 1)';
  2050. var w34HlStroke = 'rgba(180, 180, 200, 1)';
  2051. jsPlumb.connect( {
  2052. source:'window3',
  2053. target:'window4',
  2054. paintStyle:{lineWidth:10, strokeStyle:w34Stroke},
  2055. anchors:["RightMiddle", "LeftMiddle"],
  2056. endpointStyle:{ gradient : {stops:[[0, w34Stroke], [1, w34HlStroke]], offset:17.5, innerRadius:15 }, radius:35},
  2057. //endpointStyle:{ gradient : {stops:[[0, w34Stroke], [1, w34HlStroke]], offset:'78%', innerRadius:'73%'}, radius:35 },
  2058. endpointsOnTop:false
  2059. }
  2060. );</pre>
  2061. </div></li>
  2062. <li>Connect window2 to window3 with an 8px red Bezier and default rectangular endpoints. see also how the first anchor is
  2063. specified here - this is how you create anchors in locations jsPlumb does not offer shortcuts for.
  2064. the endpoints in this example have linear gradients applied.
  2065. <div class="code">
  2066. <pre>var w23Stroke = 'rgb(189,11,11)';
  2067. jsPlumb.connect({
  2068. source:'window2',
  2069. target:'window3',
  2070. paintStyle:{lineWidth:8,strokeStyle:w23Stroke},
  2071. anchors:[[0.3,1,0,1], "TopCenter"],
  2072. endpoint:"Rectangle",
  2073. endpointStyles:[{ gradient : {stops:[[0, w23Stroke], [1, '#558822']] }},
  2074. { gradient : {stops:[[0, w23Stroke], [1, '#882255']] }}]
  2075. });</pre>
  2076. </div></li>
  2077. <li>Connect window5 to window6 from center to center, 5px wide line that is green and half transparent. the endpoints are
  2078. 125px in radius and spill out from underneath their elements.
  2079. <div class="code">
  2080. <pre>jsPlumb.connect({
  2081. source:'window5',
  2082. target:'window6',
  2083. anchors:["Center", "Center"],
  2084. paintStyle:{lineWidth:5,strokeStyle:'rgba(0,255,0,0.5)'},
  2085. endpointStyle:{radius:125}
  2086. });</pre>
  2087. </div></li>
  2088. <li>Connect window4 to window5 from bottom right to top left, with a 7px straight line purple connector, and an image as the endpoint,
  2089. placed on top of the element it is connected to.
  2090. <div class="code">
  2091. <pre>jsPlumb.connect({
  2092. source:"window4",
  2093. target:"window5",
  2094. anchors:[ "BottomRight","TopLeft" ],
  2095. paintStyle:{ lineWidth:7, strokeStyle:"rgb(131,8,135)" },
  2096. endpoint:[ "Image", { src:"http://morrisonpitt.com/jsPlumb/img/endpointTest1.png" } ],
  2097. connector:"Straight"
  2098. });</pre>
  2099. </div></li>
  2100. <li>Connect window5 to window6 between their center points with a semi-opaque connector, and 125px endpoints:
  2101. <div class="code">
  2102. <pre>jsPlumb.connect({
  2103. source:"window5",
  2104. target:"window6",
  2105. anchors:[ "Center", "Center" ],
  2106. paintStyle:{ lineWidth:5, strokeStyle:"rgba(0,255,0,0.5)" },
  2107. endpointStyle:{ radius:125 }
  2108. });</pre>
  2109. </div>
  2110. </li>
  2111. <li>Connect window7 to window8 with a 10 pixel wide blue Connector, anchored on the top left of window7 and the bottom right of window8:
  2112. <div class="code">
  2113. <pre>jsPlumb.connect({
  2114. source:"window7",
  2115. target:"window8",
  2116. paintStyle:{ lineWidth:10, strokeStyle:"blue" },
  2117. anchors:[ "TopLeft", "BottomRight" ]
  2118. });
  2119. </pre>
  2120. </div>
  2121. </li>
  2122. <li>Connect the bottom right corner of window4 to the top left corner of window5, with rectangular endpoints of size 40x40 and a hover color of light blue:
  2123. <div class="code">
  2124. <pre>jsPlumb.connect({
  2125. source:"window4",
  2126. target:"window5",
  2127. anchors:["BottomRight","TopLeft"],
  2128. paintStyle:{lineWidth:7,strokeStyle:'rgb(131,8,135)'},
  2129. hoverPaintStyle:{ strokeStyle:"rgb(0, 0, 135)" },
  2130. endpointStyle:{ width:40, height:40 },
  2131. endpoint:"Rectangle",
  2132. connector:"Straight"
  2133. });</pre>
  2134. </div>
  2135. </li>
  2136. <li>Connect window1 to window2 with the default paint settings but provide some drag options (which are passed through to the underlying library's draggable call):
  2137. <div class="code">
  2138. <pre>jsPlumb.connect({source:'window1', target:'window2', dragOptions:{cursor:'crosshair'}});</pre>
  2139. </div>
  2140. </li>
  2141. </div>
  2142. <div class="section">
  2143. <a id="dragAndDropExamples"><h3>Draggable Connections Examples</h3></a>
  2144. This is a list of examples of how to use jsPlumb to create Connections using drag and drop.
  2145. <p>
  2146. The basic procedure is:
  2147. <ol>
  2148. <li>1a. Create Endpoints and register them on elements in your UI</li>
  2149. <li>1b. alternatively, create a source endpoint and then make some element a drop target </li>
  2150. <li>2. Drag and Drop</li>
  2151. </ol>
  2152. That's all there is to it. Of course there are plenty of options you can set when doing this...it will be easier
  2153. to show you some examples:
  2154. </p>
  2155. <ul>
  2156. <li>Define an Endpoint with default appearance, that is both a source and target of new Connections:
  2157. <div class="code">
  2158. <pre>var endpointOptions = { isSource:true, isTarget:true };
  2159. </pre>
  2160. </div>
  2161. </li>
  2162. <li>Register that Endpoint on window3, specifying that it should be located in the top center of the element:
  2163. <div class="code">
  2164. <pre>var window3Endpoint = jsPlumb.addEndpoint('window3', { anchor:"TopCenter" }, endpointOptions );
  2165. </pre>
  2166. </div>
  2167. Notice here the usage of the three-argument addEndpoint - we can reuse 'endpointOptions' with a different Anchor for another element. This is a useful
  2168. practice to get into.<br/><br/>
  2169. </li>
  2170. <li>Now register that Endpoint on window4, specifying that it should be located in the bottom center of the element:
  2171. <div class="code">
  2172. <pre>var window4Endpoint = jsPlumb.addEndpoint('window4', { anchor:"BottomCenter" }, endpointOptions );
  2173. </pre>
  2174. </div>
  2175. Now we have two Endpoints, both of which support drag and drop of new Connections. We can use these to make a programmatic Connection, too, though:<br/><br/>
  2176. </li>
  2177. <li>Connect window3 to window4 with a 25px wide yellow Bezier that has a 'curviness' of 175:
  2178. <div class="code">
  2179. <pre>jsPlumb.connect({
  2180. source:window3Endpoint,
  2181. target:window4Endpoint,
  2182. connector: [ "Bezier", 175 ],
  2183. paintStyle:{ lineWidth:25, strokeStyle:'yellow' }
  2184. });
  2185. </pre>
  2186. </div>
  2187. </li>
  2188. <li>Define an Endpoint that creates Connections that are 20px wide straight lines, that is both a source and target of new Connections,
  2189. and that has a 'scope' of 'blueline'. Also, this Endpoint mandates that once it is full, Connections can
  2190. no longer be dragged from it (even if 'reattach' is specified on a Connection):
  2191. <div class="code">
  2192. <pre>var endpointOptions = {
  2193. isSource:true,
  2194. isTarget:true,
  2195. connector : "Straight",
  2196. connectorStyle: { lineWidth:20, strokeStyle:'blue' },
  2197. scope:"blueline",
  2198. dragAllowedWhenFull:false
  2199. };
  2200. </pre>
  2201. </div>
  2202. </li>
  2203. <li>Define an Endpoint that will be anchored to "TopCenter". It creates Connections that are 20px wide straight lines, that is both a source and target of new Connections,
  2204. and that has a 'scope' of 'blueline'. Also, this Endpoint mandates that once it is full, Connections can
  2205. no longer be dragged from it (even if 'reattach' is specified on a Connection):
  2206. <div class="code">
  2207. <pre>var endpointOptions = {
  2208. anchor:"TopCenter",
  2209. isSource:true,
  2210. isTarget:true,
  2211. connector : "Straight",
  2212. connectorStyle: { lineWidth:20, strokeStyle:'blue' },
  2213. scope:"blueline",
  2214. dragAllowedWhenFull:false
  2215. };
  2216. </pre>
  2217. </div>
  2218. </li>
  2219. <li>Define an Endpoint that will create a dynamic anchor which can be positioned at "TopCenter" or "BottomCenter". It creates Connections that are 20px wide straight lines, it is both a source and target of new Connections,
  2220. and it has a 'scope' of 'blueline'. Also, this Endpoint mandates that once it is full, Connections can
  2221. no longer be dragged from it (even if 'reattach' is specified on a Connection):
  2222. <div class="code">
  2223. <pre>var endpointOptions = {
  2224. anchor:[ "TopCenter", "BottomCenter" ],
  2225. isSource:true,
  2226. isTarget:true,
  2227. connector : "Straight",
  2228. connectorStyle: { lineWidth:20, strokeStyle:'blue' },
  2229. scope:"blueline",
  2230. dragAllowedWhenFull:false
  2231. };
  2232. </pre>
  2233. </div>
  2234. </li>
  2235. <li>Exactly the same as before, but shows how you can use "anchors" instead of "anchor", if that makes you feel happier:
  2236. <div class="code">
  2237. <pre>var endpointOptions = {
  2238. anchors:[ "TopCenter", "BottomCenter" ],
  2239. isSource:true,
  2240. isTarget:true,
  2241. connector : "Straight",
  2242. connectorStyle: { lineWidth:20, strokeStyle:'blue' },
  2243. scope:"blueline",
  2244. dragAllowedWhenFull:false
  2245. };
  2246. </pre>
  2247. </div>
  2248. </li>
  2249. <li>Define an Endpoint that is a 30px blue dot, creates Connections that are 20px wide straight lines, is both a source and target of new Connections,
  2250. has a 'scope' of 'blueline', and has an event handler that pops up an alert (note: the event handler name means this example is jQuery - MooTools
  2251. and YUI3 use different event handler names):
  2252. <div class="code">
  2253. <pre>var endpointOptions = {
  2254. isSource:true,
  2255. isTarget:true,
  2256. endpoint: [ "Dot", { radius:30 } ],
  2257. style:{fillStyle:'blue'},
  2258. connector : "Straight",
  2259. connectorStyle: { lineWidth:20, strokeStyle:'blue' },
  2260. scope:"blueline",
  2261. dropOptions:{ drop:function(e, ui) { alert('drop!'); } }
  2262. };
  2263. </pre>
  2264. </div>
  2265. </li>
  2266. <li>Same example as before, but this is for MooTools, and the Endpoint can support up to 5 connections (the default is 1):
  2267. <div class="code">
  2268. <pre>var endpointOptions = {
  2269. isSource:true,
  2270. isTarget:true,
  2271. endpoint: [ "Dot", { radius:30 } ],
  2272. style:{ fillStyle:'blue' },
  2273. maxConnections:5,
  2274. connector : "Straight",
  2275. connectorStyle: { lineWidth:20, strokeStyle:'blue' },
  2276. scope:"blueline",
  2277. dropOptions:{ onDrop:function(e, ui) { alert('drop!'); } }
  2278. };
  2279. </pre>
  2280. </div>
  2281. </li>
  2282. <li>Same example again, but maxConnections being set to -1 means that the Endpoint has no maximum limit of Connections:
  2283. <div class="code">
  2284. <pre>var endpointOptions = {
  2285. isSource:true,
  2286. isTarget:true,
  2287. endpoint: [ "Dot", {radius:30} ],
  2288. style:{ fillStyle:'blue' },
  2289. maxConnections:-1,
  2290. connector : "Straight",
  2291. connectorStyle: { lineWidth:20, strokeStyle:'blue' },
  2292. scope:"blueline",
  2293. dropOptions:{ onDrop:function(e, ui) { alert('drop!'); } }
  2294. };
  2295. </pre>
  2296. </div>
  2297. </li>
  2298. <li>Same example again, but for YUI3. Note the drop callback is "drop:hit":
  2299. <div class="code">
  2300. <pre>var endpointOptions = {
  2301. isSource:true,
  2302. isTarget:true,
  2303. endpoint: [ "Dot", { radius:30 } ],
  2304. style:{fillStyle:'blue'},
  2305. maxConnections:-1,
  2306. connector : "Straight",
  2307. connectorStyle: { lineWidth:20, strokeStyle:'blue' },
  2308. scope:"blueline",
  2309. dropOptions:{ "drop:hit":function(e, ui) { alert('drop!'); } }
  2310. };
  2311. </pre>
  2312. </div>
  2313. </li>
  2314. <li>Assign a UUID to the endpoint options created above, and add as Endpoints to "window1" and "window2":
  2315. <div class="code">
  2316. <pre>
  2317. jsPlumb.addEndpoint("window1", { uuid:"abcdefg" }, endpointOptions );
  2318. jsPlumb.addEndpoint("window2", { uuid:"hijklmn" }, endpointOptions );
  2319. </pre>
  2320. </div>
  2321. </li>
  2322. <li>Connect the two Endpoints we just registered on "window1" and "window2":
  2323. <div class="code">
  2324. <pre>
  2325. jsPlumb.connect({uuids:["abcdefg", "hijklmn"]});
  2326. </pre>
  2327. </div>
  2328. </li>
  2329. <li>Create a source Endpoint, register it on some element, then make some other element a Connection target:
  2330. <div class="code">
  2331. <pre>
  2332. var sourceEndpoint = { isSource:true, endpoint:[ "Dot", { radius:50 } ] };
  2333. var targetEndpoint = { endpoint:[ "Rectangle", { width:10, height:10 } ] };
  2334. jsPlumb.addEndpoint( "window1", sourceEndpoint );
  2335. jsPlumb.makeTarget( "window2", targetEndpoint );
  2336. </pre>
  2337. </div>
  2338. Notice that the endpoint definition we use on the target window does not include the "isTarget:true" directive. jsPlumb ignores that flag when
  2339. creating a connection using an element as the target; but if you then tried to drag another connection to the Endpoint that was created, you would
  2340. not be able to. To permit that, you would set 'isTarget:true' on the targetEndpoint options defined above.
  2341. </li>
  2342. </ul>
  2343. </div>
  2344. <div class="section">
  2345. <h3><a id="utilityFunctions">Utility Functions</a></h3>
  2346. <ul>
  2347. <li>Detach window5 from all connections
  2348. <div class="code">
  2349. <pre>jsPlumb.detachAll("window5");</pre>
  2350. </div>
  2351. </li>
  2352. <li>Hide all window5's connections
  2353. <div class="code">
  2354. <pre>jsPlumb.hide("window5");</pre>
  2355. </div>
  2356. </li>
  2357. <li>Hide all window5's connections endpoints
  2358. <div class="code">
  2359. <pre>jsPlumb.hide("window5", true);</pre>
  2360. </div>
  2361. </li>
  2362. <li>Show all window5's connections
  2363. <div class="code">
  2364. <pre>jsPlumb.show("window5");</pre>
  2365. </div>
  2366. </li>
  2367. <li>Show all window5's connections and endpoints. Note that in the case that you call jsPlumb.show with two arguments, jsPlumb
  2368. will also not make a connection visible if it determines that the other endpoint in the connection is not visible.
  2369. <div class="code">
  2370. <pre>jsPlumb.show("window5", hide);</pre>
  2371. </div>
  2372. </li>
  2373. <li>Toggle the visibility of window5's connections
  2374. <div class="code">
  2375. <pre>jsPlumb.toggle("window5");</pre>
  2376. </div>
  2377. </li>
  2378. <li>Force repaint of all of window5's connections
  2379. <div class="code">
  2380. <pre>jsPlumb.repaint("window5");</pre>
  2381. </div>
  2382. </li>
  2383. <li>Force repaint of all of window5, window6 and window11's connections
  2384. <div class="code">
  2385. <pre>jsPlumb.repaint( [ "window5", "window6", "window11" ] );</pre>
  2386. </div>
  2387. </li>
  2388. <li>Force repaint of every connection
  2389. <div class="code">
  2390. <pre>jsPlumb.repaintEverything();</pre>
  2391. </div>
  2392. </li>
  2393. <li>Detach every connection that the given instance of jsPlumb is managing
  2394. <div class="code">
  2395. <pre>jsPlumb.detachEveryConnection();</pre>
  2396. </div>
  2397. </li>
  2398. <li>Detach all connections from "window1"
  2399. <div class="code">
  2400. <pre>jsPlumb.detachAllConnections("window1");</pre>
  2401. </div>
  2402. </li>
  2403. <li>Remove the given Endpoint from element "window1", deleting its Connections.
  2404. <div class="code">
  2405. <pre>jsPlumb.removeEndpoint("window1", someEndpoint);</pre>
  2406. </div>
  2407. </li>
  2408. <li>Remove all Endpoints for the element 'window1', deleting their Connections.
  2409. <div class="code">
  2410. <pre>jsPlumb.removeAllEndpoints("window1");</pre>
  2411. </div>
  2412. </li>
  2413. <li>Removes every Endpoint managed by this instance of jsPlumb, deleting all Connections.
  2414. This is the same as jsPlumb.reset(), effectively, but it does not clear out the event listeners list.
  2415. <div class="code">
  2416. <pre>jsPlumb.removeEveryEndpoint();</pre>
  2417. </div>
  2418. </li>
  2419. <li>Deletes the given Endpoint and all its Connections.
  2420. <div class="code">
  2421. <pre>jsPlumb.deleteEndpoint(endpoint);</pre>
  2422. </div>
  2423. </li>
  2424. <li>Removes every endpoint, detaches every connection, and clears the event listeners list. Returns jsPlumb instance to its initial state.
  2425. <div class="code">
  2426. <pre>jsPlumb.reset();</pre>
  2427. </div>
  2428. </li>
  2429. <li>Library-agnostic method to get a selector from the given selector specification. This function is used mostly by the jsPlumb demos, to cut down on repeating code across the different libraries. But perhaps you are writing something with jsPlumb that you also wisht to be library agnostic - this function can help you. The returned object, in each of jQuery, MooTools and YUI, has a ".each" iterator.
  2430. <div class="code">
  2431. <pre>var selector = jsPlumb.getSelector(".someSelector .spec");</pre>
  2432. </div>
  2433. </li>
  2434. <li>Set window1 to be not draggable, no matter what some jsPlumb command may request.
  2435. <div class="code">
  2436. <pre>jsPlumb.setDraggable("window1", false);</pre>
  2437. </div>
  2438. </li>
  2439. <li>Set window1 and window2 to be not draggable, no matter what some jsPlumb command may request.
  2440. <div class="code">
  2441. <pre>jsPlumb.setDraggable(["window1","window2"], false);</pre>
  2442. </div>
  2443. </li>
  2444. <li>Sets whether or not elements that are connected are draggable by default.
  2445. The default for this is true.
  2446. <div class="code">
  2447. <pre>jsPlumb.setDraggableByDefault(false);</pre>
  2448. </div>
  2449. </li>
  2450. <li>Initialises window1 as a draggable element (all libraries). Passes in an on drag callback
  2451. <div class="code">
  2452. <pre>jsPlumb.draggable("window1");</pre>
  2453. </div>
  2454. </li>
  2455. <li>Initialises window1 and window2 as draggable elements (all libraries)
  2456. <div class="code">
  2457. <pre>jsPlumb.draggable(["window1","window2"]);</pre>
  2458. </div>
  2459. </li>
  2460. <li>Initialises window1 as a draggable element (all libraries)
  2461. <div class="code">
  2462. <pre>jsPlumb.draggable("window1");</pre>
  2463. </div>
  2464. </li>
  2465. <li>Initialises all elements with class 'window' as draggable elements (jQuery)
  2466. <div class="code">
  2467. <pre>jsPlumb.draggable($(".window"));</pre>
  2468. </div>
  2469. </li>
  2470. <li>Initialises all elements with class 'window' as draggable elements (MooTools)
  2471. <div class="code">
  2472. <pre>jsPlumb.draggable($$(".window"));</pre>
  2473. </div>
  2474. </li>
  2475. <li>Initialises all elements with class 'window' as draggable elements (YIU3)
  2476. <div class="code">
  2477. <pre>jsPlumb.draggable(Y.all(".window"));</pre>
  2478. </div>
  2479. </li>
  2480. <li>Initialises window1 as a draggable element (jQuery)
  2481. <div class="code">
  2482. <pre>jsPlumb.draggable($("#window1"));</pre>
  2483. </div>
  2484. </li>
  2485. <li>Initialises window1 as a draggable element (MooTools)
  2486. <div class="code">
  2487. <pre>jsPlumb.draggable($("window1"));</pre>
  2488. </div>
  2489. </li>
  2490. <li>Initialises window1 as a draggable element (YUI3)
  2491. <div class="code">
  2492. <pre>jsPlumb.draggable(Y.one("window1"));</pre>
  2493. </div>
  2494. </li>
  2495. </ul>
  2496. </div>
  2497. <div class="section">
  2498. <h3><a id="developingJsPlumb">Advanced Topics</a></h3>
  2499. <h4><a id="which">Which files are which?</a></h4>
  2500. In development, jsPlumb is broken up into seven scripts:
  2501. <ul>
  2502. <li>- jsPlumb-x.x.x.js
  2503. <p>This is the main jsPlumb engine.</p>
  2504. </li>
  2505. <li>- jsPlumb-defaults-x.x.x.js
  2506. <p>This contains the default Anchor, Endpoint, Connector and Overlay implementations.</p>
  2507. </li>
  2508. <li>- jsPlumb-renderers-canvas-x.x.x.js
  2509. <p>This contains the HTML5 canvas render code.</p>
  2510. </li>
  2511. <li>- jsPlumb-renderers-svg-x.x.x.js
  2512. <p>This contains the SVG render code.</p>
  2513. </li>
  2514. <li>- jsPlumb-renderers-vml-x.x.x.js
  2515. <p>This contains the VML render code.</p>
  2516. </li>
  2517. <li>- jsPlumb-connectors-statemachine-x.x.x.js
  2518. <p>This State Machine connector.</p>
  2519. </li>
  2520. <li>- &lt;LIBRARY_PREFIX&gt;.jsPlumb-x.x.x.js
  2521. <p>This contains library-specific helper methods. jsPlumb ships with three of these - one each for jQuery, MooTools and YUI3. See below for information on how to create a new library implementation.</p>
  2522. </li>
  2523. <li>- jsBezier-0.3-min.js
  2524. <p>These are the Bezier curve functions; they are maintained in a separate project called <a href="http://code.google.com/p/jsbezier/">jsBezier</a></p>
  2525. </li>
  2526. </ul>
  2527. These seven files are packaged together to form the scripts that people use, for example:
  2528. <ul>
  2529. <li>jquery.jsPlumb-1.3.6-all.js
  2530. <p>Contains jsPlumb-1.3.6.js, jsPlumb-defaults-1.3.6.js, jsPlumb-renderers-canvas-1.3.6.js, jsPlumb-renderers-svg-1.3.6.js, jsPlumb-renderers-vml-1.3.6.js, jsPlumb-connectors-statemachine-1.3.6.js, jquery.jsPlumb-1.3.6.js and jsBezier-0.3-min.js</p>
  2531. </li>
  2532. <li>jquery.jsPlumb-1.3.6-all-min.js
  2533. <p>A minified version of the script above (minified using the YUI Compressor)</p>
  2534. </li>
  2535. </ul>
  2536. <h4><a id="pluggableLibrarySupport">Pluggable Library Support</a></h4>
  2537. Out of the box, jsPlumb can be run on top of jQuery, MooTools or YUI3. This is achieved by
  2538. delegating several core methods - tasks such as finding an element by id, finding an element's
  2539. position or dimensions, initialising a draggable, etc - to the library in question.
  2540. <p>To develop one of these, your test page should include the first two scripts discussed above, and
  2541. then your own script containing your library specific functionality. The existing implementations
  2542. may be documented well enough for you to create your own, but contact me if you need assistance. If you do this, it would be
  2543. great to share it with everyone...</p>
  2544. <p>There is a group of people working on an ExtJS adapter currently. There is no schedule for when this will be completed though.</p>
  2545. <!-- h4><a id="customConnectors">Custom Connectors</a></h4>
  2546. You can provide your own connectors if you need to. A Connector consists of two functions, which work as a pair. First a call is made to the <em>compute</em> function:
  2547. <div class="code">
  2548. <pre>
  2549. this.compute = function(sourcePos, targetPos, sourceAnchor, targetAnchor, lineWidth) {
  2550. ...
  2551. return dimensions;
  2552. }
  2553. </pre>
  2554. </div>
  2555. which is expected to return a list that the <em>paint</em> function can make sense of. The first four entries in the
  2556. list <strong>must be</strong> the [x,y,width,height] values for the canvas that the connector will be drawn on; jsPlumb will
  2557. use this information to size the canvas prior to calling the Connector's <em>paint</em> function. Therefore it
  2558. is the Connector's responsibility to ensure that the returned dimensions describe a large enough space for
  2559. the line that will be drawn on it.</p><p>The next four elements <strong>must be</strong> the coordinates of the two endpoints of the line
  2560. you are going to draw.</p><p>The remainder of the items in the returned list are arbitrary, and will
  2561. vary between Connector implementations; this list is passed in to a Connector's <em>paint</em> function, so each
  2562. implementation will put into the list whatever it needs to paint itself. For instance, the straight line
  2563. connector only needs the [x,y] location of each end of the line it will paint, and that is one of the required entries, so
  2564. it does not have to do anything extra, whereas the Bezier connector adds the location of the two control points. Other types of
  2565. Connectors will do whatever is appropriate for their particular situation.
  2566. </p>
  2567. This is the method signature for the <em>paint</em> function:
  2568. <div class="code">
  2569. <pre>this.paint = function(dimensions, ctx) { .. }</pre>
  2570. </div>
  2571. here, the 'dimensions' argument to the 'paint' function is the return value of the 'compute' function. The 'ctx' argument is the Canvas context; you
  2572. will do all your drawing on this.
  2573. </p>
  2574. To change the connector from the default, specify it in your connect call:
  2575. <div class="code">
  2576. <pre>jsPlumb.connect({source:'someWindow', target:'otherWindow', connector:new jsPlumb.Connectors.Straight()});</pre>
  2577. </div>
  2578. note that you can use shorthand for connectors if you don't need to specify parameters to it:
  2579. <div class="code">
  2580. <pre>jsPlumb.connect({source:'someWindow', target:'otherWindow', connector:"Straight"});</pre>
  2581. </div>
  2582. This works in the same way as specifying Anchors as string does.
  2583. <p>
  2584. The section below this discusses Overlays, which allow you to decorate Connectors with
  2585. things such as labels or arrows or whatever else you like. Overlays can only work with Connectors that implement a few helper functions.
  2586. <h4>The concept of <strong>location</strong></h4>
  2587. Before discussing the helper functions you first must be across the concept of 'location' as used by this mechanism. The <em>location</em>
  2588. on a connector can be a decimal value between 0 and 1 inclusive, which marks a proportionate amount of travel <em>along the path
  2589. inscribed by the Connector</em>. For a straight line connector this is a simple piece of maths, but for Bezier connectors it's a little
  2590. bit more involved.
  2591. <h4>Required Helper Methods</h4>
  2592. <ul>
  2593. <li><strong>pointOnPath(location)</strong> - returns an [x,y] point corresponding to the given location</li>
  2594. <li><strong>pointAlongPathFrom(location, distance)</strong> - returns an [x,y] point corresponding to travelling 'distance' pixels along the connector from 'location'.</li>
  2595. <li><strong>gradientAtPoint(location)</strong> - returns the connector's gradient at the given location. For linear connectors such as Straight this is constant, but for Bezier connectors the gradient changes continually.</li>
  2596. <li><strong>perpendicularToPathAt(location, distance, length)</strong> - returns a line that is perpendicular to (and centered on) the connector at 'distance' from the given location, with length 'length'.</li>
  2597. </ul>
  2598. </p>
  2599. <h4><a id="customEndpoints">Custom Endpoints</a></h4>
  2600. <p>To create your own Endpoint implementation, you need to implement a single method:
  2601. <div class="code"><pre>paint : function(anchorPoint, orientation, canvas, endpointStyle, connectorPaintStyle) { ... }</pre></div>
  2602. The arguments to this method are as follows:
  2603. <ul>
  2604. <li>anchorPoint - [x,y] location of the anchor point on screen</li>
  2605. <li>orientation - [x,y] hints for the general direction the anchor points to</li>
  2606. <li>canvas - the canvas to draw into</li>
  2607. <li>endpointStyle - Javascript object containing style directives as discussed above. The contents of this are arbitrary, so if you write a new Endpoint that needs some extra settings, you can add them no hassle.</li>
  2608. <li>connectorPaintStyle - the style being used to paint the associated Connector.</li>
  2609. </ul>
  2610. </p>
  2611. <p>
  2612. It is your responsibility to size and locate the canvas to suit your needs. jsPlumb provides the following
  2613. helper method to assist you:
  2614. <div class="code"><pre>jsPlumb.sizeCanvas(canvas, x, y, width, height);</pre></div>
  2615. Allows you to locate the canvas on screen and to size it.
  2616. </p>
  2617. <h4><a id="customOverlays">Custom Overlays</a></h4>
  2618. Overlays can only work with Connectors that implement the methods <strong>pointOnPath</strong>, <strong>pointAlongPathFrom</strong>,
  2619. <strong>gradientAtPoint</strong>, and <strong>perpendicularToPathAt</strong>. These are discussed in more detail in the Custom Connectors section above. Both of the Connectors
  2620. that come with jsPlumb - Straight and Bezier -implement these methods; if you write a custom connector, or have written a custom connector, you will need to supply
  2621. them.
  2622. <h4>Overlay Interface</h4>
  2623. An Overlay is required to implement two methods in order to be usable by jsPlumb:
  2624. <ul>
  2625. <li><strong>computeMaxSize(connector, context)</strong> - returns an integer value indicating the larger of this overlay's width and height. It is used by jsPlumb to ensure that the canvas is large enough to accomodate the overlay. The examples below should help to clarify this.</li>
  2626. <li><strong>draw(connector, ctx)</strong> - draws the overlay. What happens in this method is up to the given implementation.</li>
  2627. </ul>
  2628. <h4>computeMaxSize methods</h4>
  2629. This is the Arrow overlay's computeMaxSize method:
  2630. <div class="code">
  2631. <pre>
  2632. this.computeMaxSize = function() { return width; }
  2633. </pre>
  2634. </div>
  2635. Here, <em>width</em> is a private member of Arrow that indicates the width of the arrow's tail. So the Arrow overlay reports that figure as the width it needs.
  2636. Contrast this with the Label Overlay's computeMaxSize method:
  2637. <div class="code">
  2638. <pre>
  2639. this.computeMaxSize = function(connector, ctx) {
  2640. if (labelText) {
  2641. ctx.save();
  2642. if (self.labelStyle.font) ctx.font = self.labelStyle.font;
  2643. var t = ctx.measureText(labelText).width;
  2644. // a fake text height measurement: use the width of upper case M
  2645. var h = ctx.measureText("M").width;
  2646. labelPadding = self.labelStyle.padding || 0.25;
  2647. labelWidth = t + (2 * t * labelPadding);
  2648. labelHeight = h + (2 * h * labelPadding);
  2649. ctx.restore();
  2650. return Math.max(labelWidth, labelHeight);
  2651. }
  2652. return 0;
  2653. };
  2654. </pre>
  2655. </div>
  2656. The Label overlay has to use the context to determine how big it will be on screen.
  2657. <h4>draw methods</h4>
  2658. To give you a taste for how you can interact with a connector, consider the first few lines of the Arrow overlay's draw method:
  2659. <div class="code">
  2660. <pre>
  2661. this.draw = function(connector, ctx) {
  2662. // this is the arrow head position
  2663. var hxy = connector.pointAlongPathFrom(self.loc, length / 2);
  2664. // this is the center of the tail
  2665. var txy = connector.pointAlongPathFrom(self.loc, -length / 2), tx = txy[0], ty = txy[1];
  2666. // this is the tail vector
  2667. var tail = connector.perpendicularToPathAt(self.loc, -length / 2, width);
  2668. ...
  2669. </pre>
  2670. </div>
  2671. <p>The first two calls to the connector use the <strong>pointAlongPathFrom</strong> method, which passes <em>self.loc</em> as the location of the
  2672. point on the path, and <em>length / 2</em> as the number of pixels along the path to traverse.</p>
  2673. <p><em>self.loc</em> is Arrow's internal member describing the location of the overlay, and it is a decimal (between 0 and 1 inclusive) that points to
  2674. a location at some distance along the path inscribed by the connector. So these first two calls get us [x,y] locations of points on
  2675. the connector that mark the head and tail points for the arrow.
  2676. </p>
  2677. <p>
  2678. The <strong>connector.perpendicularToPathAt(self.loc, -length / 2, width)</strong> call returns a line description of a line that is perpendicular to, and centered on, the connector
  2679. at "-length / 2" pixels from the given point, with the given width (width is an internal member of Arrow). At this point, the Arrow object has the three main points it
  2680. needs in order to draw itself.
  2681. </p>
  2682. </div-->
  2683. </div>
  2684. </body>
  2685. </html>