Interacting with Diagrams

Built-in GoJS Interactivity

GoJS implements a number of common editing operations such as manipulating parts -- moving, adding, copying, cutting, and deleting Nodes and Links. These editing abilities are accessible via mouse or touch and keyboard by default, and can also be invoked programmatically in JavaScript.

The following Diagram defines a node template and has four nodes in its model: 


const myDiagram =
  new go.Diagram("myDiagramDiv", { "undoManager.isEnabled": true });

// define a simple Node template
myDiagram.nodeTemplate =
  new go.Node("Auto")
    .add(
      new go.Shape("Rectangle", { strokeWidth: 0 })
        // zero strokeWidth means don't draw any outline
        // the Shape.fill comes from the Node.data.color property
        .bind("fill", "color"),
      new go.TextBlock({ margin: 6, font: "18px sans-serif" })
        // leave some space around larger-than-normal text
        // the TextBlock.text comes from the Node.data.text property
        .bind("text")
    );

myDiagram.model = new go.GraphLinksModel(
  [ // there will be a Node for each data object in this nodeDataArray
    { key: 1, text: "Alpha", color: "lightblue" },
    { key: 2, text: "Beta", color: "orange" },
    { key: 3, text: "Gamma", color: "lightgreen" },
    { key: 4, text: "Delta", color: "pink" }
  ]);

Out of the box, several interactions are available:

By setting a few properties you can expose more interaction to a user, including manipulating groups: 


const myDiagram =
  new go.Diagram("myDiagramDiv", {
    // allow double-click in background to create a new node
    "clickCreatingTool.archetypeNodeData":
      { text: "Node", color: "lightgray" },

    // allow Ctrl-G to group selected nodes
    "commandHandler.archetypeGroupData":
      { text: "Group", isGroup: true },

    // have mouse wheel events zoom in and out instead of scroll up and down
    "toolManager.mouseWheelBehavior": go.WheelMode.Zoom,

    // enable undo & redo
    "undoManager.isEnabled": true
  });

myDiagram.nodeTemplate =
  new go.Node("Auto")
    .add(
      new go.Shape("Rectangle", { strokeWidth: 0 })
        .bind("fill", "color"),
      new go.TextBlock({
          margin: 6, font: "18px sans-serif", editable: true
        })
        .bindTwoWay("text")
    );

myDiagram.groupTemplate =
  new go.Group("Vertical", {
      // allow Ctrl-Shift-G to ungroup a selected Group.
      ungroupable: true
    })
    .add(
      new go.TextBlock({ font: "bold 12pt sans-serif", editable: true })
        .bindTwoWay("text"),
      new go.Panel("Auto")
        .add(
          new go.Shape({ fill: "transparent" }),
          new go.Placeholder({ padding: 10 })
        )
    );

myDiagram.model = new go.GraphLinksModel(
  [
    { key: 1, text: "Alpha", color: "lightblue" },
    { key: 2, text: "Beta", color: "orange" },
    { key: 3, text: "Gamma", color: "lightgreen", group: 5 },
    { key: 4, text: "Delta", color: "pink", group: 5 },
    { key: 5, text: "Group1", isGroup: true }
  ]);

These interactions (and more!) are all present in the basic.html sample. Be sure to also see the Intro page on GoJS commands.

You can disable portions of Diagram interactivity with several properties, depending on what you want to allow users to do. See the Intro page on GoJS permissions for more explanation.

Focus and Keyboard Control of Tools

You have always been able to manipulate diagrams using the mouse without using the keyboard, especially when making use of the default context menu, which has always been needed on touch devices. As of version 3.1 if you have a keyboard you no longer need to use the mouse to manipulate almost any diagram. This keyboard control mode, when enabled, is available as long as the diagram has keyboard focus. You can always Tab out of the diagram.

Because the GraphObjects within a Diagram are not HTML elements, there is a separate GoJS focus object that is a GraphObject. The arrow keys, Enter, and Escape can change which GraphObject has GoJS focus.

Additionally there is a virtual pointer acting as if it were the mouse, visible when the Shift key is held down. Control the virtual pointer using Shift-arrow keys, Shift Numpad0-9 keys, Shift-Enter, and a few other keys modified by Shift.

Version 3.1 also includes built-in support for screen readers. However, we recommend that you customize the behavior to provide the best possible experience for your users.

Summary of Focus Navigation and the Virtual Pointer

(On a Mac, use the Command modifier insead of the Control modifier.)

See the Intro page on Accessibility for demos and more explanation.

Tool Tips

GoJS provides a mechanism for you to define tooltips for any object or for the Diagram itself. In the example below, two tooltips are defined, one on the Node template and one on the Diagram. 


const myDiagram =
  new go.Diagram("myDiagramDiv", {
    toolTip:  // define a tooltip for the whole Diagram,
              // shown when the mouse hovers over the background
      go.GraphObject.build("ToolTip")
        .add(
          new go.TextBlock("Diagram info")
            .bindObject("text", "",
                ad => `there are ${ad.diagram.nodes.count} nodes`)
        ),
    "undoManager.isEnabled": true
  });

myDiagram.nodeTemplate =
  new go.Node("Auto", {
      toolTip:  // define a tooltip for a Node
        go.GraphObject.build("ToolTip")
          .add(
            new go.TextBlock("Node info")
              .bind("text", "color", c => `This Node is ${c}`)
          )
    })
    .add(
      new go.Shape("Rectangle", { strokeWidth: 0 })
        .bind("fill", "color"),
      new go.TextBlock({ margin: 6, font: "18px sans-serif" })
        .bind("text")
    );

