Legends and Titles

Sometimes in addition to the nodes and links that are the subject of a diagram, one also wants to display a "legend" or "key" describing the different kinds of nodes or links. Perhaps one also wants there to be "title" for the diagram in large letters.

Outside of Diagram

First, you must consider whether titles or legends should be part of the diagram or not. You can create whatever you want in HTML outside of the diagram.

  setupForLegend(diagram);

Note that anything in HTML will not automatically scroll and zoom along with the diagram's contents shown in the viewport. But HTML elements could be positioned in front of or behind the diagram's DIV element.

Unmodeled Parts

Second, you should consider whether the title or legend should be held in your data model. Do you need to save and load that data in your database?

If you do not want to these objects to be included in your application's data model, you can just create them as simple Parts and Diagram.add them to your diagram at explicitly defined Part.locations.

  setupForLegend(diagram);  // this creates a diagram just like the first example

  diagram.add(
    $(go.Part, { location: new go.Point(0, -40) },
      $(go.TextBlock, "A Title", { font: "bold 24pt sans-serif", stroke: "green" })));

If you do not assign a location or position for your Parts, and if your Diagram.layout (if any) does not assign any Part.location, then there might not be a real location for those parts and they might not appear anywhere in the diagram.

All of the predefined Layouts that make use of LayoutNetworks, including TreeLayout, do not operate on simple Parts but only on Nodes and Links. If you had added a Node to the diagram it would have been positioned as part of this diagram's normal tree layout, even though you explicitly set its location. Alternatively it could still be a Node if you set its Part.isLayoutPositioned property to false.

You will notice that the title is selectable and movable and copyable and deletable in the diagram above. You may want to set properties such as Part.selectable to false.

For an example showing a legend, see the Family Tree sample.

Modeled Parts

If on the other hand you do want to store your titles or legends in your model, you can do so using the normal mechanisms. Typically you will use node categories and template maps.

Static Parts

Third, consider whether you want the title or legend to move or scale as the user scrolls or zooms the diagram. If you want to keep such a decoration at the same position in the viewport, you can place it in a Layer that has Layer.isViewportAligned set to true. There are two such layers that are predefined for you: "ViewportBackground" and "ViewportForeground". Parts added to these layers will position and scale themselves according to their alignment spots, GraphObject.alignment and GraphObject.alignmentFocus, relative to the viewport, and their drawn scale will not change with the Diagram scale. Thus they will not move as the user scrolls or zooms.

If you set or bind the GraphObject.position or Part.location properties of Parts in such Layers, those new values will be ignored because the alignment properties take precedence. However those properties still have valid values, with Points that are in document coordinates.

  setupForLegend(diagram);  // this creates a diagram just like the first example

  // this Layer is behind everything and is not interactive
  const myTitle =
    $(go.Part,
      {
        layerName: "ViewportBackground",
        alignment: new go.Spot(0, 0, 10, 10)
      },
      $(go.TextBlock, "A Title", { font: "bold 24pt sans-serif", stroke: "green" }));
  diagram.add(myTitle);

Note that as the user pans or scrolls or zooms the diagram, the title remains at the same top-left corner at apparently the same effective size. This example makes use of the "ViewportBackground" Layer (see Intro to Layers), which is convenient for making sure the title (or legend) stays in the background and does not participate in selection or mouse events or the UndoManager.