311 lines
16 KiB
HTML
311 lines
16 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<title>GoJS Introduction -- Northwoods Software</title>
|
|
<!-- Copyright 1998-2017 by Northwoods Software Corporation. -->
|
|
<script src="../release/go.js"></script>
|
|
<script src="goIntro.js"></script>
|
|
</head>
|
|
<body onload="goIntro()">
|
|
<div id="container" class="container-fluid">
|
|
<div id="content">
|
|
|
|
<h1>Introduction to GoJS Diagramming Components</h1>
|
|
|
|
<p>
|
|
<b>GoJS</b> is a JavaScript library that lets you easily create interactive diagrams in modern web browsers.
|
|
<b>GoJS</b> supports graphical templates and data-binding of graphical object properties to model data.
|
|
You only need to save and restore the model, consisting of simple JavaScript objects holding
|
|
whatever properties your app needs.
|
|
Many predefined tools and commands implement the standard behaviors that most diagrams need.
|
|
Customization of appearance and behavior is mostly a matter of setting properties.
|
|
</p>
|
|
|
|
<h2 id="SimpleGoJSDiagram">A Simple GoJS Diagram</h2>
|
|
<p>
|
|
The following code defines a node template and model data, which produces a small diagram with a handful of nodes and links.
|
|
</p>
|
|
|
|
<pre data-language="javascript" id="minimal">
|
|
// For conciseness. See the "Building Parts" intro page for more
|
|
var $ = go.GraphObject.make;
|
|
|
|
// the node template describes how each Node should be constructed
|
|
diagram.nodeTemplate =
|
|
$(go.Node, "Auto", // the Shape automatically fits around the TextBlock
|
|
$(go.Shape, "RoundedRectangle", // use this kind of figure for the Shape
|
|
// bind Shape.fill to Node.data.color
|
|
new go.Binding("fill", "color")),
|
|
$(go.TextBlock,
|
|
{ margin: 3 }, // some room around the text
|
|
// bind TextBlock.text to Node.data.key
|
|
new go.Binding("text", "key"))
|
|
);
|
|
|
|
// the Model holds only the essential information describing the diagram
|
|
diagram.model = new go.GraphLinksModel(
|
|
[ // a JavaScript Array of JavaScript objects, one per node;
|
|
// the "color" property is added specifically for this app
|
|
{ key: "Alpha", color: "lightblue" },
|
|
{ key: "Beta", color: "orange" },
|
|
{ key: "Gamma", color: "lightgreen" },
|
|
{ key: "Delta", color: "pink" }
|
|
],
|
|
[ // a JavaScript Array of JavaScript objects, one per link
|
|
{ from: "Alpha", to: "Beta" },
|
|
{ from: "Alpha", to: "Gamma" },
|
|
{ from: "Beta", to: "Beta" },
|
|
{ from: "Gamma", to: "Delta" },
|
|
{ from: "Delta", to: "Alpha" }
|
|
]);
|
|
|
|
diagram.initialContentAlignment = go.Spot.Center;
|
|
// enable Ctrl-Z to undo and Ctrl-Y to redo
|
|
diagram.undoManager.isEnabled = true;
|
|
</pre>
|
|
<p>This creates the following Diagram:</p>
|
|
<script>goCode("minimal", 400, 150)</script>
|
|
<p>
|
|
You can interact with this diagram in many ways:
|
|
</p>
|
|
<ul>
|
|
<li>You can select a part by clicking on it.
|
|
Selected nodes are highlighted with an <a>Adornment</a> that is a blue rectangle surrounding the node.
|
|
Selected links are highlighted with a blue line following the path of the link.</li>
|
|
<li>Multiple parts may be selected at once.
|
|
Hold the Shift key down when clicking to add to the selection.
|
|
Hold the Control key down when clicking to toggle whether that part is selected.</li>
|
|
<li>Another way to multi-select is to mouse-down at a point in the background (not on a part), wait a moment, and then drag a box.
|
|
Parts that are in the box when the mouse-up occurs are selected.
|
|
The Shift and Control modifiers work then as well.</li>
|
|
<li>Ctrl-A selects all parts in the diagram.</li>
|
|
<li>Move one or more nodes by selecting them and dragging.</li>
|
|
<li>Copying selected parts works with either copy/paste (Ctrl-C/Ctrl-V) or with Ctrl-mouse-drag.</li>
|
|
<li>Delete selected parts with the Delete key.</li>
|
|
<li>If scrollbars are visible or if the whole collection of parts is smaller than the viewable area of the diagram (the "viewport"),
|
|
you can pan the diagram with a mouse-down in the background (not on a part) if you drag without waiting.</li>
|
|
<li>Use the mouse wheel to scroll up and down and Shift-mouse-wheel to scroll left and right.
|
|
Ctrl-mouse-wheel zooms in and out.</li>
|
|
</ul>
|
|
<p>
|
|
You can also pan, pinch zoom, select, copy, move, delete, undo, and redo with your fingers on a touch device.
|
|
Most commands that can be invoked from a keyboard can be invoked from the default context menu that you get by pressing your finger and holding it motionless for a moment.
|
|
</p>
|
|
|
|
<p>
|
|
What is unique about all of the examples in the documentation is that they are all "live" -- there are no screenshots!
|
|
They are actual <a>Diagram</a>s implemented by the source code shown.
|
|
You can interact with them -- some even display animation.
|
|
</p>
|
|
|
|
<p>
|
|
If you'd like to see more examples of what <b>GoJS</b> can do, see the <a href="../samples/index.html" target="samples">GoJS Samples directory</a>.
|
|
To make it easier to search the JavaScript code and documentation or to experiment by modifying the samples,
|
|
you can install the <b>GoJS</b> kit in various manners:
|
|
<ul>
|
|
<li>Download a ZIP file from <a href="../doc/download.html">Download</a>.</li>
|
|
<li>Download us from <a href="https://github.com/NorthwoodsSoftware/GoJS">GoJS on GitHub</a>.</li>
|
|
<li>Install GoJS using <code>npm install gojs</code>.</li>
|
|
</ul>
|
|
</p>
|
|
|
|
<h2 id="GoJSConcepts">GoJS Concepts</h2>
|
|
<p>
|
|
<a>Diagram</a>s consist of <a>Part</a>s: <a>Node</a>s that may be connected by <a>Link</a>s and that may be grouped together into <a>Group</a>s.
|
|
All of these parts are gathered together in <a>Layer</a>s and are arranged by <a>Layout</a>s.
|
|
</p>
|
|
|
|
<p>
|
|
Each diagram has a <a>Model</a> that holds and interprets your application data to determine node-to-node link relationships and
|
|
group-member relationships.
|
|
Most parts are data-bound to your application data.
|
|
The diagram automatically creates a <a>Node</a> or a <a>Group</a> for each data item in the model's <a>Model.nodeDataArray</a>
|
|
and a <a>Link</a> for each data item in the model's <a>GraphLinksModel.linkDataArray</a>.
|
|
You can add whatever properties you need to each data object, but there are just a few properties that each kind of model expects.
|
|
</p>
|
|
|
|
<p>
|
|
Each <a>Node</a> or <a>Link</a> is normally defined by a template that declares its appearance and behavior.
|
|
Each template consists of <a>Panel</a>s of <a>GraphObject</a>s such as <a>TextBlock</a>s or <a>Shape</a>s.
|
|
There are default templates for all parts, but almost all applications will specify custom templates
|
|
in order to achieve the desired appearance and behavior.
|
|
Data bindings of <a>GraphObject</a> properties to model data properties make each Node or Link unique for the data.
|
|
</p>
|
|
|
|
<p>
|
|
The nodes may be positioned manually (interactively or programmatically) or may be arranged automatically by the
|
|
<a>Diagram.layout</a> and by each <a>Group.layout</a>.
|
|
Nodes are positioned either by their top-left corner point (<a>GraphObject.position</a>) or by a programmer-defined
|
|
spot in the node (<a>Part.location</a> and <a>Part.locationSpot</a>).
|
|
</p>
|
|
|
|
<p>
|
|
<a>Tool</a>s handle mouse and keyboard events. Each diagram has a number of tools that perform interactive tasks such as
|
|
selecting parts or dragging them or drawing a new link between two nodes. The <a>ToolManager</a> determines
|
|
which tool should be running, depending on the mouse events and current circumstances.
|
|
</p>
|
|
|
|
<p>
|
|
Each diagram also has a <a>CommandHandler</a> that implements various commands, such as Delete or Copy.
|
|
The CommandHandler interprets keyboard events, such as control-Z, when the ToolManager is running.
|
|
</p>
|
|
|
|
<p>
|
|
The diagram provides the ability to scroll the parts of the diagram and to zoom in or out.
|
|
The diagram also contains all of the layers, which in turn contain all of the parts (nodes and links).
|
|
The parts in turn are composed of possibly nested panels of text, shapes, and images.
|
|
This hierarchy of JavaScript objects in memory forms the "visual tree" of everything that may be drawn by the diagram.
|
|
</p>
|
|
|
|
<p>
|
|
The <a>Overview</a> class allows the user to see the whole model and to control what part of it that the diagram displays.
|
|
The <a>Palette</a> class holds parts that the user may drag-and-drop into a diagram.
|
|
</p>
|
|
|
|
<p>
|
|
You can select one or more parts in the diagram. The template implementation may change the appearance
|
|
of the node or link when it is selected. The diagram may also add <a>Adornment</a>s to indicate selection and to
|
|
support tools such as resizing a node or reconnecting a link.
|
|
Adornments are also how tooltips and context menus are implemented.
|
|
</p>
|
|
|
|
<p>
|
|
All programmatic changes to <a>Diagram</a>, <a>GraphObject</a>, <a>Model</a> or model data state should be performed
|
|
within a single transaction per user action, to make sure updating happens correctly and to support undo/redo.
|
|
All of the predefined tools and commands perform transactions, so each user action is automatically undoable
|
|
if the <a>UndoManager</a> is enabled.
|
|
<a>DiagramEvent</a>s on Diagrams, and event handlers on Diagrams and GraphObjects,
|
|
are all documented whether they are raised within a transaction or whether you need to conduct a transaction in order
|
|
to change the model or the diagram.
|
|
</p>
|
|
|
|
|
|
<h2 id="CreatingDiagram">Creating a Diagram</h2>
|
|
<b>GoJS</b> does not depend on any JavaScript library or framework, so you should be able to use it in any environment.
|
|
However it does require that the environment support modern HTML and JavaScript.
|
|
|
|
<h3 id="LoadingGoJS">Loading GoJS</h3>
|
|
<p>
|
|
Before you can execute any JavaScript code to build a Diagram, you will need to load the <b>GoJS</b> library.
|
|
When you include the library, the "<code>go</code>" JavaScript object will hold all of the <b>GoJS</b> types.
|
|
During development we recommend that you load "go-debug.js" instead of "go.js", for additional run-time error checking and debugging ability.
|
|
</p>
|
|
<p>
|
|
We recommend that you declare that your web page supports modern HTML:
|
|
</p>
|
|
<pre>
|
|
<!DOCTYPE html> <!-- Declare standards mode. -->
|
|
<html>
|
|
<head>
|
|
. . .
|
|
<!-- Include the GoJS library. -->
|
|
<script src="go-debug.js"></script>
|
|
</pre>
|
|
<p>
|
|
If you are using <a href="http://requirejs.org" target="_blank">RequireJS</a>, <b>GoJS</b> supports UMD module definitions.
|
|
See the <a href="../samples/require.html" target="samples">Require sample</a> for an example.
|
|
Furthermore modularized versions of the extension classes are now available at <code>../extensionsTS/</code>,
|
|
where the extension classes have been translated into TypeScript and compiled into <code>.js</code> files
|
|
that can be <code>import</code>ed. or <code>require</code>d.
|
|
</p>
|
|
<p>
|
|
In ES6 (ECMAScript 2015) or TypeScript code, just import the "go.js" library:
|
|
<pre>import * as go from "go";</pre>
|
|
or, if depending on your npm environment:
|
|
<pre>import * as go from "gojs";</pre>
|
|
</p>
|
|
|
|
<h3 id="HostingGoJSinaDivElement">Hosting GoJS in a Div Element</h3>
|
|
<p>
|
|
Every <a>Diagram</a> must be hosted by an HTML Div element.
|
|
<b>GoJS</b> will manage the contents of that Div element, but you may position and size and style the Div as you would any HTML element.
|
|
The diagram will add a Canvas element to that Div element that the diagram will draw in -- this is what users actually see.
|
|
The Canvas element is automatically sized to have the same size as the Div element.
|
|
</p>
|
|
|
|
<pre>
|
|
<body>
|
|
. . .
|
|
<!-- The DIV for a Diagram needs an explicit size or else we won't see anything.
|
|
In this case we also add a border to help see the edges. -->
|
|
<div id="myDiagramDiv" style="border: solid 1px blue; width:400px; height:150px"></div>
|
|
</pre>
|
|
|
|
<p>
|
|
Then you can create the <a>Diagram</a> in JavaScript with a reference to that Div element.
|
|
Build the diagram by constructing plain JavaScript objects and adding them to the diagram's model.
|
|
Note that all references in JavaScript code to <b>GoJS</b> types such as <a>Diagram</a> are prefixed with "<code>go.</code>".
|
|
</p>
|
|
|
|
<pre>
|
|
<!-- Create the Diagram in the DIV element using JavaScript. -->
|
|
<!-- The "go" object is the "namespace" that holds all of the GoJS types. -->
|
|
<script>
|
|
var diagram = new go.Diagram("myDiagramDiv");
|
|
diagram.model = new go.GraphLinksModel(
|
|
[{ key: "Hello" }, // two node data, in an Array
|
|
{ key: "World!" }],
|
|
[{ from: "Hello", to: "World!"}] // one link data, in an Array
|
|
);
|
|
</script>
|
|
</pre>
|
|
|
|
<div id="myDiagramDiv" style="border: solid 1px blue; width:400px; height:150px"></div>
|
|
|
|
<!-- Create the Diagram using JavaScript. -->
|
|
<!-- The "go" object is the "namespace" that holds all of the GoJS types. -->
|
|
<script>
|
|
var diagram = new go.Diagram("myDiagramDiv");
|
|
diagram.model = new go.GraphLinksModel(
|
|
[{ key: "Hello" }, // two node data, in an Array
|
|
{ key: "World!" }],
|
|
[{ from: "Hello", to: "World!" }] // one link data, in an Array
|
|
);
|
|
</script>
|
|
|
|
<p>
|
|
This completes the implementation of the "Hello World!" live diagram that you see above.
|
|
</p>
|
|
|
|
<h3 id="DevelopingYourDiagram">Developing your Diagram</h3>
|
|
<p class="box bg-danger">
|
|
<b>GoJS</b> outputs error or warning messages when something goes wrong.
|
|
When developing with <b>GoJS</b>, be sure to check your browser's developer console for information.
|
|
The "go-debug.js" version of the library contains extra type-checking and error-checking code, and should be used during development.
|
|
The "go.js" version has less error checking, but is faster as a result, and should be used in production.
|
|
</p>
|
|
|
|
<p>
|
|
Your JavaScript code should only use properties and methods that are documented in the <a href="../api/index.html" target="api">API</a>.
|
|
The <b>GoJS</b> libraries are "minified", so if you look at an instance of a <b>GoJS</b> class in the debugger,
|
|
you will see many one or two letter property names. All of those are internal names that you should not use.
|
|
At the current time the only one letter property names are "x" and "y" on <a>Point</a>, <a>Rect</a>, <a>Spot</a> and <a>LayoutVertex</a>.
|
|
The only two letter property name is <a>InputEvent.up</a>.
|
|
Otherwise you should not try to use any one or two letter property names on any <b>GoJS</b>-defined objects.
|
|
</p>
|
|
|
|
<p class="box bg-danger">
|
|
Do not modify the prototypes of the <b>GoJS</b> classes.<br />
|
|
Only use the properties and methods documented in the <a href="../api/index.html" target="api">API</a>.
|
|
</p>
|
|
|
|
<p>
|
|
You can also use <a href="https://www.typescriptlang.org/">TypeScript</a> in order to get better "compile-time" type-checking.
|
|
The TypeScript definition file for <b>GoJS</b> is named "go.d.ts" and is located in the same directory as the "go.js" and "go-debug.js" libraries.
|
|
In some editors, access to the definition file also greatly improves documentation feedback while editing TypeScript code.
|
|
The extension classes have also been translated into TypeScript, available at <code>../extensionsTS/</code>.
|
|
</p>
|
|
|
|
<p>
|
|
You can see the variety of kinds of diagrams that you can build at <a href="../samples/index.html" target="samples">GoJS Samples</a>.
|
|
</p>
|
|
<p>
|
|
In the next introduction page we discuss <a href="buildingObjects.html">building <b>GoJS</b> Parts and adding them into Diagrams.</a>
|
|
</p>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|