forked from jgraph/mxgraph
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathmanual.html
More file actions
1655 lines (1380 loc) · 71.1 KB
/
manual.html
File metadata and controls
1655 lines (1380 loc) · 71.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<html>
<head>
<title>mxGraph User Manual - JavaScript Client</title>
<link rel="stylesheet" href="css/manual-styles.css">
<link rel="stylesheet" href="css/manual-colors.css">
<script type="text/javascript" src="js/toc.js"></script>
</head>
<body onload="maketoc(document.getElementById('toc'));">
<h1>mxGraph User Manual – JavaScript Client</h1>
<br/>
<br/>
<p>mxGraph Version 3.9.8 – 06. July 2018</p>
<p>Copyright (c) JGraph Ltd 2006-2017</p>
<br/>
<p>All rights reserved. No part of this publication may be
reproduced, stored in a retrieval system, or transmitted in any form or
by any means, electronic, mechanical, photocopying, recording or
otherwise, without the prior written permission of the author.</p>
<p>The programs in this book have been included for their
instructional value. They have been tested with care but are not
guaranteed for any particular purpose. The publisher does not offer any
warranties or representations nor does it accept any liabilities with
respect to the programs.</p>
<p>Possession, use, or copying of the software described in this
publication is authorized only pursuant to a valid written license from
JGraph Ltd.</p>
<p>Neither JGraph Ltd. nor its employees are responsible for any
errors that may appear in this publication. The information in this
publication is subject to change without notice.</p>
<p>Java and all Java-based marks are trademarks or registered
trademarks of Sun Microsystems, Inc. in the U.S. and other countries.</p>
<br/>
<h1>Table Of Contents</h1>
<div id="toc"></div>
<br/>
<h1><a id="Introduction"></a>Introduction</h1>
<h2><a id="mxGraph_Products"></a>Product Introduction</h2>
<p>mxGraph is a JavaScript component that provides features aimed at applications that display
interactive <a href="http://en.wikipedia.org/wiki/Diagram">diagrams</a>
and graphs. Note by graphs we mean <a
href="http://en.wikipedia.org/wiki/Graph_(mathematics)">mathematical
graphs</a>, not necessarily <a href="http://en.wikipedia.org/wiki/Charts">charts</a>
(although some charts are graphs). See later section “What is a
Graph?” for more details.</p>
<p>Being a developer library, mxGraph is not designed specifically
to provide a ready to use application, although many of the examples are
close to being usable applications. mxGraph provides all the commonly
required functionality to draw, interact with and associate a context
with a diagram. mxGraph comes with a number of examples that help explain how a
basic application is put together and showcases
individual features of the library.</p>
<p>Developers integrating the library in their application should
read the section
“Pre-requisites” below. Given that mxGraph is a component
part of your application, you must understand how JavaScript web
applications are constructed at an architectural level, and how to program
both in JavaScript, as well as any server-side languages used.</p>
<p>mxGraph mainly comprises one JavaScript
file that contains all of the mxGraph functionality. This is loaded into
a HTML web page in a JavaScript section and executes in an HTML
container in the browser. This is an incredibly simple architecture that
only requires a web server capable of serving html pages and a
JavaScript enabled web browser.</p>
<p>The key advantages of this technology are:</p>
<ul>
<li>That no third-party plug-ins are required. This removes
plug-in vendor dependence.</li>
<li>The technologies involved are open and there are many open
implementations, no one vendor can remove a product or technology that
leaves your application unworkable in practise.</li>
<li>Standardized technologies, meaning your application is
deployable to the maximum number of browser users without need for
additional configuration or installation at the client computer. Large
corporate environments often dislike allowing individuals to install
browser plug-ins and do not like to change the standard build rolled
out to all machines.</li>
</ul>
<p><img src="images/mx_man_architecture.png" name="mxgraph_architecture" />
<br/>
<em>The mxGraph components and their relationships</em></p>
<h2><a id="mxgraph_applications"></a>What Applications can
mxGraph be used for?</h2>
<p>Example applications for a graph visualization library include:
process diagrams, workflow and BPM visualization, flowcharts, traffic or
water flow, database and WWW visualization, networks and
telecommunications displays, mapping applications and GIS, UML diagrams,
electronic circuits, VLSI, CAD, financial and social networks, data
mining, biochemistry, ecological cycles, entity and cause-effect
relationships and organisational charts.</p>
<h2><a id="mxgraph_deployment"></a>How is mxGraph deployed?</h2>
<p>In the typical thin-client environment, mxGraph is split into the
client-side JavaScript library and a server-side library in one of the
two supported languages, .NET and Java. The JavaScript library is
contained as part of a larger web application that is delivered to the
browser using a standard web server. All the browser needs is the
ability to run JavaScript to be enabled.</p>
<p>In the third part of this manual, you will see an example of an
html page that embeds the mxGraph library, as well as a simple
application to invoke the library's functionality.</p>
<h2><a id="mxgraph_technologies"></a>mxGraph Technologies</h2>
<p>mxGraph uses JavaScript for the client-side functionality on the
browser. The JavaScript code in turn uses the underlying vector graphics
language on the active browser to render the displayed diagram, currently SVG
for all supported browsers. mxGraph also includes the feature to render entirely
using html, this limits the range of functionality available, but is
suitable for more simple diagrams.</p>
<p>As a developer you are not exposed to browser specific features.
As mentioned, the vector graphics language varies by browser, so mxGraph
abstracts their features into a common class. Similarly, for event
handling and DOMs. Browsers differ in their implementation of these two
major browser functionalities, mxGraph exposes a constant API over all
browsers and adapts to the inconsistencies behind the scenes.</p>
<h2><a id="mxgraph_licensing"></a>mxGraph Licensing</h2>
<p>The JavaScript client of mxGraph is licensed under the
<a href="https://www.apache.org/licenses/LICENSE-2.0"> Apache
2.0 license</a> For detailed licensing questions you are always advised to
consult a legal professional.</p>
<h2><a id="what_graph"></a>What is a Graph?</h2>
<p>Graph visualization is based on the mathematical theory of
networks, graph theory. If you're seeking JavaScript bar <em>charts</em>,
pie <em>charts</em>, Gantt <em>charts</em>, have a look at the <a
href="http://code.google.com/apis/chart/">Google Charts</a> project
instead, or similar</p>
<p>A graph consists of vertices, also called nodes, and of edges
(the connecting lines between the nodes). Exactly how a graph appears
visually is not defined in graph theory. The term <em>cell</em> will be
used throughout this manual to describe an element of a graph, either
edges, vertices or groups.</p>
<p><img src="images/mx_man_simple_graph.png" /><br/>
<em>A simple Graph</em></p>
<br/>
<p>There are additional definitions in graph theory that provide
useful background when dealing with graphs, they are listed in the
Appendices if of interest to you.</p>
<h3><a id="graph_visualization"></a>Graph Visualization</h3>
<p>Visualization is the process of creating a useful visual
representation of a graph. The scope of visualization functionality is
one of mxGraphs' main strength. mxGraph supports a wide range of
features to enable the display of cells to only be limited by the skill
of the developer and the platform functionality available. Vertices may
be shapes, images, vector drawing, animations, virtually any graphical
operations available in browsers. You can also use HTML mark-up in both
vertices and edges.</p>
<p><img src="images/mx_man_graph_vis.png"><br/>
<em>Graph Visualization of a transport system. (c) Tourizm Maps
2003, http://www.world-maps.co.uk</em></p>
<br/>
<h3><a id="graph_interaction"></a>Graph Interaction</h3>
<p>Interaction is the way in which an application using mxGraph can
alter the graph model through the web application GUI. mxGraph supports
dragging and cloning cells, re-sizing and re-shaping, connecting and
disconnecting, drag and dropping from external sources, editing cell
labels in-place and more. One of the key benefits of mxGraph is the
flexibility of how interaction can be programmed.</p>
<p>Many complex graphical web applications rely on a round-trip to
the server in order to form the display, not only the base display but
also the interaction events. Although this is often given the title of
AJAX functionality, such server reliance is not appropriate for
interaction events. Visual feedback taking longer than about 0.2 seconds
in an application generally seriously impacts the usability. By placing
all of the interaction on the client, mxGraph provides the true feel of
a application, rather than seeming like a dumb remote terminal. It also
allows the possibility of off-line use.</p>
<p><img src="images/mx_man_graph_interaction.png" /><br/>
<em>Selection shading while selecting an area through mouse drag</em></p>
<br/>
<h3><a id="graph_layouts"></a>Graph Layouts</h3>
<p>Graph cells can be drawn anywhere in a simple application,
including on top of one another. Certain applications need to present
their information in a generally ordered, or specifically ordered
structure. This might involve ensuring cells do not overlap and stay at
least a certain distance from one another, or that cells appear in
specific positions relative to other cells, usually the cells they are
connected to by edges. This activity, called the layout application, can
be used in a number of ways to assist users in setting out their graph.
For non-editable graphs, layout application is the process of applying a
layout algorithm to the cells. For interactive graphs, meaning those
that can be edited through the UI, layout application might involve only
allowing users to make changes to certain cells in certain positions, to
re-apply the layout algorithm after each change to the graph, or to
apply the layout when editing is complete.</p>
<p><img src="images/mx_man_graph_layout.png" /><br/>
<em>Layout of a workflow using a horizontal hierarchical layout</em></p>
<p>mxGraph supports a range of tree, force-directed and hierarchical
layouts which will fit most layout needs. See the later section on using
the layouts for more information.</p>
<p>In a client-server architecture there are two options for how
layouts can be run. The Javascript versions provide the ability to run
the layouting entirely on the client, while the same layout
implementation in Java on the server-side enables the option to offload
some processing to the server, if required.</p>
<h3><a id="graph_analysis"></a>Graph Analysis</h3>
<p>Analysis of graphs involves the application of algorithms
determining certain details about the graph structure, for example,
determining all routes or the shortest path between two cells. There are
more complex graph analysis algorithms, these being often applied in
domain specific tasks. Techniques such as clustering, decomposition, and
optimization tend to be targeted at certain fields of science and have
not been implemented in the core mxGraph packages at the current time of
writing.</p>
<p><img src="images/mx_man_graph_analysis.jpg"
name="shortest_path_analyis" /><br/>
<em>Shortest Path Analysis</em></p>
<br/>
<h2><a id="about_manual"></a>About this Manual</h2>
<h3><a id="pre_requisites"></a>Pre-requisites for mxGraph</h3>
<p>To benefit fully from this manual you will need to have a
reasonable understanding of web applications and of the server
technology you wish to deploy using. Deployment examples are available
for each of the server technologies supported, some familiarity with
that server technology is obviously required.</p>
<p>Basic XML knowledge is useful for changing the editor
configuration files that describe the visual and behavioural aspects of
the editor. You will need to understand and implement Javascript coding
and be familiar with object orientated programming principles and modern
software design.</p>
<p>You do not need knowledge of the underlying vector graphics
language that the browser uses, such as SVG or HTML canvas. mxGraph
abstracts the description of the visual component into one API.</p>
<h1><a id="Getting_Started"></a>Getting Started</h1>
<h2><a id="mxgraph_site"></a>The mxGraph Package</h2>
<h3><a id="obtaining_mxgraph"></a>Obtaining mxGraph</h3>
<p>
mxGraph is available from the <a href="https://github.com/jgraph/mxgraph">GitHub project</a>.
Released versions are tagged "va.b.c", where a, b and c are version number parts following
<a href="http://semver.org/">semantic versioning</a>.
</p>
<p>
Each formal release is also available as .zip or .tar.gz on the
<a href="https://github.com/jgraph/mxgraph/releases">mxGraph releases</a> page.
</p>
<h3><a id="project_structure"></a>Project structure and build
options</h3>
<p>Once unzipped you will be presented with a number of files and
directories in the installation root.</p>
<TABLE WIDTH=642 BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4
CELLSPACING=0>
<COL WIDTH=165>
<COL WIDTH=459>
<THEAD>
<TR VALIGN=TOP>
<TD WIDTH=165>
<p>/doc</p>
</TD>
<TD WIDTH=459>
<p>Documentation root, includes this user manual</p>
</TD>
</TR>
</THEAD>
<TBODY>
<TR VALIGN=TOP>
<TD WIDTH=165>
<p>/dotnet</p>
</TD>
<TD WIDTH=459>
<p>.NET server-side classes</p>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=165>
<p>/java</p>
</TD>
<TD WIDTH=459>
<p>Java server-side classes</p>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=165>
<p>/javascript</p>
</TD>
<TD WIDTH=459>
<p>JavaScript client functionality.</p>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=165>
<p>/javascript/examples</p>
</TD>
<TD WIDTH=459>
<p>HTML examples demonstrating the use of mxGraph</p>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=165>
<p>ChangeLog</p>
</TD>
<TD WIDTH=459>
<p>Details of the changes between releases</p>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=165>
<p>index.html</p>
</TD>
<TD WIDTH=459>
<p>Basic introduction to the library</p>
</TD>
</TR>
<TR VALIGN=TOP>
<TD WIDTH=165>
<p>license.txt</p>
</TD>
<TD WIDTH=459>
<p>The licensing terms under which you must use the library</p>
</TD>
</TR>
</TBODY>
</TABLE>
<p><em>Table: Project Directory Structure</em></p>
<br/>
<h3><a id="npm"></a>npm</h3>
<p>mxGraph is also available via the npm package manager. To use mxGraph as
a depedency, use <code>npm install</code>:</p>
<pre>npm install mxgraph --save</pre>
<p>The module can be loaded using <code>require()</code>. This returns a
factory function that accepts an object of options. Options such as
<code>mxBasePath</code> must be provided to the factory function, rather
than specified as global variables.</p>
<pre>var mxgraph = require("mxgraph")({
mxImageBasePath: "./src/images",
mxBasePath: "./src"
})</pre>
<p>The factory function returns a 'namespace object' that provides access to
all objects of the mxGraph package. For example, the <code>mxEvent</code>
object is available at <code>mxgraph.mxEvent</code>.</p>
<pre>var mxEvent = mxgraph.mxEvent;
mxEvent.disableContextMenu(container);</pre>
<h2><a id="web_applications"></a>JavaScript and Web Applications</h2>
<p>Web applications, specifically the use of JavaScript to attempt
to emulate desktop application-like behaviour in web browsers, is still
a relatively new field of software engineering. There are three main
issues with JavaScript that are perceived to be a barrier to producing
high quality applications, performance, lack of native functionality
available in desktop applications and inconsistent APIs between
browsers.</p>
<p>There has been considerable effort toward developing framework
libraries to solve two of the problems, the functionality and API
issues. The requirements of many of these libraries is driven by both
improving web site design and usability, as well as to assist production
of what we generally refer to as application features (menus, windows,
dialogs, persistence, event handling, etc). They also provide certain
base functionalities missing in JavaScript that desktop application
developers take for granted, such as basic maths and collections
functionality.</p>
<p>Many of these JavaScript frameworks have IDE support for
development nowadays and all of the major browsers now contain
JavaScript debuggers, either natively or as a plug-in. There is no
compilation phase with JavaScript (it is an interpreted language) so
basic typographical errors are often only caught at runtime, unless you
obtain a syntax checking tool in your IDE. So although there is not one
complete package for your JavaScript development needs, there are a
number of vendors providing the individual components you need to
produce JavaScript applications effectively.</p>
<h3><a id="js_frameworks"></a>Third-Party JavaScript Frameworks</h3>
<h4><a id="native_js_frameworks"></a>Native JavaScript Frameworks
and Libraries</h4>
<p>Rather than list and compare every JavaScript framework, please
see the wikipedia entries for <a
href="http://en.wikipedia.org/wiki/List_of_JavaScript_libraries#JavaScript">web
application frameworks</a> and the <a
href="http://en.wikipedia.org/wiki/Comparison_of_JavaScript_frameworks">comparison
of JavaScript</a>. The comparison should not be considered authoritative,
more so it illustrates the types of features provided, such as event
handling, animation, widgets, AJAX request support etc. <a
href="http://javascriptlibraries.com/">This site</a> is also a useful
list of JavaScript libraries, mostly being open/free source licensed.</p>
<p>Be aware that many frameworks add implicit behaviours to make
JavaScript appear more like an OO language and to increase the base
functionality of the language. During the writing of the layout portion
of mxGraph, it was found that this implicit behaviour broke an example
in a very hard to debug manner. Be aware that this may cause
problems and if you select a framework ensure you understand which
implicit behaviours it introduces.</p>
<p>When selecting a framework and/or libraries think about which
frameworks tie you into certain functional behaviour and look for
libraries that provide features such as animation as distinct,
independent blocks, that you can use without being tied into the overall
design.</p>
<h4><a id="integration_js_frameworks"></a>Integration of mxGraph
and JavaScript frameworks</h4>
<p>This area is often misunderstood, put simply, there is no <em>integration</em>
required. Web applications generally comprise one or more <a
href="http://en.wikipedia.org/wiki/Span_and_div"><em>div</em></a>
elements into which the HTML wrapping the JavaScript of the application
is placed. If you create a div as a container for an mxGraph, that area
is a stand-alone display for the mxGraph application. It can communicate
itself with any back-end server, but there is no interdependence between
that div and the rest of the page, other than the area each take up.
This includes event handling, mxGraph can handle the events for its
container, even if the rest of the web page used a completely different
event model. As long as neither mxGraph nor the other libraries and
frameworks on the page introduce implicit behaviours that break one part
of the page, the issue of client integration is not something that needs
analysis.</p>
<p>Integration of the mxGraph back-end functionality, that which
sits at the server-side is the subject of a later chapter.</p>
<h4><a id="extending_mxgraph"></a>Extending mxGraph in JavaScript</h4>
<p>In JavaScript, there are various ways of mapping the Object
Oriented paradigm to language constructs. mxGraph uses a particular
scheme throughout the project, with the following implicit rules:</p>
<ul>
<li>Do not change the built-in prototypes</li>
<li>Donot try to limit the power of the JavaScript language.</li>
</ul>
<p>There are two types of “classes” in mxGraph; <EM>classes</em>
and <EM>singletons</em> (where only one instance of the class exists).
Singletons are mapped to global objects where the variable name is the
same as the class name. For example, mxConstants is an object with all
the constants defined as object fields. Normal classes are mapped to a
constructor function and a prototype which defines the instance fields
and methods. For example, mxEditor is a function and mxEditor.prototype
is the prototype for the object that the mxEditor function creates. The
<em>mx</em> prefix is a convention that is used for all classes in the
mxGraph package to avoid conflicts with other objects in the global
namespace.</p>
<p>For subclassing, the superclass must provide a constructor that
is either parameterless or handles an invocation with no arguments.
Furthermore, the special constructor field must be redefined after
extending the prototype. For example, the superclass of mxEditor is
mxEventSource. This is represented in JavaScript by first
“inheriting” all fields and methods from the superclass by
assigning the prototype to an instance of the superclass, eg.</p>
<pre>mxEditor.prototype = new mxEventSource()</pre>
<p>and redefining the constructor field using:</p>
<pre>mxEditor.prototype.constructor = mxEditor</pre>
<p>The latter rule is applied so that the type of an object can be
retrieved via the name of it’s constructor using <EM>mxUtils.getFunctionName(obj.constructor)</em>.</p>
<h5><a id="constructor"></a>Constructor</h5>
<p>For subclassing in mxGraph, the same mechanism should be applied.
For example, for subclassing the mxGraph class, first a constructor must
be defined for the new class. The constructor calls the super
constructor with any arguments that it may have using the <em>call</em>
function on the mxGraph function object, passing along explicitly each
argument:</p>
<pre>
function MyGraph(container)
{
mxGraph.call(this, container);
}
</pre>
<p>The prototype of MyGraph inherits from mxGraph as follows. As
usual, the constructor is redefined after extending the superclass:</p>
<pre>MyGraph.prototype = new mxGraph();
MyGraph.prototype.constructor = MyGraph;</pre>
<p>You may want to define the codec associated for the class after
the above code (see I/O section of manual). This code will be executed
at class loading time and makes sure the same codec is used to encode
instances of mxGraph and MyGraph.</p>
<pre>
var codec = mxCodecRegistry.getCodec(mxGraph);
codec.template = new MyGraph();
mxCodecRegistry.register(codec);
</pre>
<h5><a id="functions"></a>Functions</h5>
<p>In the prototype for MyGraph, functions of mxGraph can be
extended as follows.</p>
<pre>
MyGraph.prototype.isSelectable = function(cell)
{
var selectable = mxGraph.prototype.isSelectable.apply(this, arguments);
var geo = this.model.getGeometry(cell);
return selectable &&(geo == null || !geo.relative);
}
</pre>
<p>The supercall in the first line is optional. It is done using the
<em>apply</em> function on the <em>isSelectable</em> function object of
the mxGraph prototype, using the special <em>this</em> andn <em>arguments</em>
variables as parameters. Calls to the superclass function are only
possible if the function is not replaced in the superclass as follows,
which is another way of “subclassing” in JavaScript.</p>
<pre>
mxGraph.prototype.isSelectable = function(cell)
{
var geo = this.model.getGeometry(cell);
return selectable && (geo == null || !geo.relative);
}
</pre>
<p>The above scheme is useful if a function definition needs to be
replaced completely.</p>
<p>In order to add new functions and fields to the subclass, the
following code is used. The example below adds a new function to return
the XML representation of the graph model:</p>
<pre>
MyGraph.prototype.getXml = function()
{
var enc = new mxCodec();
return enc.encode(this.getModel());
}
</pre>
<h5><a id="fields"></a>Fields</h5>
<p>Likewise, a new field is declared and defined as follows:</p>
<pre>
MyGraph.prototype.myField = ‘Hello, World!’;
</pre>
<p>Note that the value assigned to myField is created only once,
that is, all instances of MyGraph share the same value. If you require
instance-specific values, then the field must be defined in the
constructor instead. For example:</p>
<pre>
function MyGraph(container)
{
mxGraph.call(this, container);
this.myField = [];
}
</pre>
<p>Finally, a new instance of MyGraph is created using the following
code, where container is a DOM node that acts as a container for the
graph view:</p>
<pre>
var graph = new MyGraph(container);
</pre>
<br/>
<h3><a id="general_javascript"></a>General JavaScript Development</h3>
<h4><a id="javascript_obfuscation"></a>JavaScript Obfuscation</h4>
<p>By default, when you deliver JavaScript to a browser client, you
deliver the entire source to that JavaScript. That JavaScript is then
interpreted and run on the browser. It is not possible to encrypt the
JavaScript to any extent on the client at the point it is run, since the
JavaScript source must be understood by the JavaScript interpretor and
interpreted languages do not have a binary intermediate form.</p>
<p>It would be possible to encrypt the JavaScript in transmission
and have it decrypted and run on the client, but the client would still
be able to access the source after decryption.</p>
<p>We do not obfuscate because the method names form a public API
and I/O would need to understand the obfuscation at both communication
ends.</p>
<h4><a id="namespaces"></a>Namespaces</h4>
<p>The concept of namespaces does not exist in standised JavaScript, so take
great care when creating new class names. In mxGraph, all of the classes
begin with the prefix “mx-”, to avoid clashes or overriding
prototypes unintentionally.
<br/>
<h2><a id="hello_world"></a>Hello World!</h2>
<p>Hello World in mxGraph consists of a simple client-side example
that displays two connected vertices with the labels “Hello”
and “World!”. The example demonstrates the following things:
</p>
<ul>
<li><strong>Creating an HTML page that links the mxGraph
client JavaScript,</strong></li>
<li><strong>Creating a container to place the mxGraph
into,</strong></li>
<li><strong>Adds the required cells to that graph.</strong></li>
</ul>
<p>The source code for the example, helloworld.html, can be found
below and in the examples directory of both the evaluation and full
versions of mxGraph. The HTML source contains two main sections, the
head and the body. These contain the following main elements that you
can consider a template for building a basic mxGraph application:</p>
<ul>
<li><strong>mxBasePath</strong>: This is a JavaScript variable
that defines the directory within which the css, images, resources and js
directories are expected to be found. It is JavaScript code and needs
to be placed with in a <em>script</em> tag. This must come before the
line loading mxClient.js and should not have a trailing slash.</li>
<li><strong>mxClient.js</strong>: This is the path to mxGraph
library. If the HTML file is executed locally, the path might be local
to the computer or a public Internet path. If the html page were
downloaded from a web server, the path would generally be a public
Internet path.</li>
<li><strong>Creation of the container</strong>: At the bottom of
the code, in the body element, the function that is called on loading
the web page is defined (the value of onload). It passes in a div
container as a parameter, that is defined underneath. This div is the
container the mxGraph component will be placed within. In this example
a grid background is applied, as commonly used in diagramming
applications. No other part of the graph visuals are described at
container creation, other than the background and the container width
and height.
<p>Note that the overflow:hidden style should always be used if you
want no scrollbars to appear.</p>
</li>
<li><strong>The entry function</strong>: The main code of the file
is the entry method executed on page load in this case. This is
JavaScript code and must be within a JavaScript <em>script</em>
element. The first lines of any mxGraph application should be to check
the browser is supported and exit appropriately if not. If the browser
is supported, a mxGraph is created within the div container and three
cells are added to the graph between the begin/end update calls.</li>
</ul>
<br/>
<p><img src="images/mx_man_hello_world.png" name="ill_hello_world" />
<br/>
<em>The mxGraph HelloWorld example</em></p>
<br/>
<pre>
<html>
<head>
<title>Hello, World! example for mxGraph</title>
<!-- Sets the <U>basepath</U> for the library if not in same directory -->
<script type=<em>"text/javascript"</em>>
mxBasePath = '../src';
</script>
<!-- Loads and <U>initializes</U> the library -->
<script type=<em>"text/javascript"</em> src=<em>"../src/js/mxClient.js"</em>></script>
<!-- Example code -->
<script type=<em>"text/javascript"</em>>
// Program starts here. Creates a sample graph in the
// DOM node with the specified ID. This function is invoked
// from the onLoad event handler of the document (see below).
function main(container)
{
// Checks if the browser is supported
if (!mxClient.isBrowserSupported())
{
mxUtils.error('Browser is not supported!', 200, false);
}
else
{
// Creates the graph inside the given container
var graph = new mxGraph(container);
// Enables rubberband selection
new mxRubberband(graph);
// Gets the default parent for inserting new cells. This
// is normally the first child of the root (ie. layer 0).
var parent = graph.getDefaultParent();
// Adds cells to the model in a single step
graph.getModel().beginUpdate();
try
{
var v1 = graph.insertVertex(parent, null,
'Hello,', 20, 20, 80, 30);
var v2 = graph.insertVertex(parent, null,
'World!', 200, 150, 80, 30);
var e1 = graph.insertEdge(parent, null, '', v1, v2);
}
finally
{
// Updates the display
graph.getModel().endUpdate();
}
}
};
</script>
</head>
<!-- Page passes the container for the graph to the program -->
<body onload=<em>"main(document.getElementById('graphContainer'))"</em>>
<!-- Creates a container for the graph with a grid wallpaper -->
<div id=<em>"graphContainer"</em>
style=<em>"overflow:hidden;width:321px;height:241px;background:url('editors/images/grid.gif')"</em>>
</div>
</body>
</html>
</pre>
<p>Important concepts to note in this exercise are:</p>
<ul>
<li>mxClient.js is a JavaScript file combining all of the
JavaScript source code of mxGraph. When downloading from a web server,
obtaining all the JavaScript as one file is much faster than as lots of
separate files, due to the overhead of the requests/acknowledgements
required for each file. The speed increase is usually at least x2,
although it varies with the capacity of the server to have parallel
sockets open with one client.</li>
<li>The JavaScript code and its dependencies are all placed within
the <em>head</em> element.</li>
<li>Internet Explorer has, by default, security options enabled
that cause a user prompt when attempting to run JavaScript from the
local file system. This can be disabled in the options menu, but note
that running from the local file system is not a deployment scenario of
mxGraph, this would only happen during development.</li>
<li>Your application can be written and linked into the
application either within the HTML file, or in separate JavaScript
source code that is linked into the html in the way the mxClient.js
file is in the example.</li>
</ul>
<h2><a id="deployment"></a>mxGraph Deployment and Debugging</h2>
<p>There are two versions of the mxclient.js file, one for production use and
a second for development/debugging use. <em>javascript/src/js/mxClient.js</em> is
the production version and <em>javascript/debug/js/mxClient.js</em> is for
development. The first version has all linefeeds stripped to ensure the
file is the minimal size possible. This has the side-effect of breaking most
JavaScript debuggers. During development you are advised to use the debug
version, which has the linefeeds in, enabling debugging in the supported
browsers.</p>
<p>Both mxClient.js files are the entire JavaScript source to mxGraph,
with all of the whitespace and comments removed to reduce file size.
Whilst debugging, it is easier to use the individual source files if you
need to debug into the mxGraph library itself. The source code version of
mxGraph contains the full source in the source.zip file in the
<em>javascript/devel</em> directory. Unzipping this into the mxBasePath and removing
the load of the complete mxClient.js file enables easier debugging of mxGraph.
Note that the mxclient.js file in the source zip is a bootstrap file that
loads all the other JavaScript source code.</p>
<p>The download speed of the client source can be further improved
by compressing the code. All modern browsers support receiving and
uncompressing transmissions compressed at the server end and all good
web servers support detection of those browser that do not support it
and send the uncompressed version as a fallback.</p>
<p>For example, on the Apache web server there is a mod_deflate
module, details of its use can be found from a standard search. The
jgraph.com server uses this module and there have been no reports of
issues in any supported browser.</p>
<p>The use of compression reduces the mxClient.js file size down
from about 600KB to around 130KB. The difference is not noticed by the
user on most modern networks, but there might be situations where the
smaller version would be preferable.</p>
<br/>
<h1><a id="model_cells"></a>mxGraph Model and Cells</h1>
<h2><a id="mxgraph_architecture"></a>Core mxGraph architecture</h2>
<h3><a id="mxgraph_model"></a>The mxGraph Model</h3>
<p>The mxGraph model is the core model that describes the structure
of the graph, the class is called mxGraphModel and is found within the
model package. Additions, changes and removals to and from the graph
structure take place through the graph model API. The model also
provides methods to determine the structure of the graph, as well as
offering methods to set visual states such as visibility, grouping and
style.</p>
<p>However, although the transactions to the model are stored on the
model, mxGraph is designed in such a way that the main public API is
through the mxGraph class. The concept of “add this cell to the
graph” is a more natural description of the action than “add
this cell to the model of the graph”. Where it is intuitive,
functions available on the model and cells are duplicated on the graph
and those methods on the graph class are considered the main public API.
Throughout the rest of this manual these key API methods are given a pink background:</p>
<div id="coreapi">
<p>anExampleCoreAPIMethod()</p>
</div>
<p>So, though many of the main API calls are through the mxGraph
class, keep in mind that mxGraphModel is the underlying object that
stores the data structure of your graph.</p>
<p>mxGraph uses a transactional system for making changes to the
model. In the HelloWorld example we saw this code:</p>
<pre>
// Adds cells to the model in a single step
graph.getModel().beginUpdate();
try
{
var v1 = graph.insertVertex(parent, null, 'Hello,', 20, 20, 80, 30);
var v2 = graph.insertVertex(parent, null, 'World!', 200, 150, 80, 30);
var e1 = graph.insertEdge(parent, null, '', v1, v2);
}
finally
{
// Updates the display
graph.getModel().endUpdate();
}
</pre>
<p>to perform the insertion of the 2 vertices and 1 edge. For each
change to the model you make a call to beginUpdate(), make the
appropriate calls to change the model, then call endUpdate() to finalize
the changes and have the change event notifications sent out.</p>
<div id="coreapi">
<p><strong>Key API Methods:</strong></p>
<ul>
<li><strong>mxGraphModel.beginUpdate() </strong>- starts a new
transaction or a sub-transaction.</li>
<li><strong>mxGraphModel.endUpdate()</strong> - completes a
transaction or a sub-transaction.</li>
<li><strong>mxGraph.addVertex()</strong> - Adds a new vertex to
the specified parent cell.</li>
<li><strong>mxGraph.addEdge()</strong> - Adds a new edge to the
specified parent cell.</li>
</ul>
</div>
<p><strong>Note</strong> – Technically you do not have to
surround your changes with the begin and end update calls. Changes made
outside of this update scope take immediate effect and send out the
notifications immediately. In fact, changes within the update scope
enact on the model straight away, the update scope is there to control
the timing and concatenation of event notifications. Unless the update
wrapping causes code aesthetic issues, it is worth using it by habit to
avoid possible problems with event and undo granularity.</p>
<p>Note the way in which the model changes are wrapped in a try
block and the endUpdate() in a finally block. This ensures the update is
completed, even if there is an error in the model changes. You should
use this pattern wherever you perform model changes for ease of
debugging.</p>
<p>Ignore the reference to the parent cell for now, that will be
explained later in this chapter.</p>
<h3><a id="transaction_model"></a>The Transaction Model</h3>
<p>The sub-transaction in the blue block above refers to the fact
that transactions can be nested. That is, there is a counter in the
model that increments for every <em>beginUpdate</em> call and decrements
for every <em>endUpdate</em> call. After increasing to at least 1, when
this count reaches 0 again, the model transaction is considered complete
and the event notifications of the model change are fired.</p>
<p>This means that every sub-contained section of code can (and
should) be surrounded by the begin/end combination. This provide the
ability in mxGraph to create separate transactions that be used as
“library transactions”, the ability to create compound
changes and for one set of events to be fired for all the changes and
only one undo created. Automatic layouting is a good example of where
the functionality is required.</p>
<p>In automatic layouting, the user makes changes to the graph,
usually through the user interface, and the application automatically
positions the result according to some rules. The automatic positioning,
the layouting, is a self-contained algorithm between begin/end update
calls that has no knowledge of the specifics of the change. Because all
changes within the begin/end update are made directly to the graph
model, the layout can act upon the state of the model as the change is
in progress.</p>
<p>It is important to distinguish between functionality that acts on
the graph model as part of a compound change and functionality that
reacts to atomic graph change events. In the first case, such as for
automatic layouting, the functionality takes the model as-is and acts
upon it. This method should only be used for parts of compound model
changes. All other parts of the application should only react to model
change events.</p>
<p>Model change events are fired when the last endUpdate call
reduces the counter back down to 0 and indicate that at least one atomic
graph change has occurred. The change event contains complete
information as to what has altered (see later section on <strong>Events</strong>
for more details).</p>
<h4><a id="model_change_methods"></a>The Model Change Methods</h4>
<p>Below is a list of the methods that alter the graph model and
should be placed, directly or indirectly, with the scope of an update:</p>
<ul>
<li>add(parent, child, index)</li>
<li>remove(cell)</li>
<li>setCollapsed(cell, collapsed)</li>
<li>setGeometry(cell, geometry)</li>
<li>setRoot(root)</li>
<li>setStyle(cell, style)</li>
<li>setTerminal(cell, terminal, isSource)</li>
<li>setTerminals(edge,source,target)</li>
<li>setValue(cell, value)</li>
<li>setVisible(cell, visible)</li>
</ul>
<p>Initially, we will just concern ourselves with the add and
remove, as well as the geometry and style editing methods. Note that
these are not core API methods, as usual these methods are on the
mxGraph class, where appropriate, and they perform the update
encapsulation for you.</p>
<p><em>Design Background</em> - Some people are confused by the
presence of visual information being stored by the model. These
attributes comprise cell positioning, visibility and collapsed state.
The model stores the default state of these attributes, providing a
common place to set them on a per-cell basis, whereas, views can
override the values on a per-view basis. The model is simply the first
common place in the architecture where these attributes can be set on a
global basis. Remember, this is a graph <em>visualization</em> library,
the visualization part is the core functionality.</p>
<h5><a id="inserting_cells"></a>Inserting Cells</h5>
<p>The three graph cells created in the <CODE>HelloWorld</CODE>
application are two vertices and one edge connecting the vertices. If
you are not familiar with basic graph theory and its terminology, please
see the <a href="http://en.wikipedia.org/wiki/Graph_theory">wikipedia
entry</a>.</p>
<p>You can add vertices and edges using the add() method on the
model. However, for the purposes of general usage of this library, learn
that mxGraph.insertVertex() and mxGraph.insertEdge() are the core public
API for adding cells. The function of the model requires that the cell
to be added is already created, whereas the mxGraph.insertVertex()
creates the cell for you.</p>
<div id="coreapi">
<p><strong>Core API functions:</strong></p>
<ul>
<li><strong>mxGraph.insertVertex(</strong><strong>parent,
id, value, x, y, width, height, style</strong><strong>)</strong> – creates