myDiagram.model = new go.GraphLinksModel(
  [ // there will be a Node for each data object in this nodeDataArray
    { key: 1, text: "Alpha", color: "lightblue" },
    { key: 2, text: "Beta", color: "orange" },
    { key: 3, text: "Gamma", color: "lightgreen" },
    { key: 4, text: "Delta", color: "pink" }
  ]);

Hover over a node to show the node's tooltip for five seconds. Hover anywhere in the viewport not over a node to see the tooltip for the diagram.

The basic.html sample contains more complex tooltip examples. See the Intro page on GoJS tooltips for more discussion.

Context Menus

GoJS provides a mechanism for you to define context menus for any object or for the Diagram itself. In the example below, two context menus are defined, one on the Node template (with one button) and one on the Diagram (with two buttons). 


const myDiagram =
  new go.Diagram("myDiagramDiv", { "undoManager.isEnabled": true });

// this function is called when the context menu button is clicked
function nodeClicked(e, obj) {
  alert('node ' + obj.part.data.key + ', "' + obj.part.data.text + '" was clicked');
}

// defines a context menu to be referenced in the node template
const nodeContextMenu =
  go.GraphObject.build("ContextMenu")
    .add(
      go.GraphObject.build("ContextMenuButton", { click: nodeClicked })
        .add(new go.TextBlock("Click me!")),
      // more ContextMenuButtons would go here
    );

myDiagram.nodeTemplate =
  new go.Node("Auto", { contextMenu: nodeContextMenu })
    .add(
      new go.Shape("Rectangle", { strokeWidth: 0 })
        .bind("fill", "color"),
      new go.TextBlock({ margin: 6, font: "18px sans-serif" })
        .bind("text")
    );

// this function alerts the current number of nodes in the Diagram
function countNodes(e, obj) {
  alert('there are ' + e.diagram.nodes.count + ' nodes');
}

// this function creates a new node and inserts it at the last event's point
function addNode(e, obj) {
  const data = { text: "Node", color: "white" };
  // do not need to set "key" property -- addNodeData will assign it automatically
  e.diagram.model.addNodeData(data);
  const node = e.diagram.findPartForData(data);
  node.location = e.diagram.lastInput.documentPoint;
}

myDiagram.contextMenu =
  go.GraphObject.build("ContextMenu")
    .add(
      go.GraphObject.build("ContextMenuButton", { click: countNodes })
        .add(new go.TextBlock("Count Nodes")),
      go.GraphObject.build("ContextMenuButton", { click: addNode })
        .add(new go.TextBlock("Add Node")),
      // more ContextMenuButtons would go here
    );

myDiagram.model = new go.GraphLinksModel(
  [
    { key: 1, text: "Alpha", color: "lightblue" },
    { key: 2, text: "Beta", color: "orange" }
  ]);

If you right-click (or long-tap on a touch device) on a Node or the Diagram, you will see the GoJS context menu appear with the defined options.

The basic.html sample contains more complex context menu examples. See the Intro page on GoJS context menus for more discussion.

Link interactions

GoJS lets users draw new Links by dragging out from a port on a Node to another port on a Node. Users can reconnect existing links by selecting one and dragging one of its handles. To enable these behaviors, some properties need to be set: 


const myDiagram =
  new go.Diagram("myDiagramDiv", { "undoManager.isEnabled": true });

myDiagram.nodeTemplate =
  new go.Node("Auto")
    .add(
      new go.Shape("Rectangle", {
            strokeWidth: 0,
            // declare this Shape to be the port element for the Node
            portId: "",
            cursor: "pointer",
            // set various port-related properties here on this port element
            fromLinkable: true, fromLinkableSelfNode: true, fromLinkableDuplicates: true,
            toLinkable: true, toLinkableSelfNode: true, toLinkableDuplicates: true
          })
        .bind("fill", "color"),
      new go.TextBlock({ margin: 6, font: "18px sans-serif" })
        .bind("text")
    );

myDiagram.linkTemplate =
  new go.Link({
      // allow the user to reconnnect existing links:
      relinkableFrom: true, relinkableTo: true,
      // draw the link path shorter than normal,
      // so that it does not interfere with the appearance of the arrowhead
      toShortLength: 2
    })
    .add(
      new go.Shape({ strokeWidth: 2 }),
      new go.Shape({ toArrow: "Standard", strokeWidth: 0 })
    );

myDiagram.model = new go.GraphLinksModel(
  [
    { key: 1, text: "Alpha", color: "lightblue" },
    { key: 2, text: "Beta", color: "orange" },
    { key: 3, text: "Gamma", color: "lightgreen" },
    { key: 4, text: "Delta", color: "pink" }
  ],
  [
    { from: 1, to: 2 },
    { from: 1, to: 4 }
  ]);

In the above example:

GoJS allows linking and re-linking to abide by custom criteria that controls whether a link connection would be valid. You can read about this in the Intro page on Validation.

GoJS links have many interesting properties that are covered in depth in the Intro page on Links and on the following pages.

You may want to read more tutorials, such as the Learn GoJS tutorial and the GraphObject Manipulation tutorial. You can also watch tutorials on YouTube.

If you are ready for a comprehensive overview of GoJS, have a look at the technical introduction. If you want to explore by example, have a look at the samples to get a feel for what's possible with GoJS.