Template Maps
Many of the previous examples have provided custom templates for nodes, groups, or links. Those examples have shown how to make simple adaptations of the templates for particular data instances via data binding. But what if you want to have nodes with drastically different appearances or behaviors in a single diagram at the same time?
It is possible to define a node template that includes all possible configurations for all of the kinds of nodes that you want to display. There would need to be a lot of data binding and/or code to make the needed changes. Often you will want to make not-GraphObject.visible large parts of the template in order to make visible the one panel that you want to show. But this technique is difficult to use -- templates get way too complicated too quickly.
Instead GoJS supports as many templates as you want -- you choose dynamically which one you want to use to represent a particular node data. This does mean potentially a lot of templates, but each one will be much simpler, easier to write, and easier to maintain.
Each Diagram actually holds a Map of templates for each type of Part: Node, Group, and Link. Each Map associates a "category" name with a template. For example, when the diagram wants to create a Node for a particular node data object, the diagram uses that node data's category to look up the node template in the Diagram.nodeTemplateMap. Similar lookups are done using the Diagram.groupTemplateMap and the Diagram.linkTemplateMap.
Each Diagram initially has its own template maps stocked with predefined categories. The default category for any data object is the empty string, "". Thus the Diagram.nodeTemplateMap initially contains a very simple Node template holding a TextBlock whose TextBlock.text property is data bound to the data converted to a string. You can see the default templates for nodes, groups, and links in a number of the previous examples, such as the Groups and Links example.
The value of Diagram.nodeTemplate is just the value of Diagram.nodeTemplateMap.getValue("") Setting Diagram.nodeTemplate just replaces the template in Diagram.nodeTemplateMap named with the empty string.
The implementations of all predefined templates are provided in Templates.js in the Extensions directory. You may wish to copy and adapt these definitions when creating your own templates.
Example of Node templates
// the "simple" template just shows the key string and the color in the background,
// but it also includes a tooltip that shows the description
var simpletemplate =
$(go.Node, "Auto",
$(go.Shape, "Ellipse",
new go.Binding("fill", "color")),
$(go.TextBlock,
new go.Binding("text", "key")),
{
toolTip:
$(go.Adornment, "Auto",
$(go.Shape, { fill: "#FFFFCC" }),
$(go.TextBlock, { margin: 4 },
new go.Binding("text", "desc"))
)
}
);
// the "detailed" template shows all of the information in a Table Panel
var detailtemplate =
$(go.Node, "Auto",
$(go.Shape, "RoundedRectangle",
new go.Binding("fill", "color")),
$(go.Panel, "Table",
{ defaultAlignment: go.Spot.Left },
$(go.TextBlock, { row: 0, column: 0, columnSpan: 2, font: "bold 12pt sans-serif" },
new go.Binding("text", "key")),
$(go.TextBlock, { row: 1, column: 0 }, "Description:"),
$(go.TextBlock, { row: 1, column: 1 }, new go.Binding("text", "desc")),
$(go.TextBlock, { row: 2, column: 0 }, "Color:"),
$(go.TextBlock, { row: 2, column: 1 }, new go.Binding("text", "color"))
)
);
// create the nodeTemplateMap, holding three node templates:
var templmap = new go.Map("string", go.Node);
// for each of the node categories, specify which template to use
templmap.add("simple", simpletemplate);
templmap.add("detailed", detailtemplate);
// for the default category, "", use the same template that Diagrams use by default;
// this just shows the key value as a simple TextBlock
templmap.add("", diagram.nodeTemplate);
diagram.nodeTemplateMap = templmap;
diagram.model.nodeDataArray = [
{ key: "Alpha", desc: "first letter", color: "green" }, // uses default category: ""
{ key: "Beta", desc: "second letter", color: "lightblue", category: "simple" },
{ key: "Gamma", desc: "third letter", color: "pink", category: "detailed" },
{ key: "Delta", desc: "fourth letter", color: "cyan", category: "detailed" }
];
If you hover the mouse over the "Beta" node, you will see the tooltip showing the description string. The detailed template does not bother using tooltips to show extra information because everything is already shown.
By default the way that the model and diagram know about the category of a node data or a link data is by looking at its category property. If you want to use a different property on the data, for example because you want to use the category property to mean something different, set Model.nodeCategoryProperty to be the name of the property that results in the actual category string value. Or set Model.nodeCategoryProperty to be the empty string to cause all nodes to use the default node template.
Example of Item Templates
For Panels with a value for Panel.itemArray, there is also the Panel.itemTemplateMap. As with Nodes and Groups and Links, the Panel.itemTemplate is just a reference to the template named with the empty string in the Panel.itemTemplateMap. Similarly, the Panel.itemCategoryProperty names the property on the item data that identifies the template to use from the itemTemplateMap.
// create a template map for items
var itemtemplates = new go.Map("string", go.Panel);
// the template when type == "text"
itemtemplates.add("text",
$(go.Panel,
$(go.TextBlock,
new go.Binding("text"))
));
// the template when type == "button"
itemtemplates.add("button",
$("Button",
$(go.TextBlock,
new go.Binding("text")),
// convert a function name into a function value,
// because functions cannot be represented in JSON format
new go.Binding("click", "handler",
function(name) {
if (name === "alert") return raiseAlert; // defined below
return null;
})
));
diagram.nodeTemplate =
$(go.Node, "Vertical",
$(go.TextBlock,
new go.Binding("text", "key")),
$(go.Panel, "Auto",
$(go.Shape, { fill: "white" }),
$(go.Panel, "Vertical",
{
margin: 3,
defaultAlignment: go.Spot.Left,
itemCategoryProperty: "type", // this property controls the template used
itemTemplateMap: itemtemplates // map was defined above
},
new go.Binding("itemArray", "info"))
)
);
function raiseAlert(e, obj) { // here OBJ will be the item Panel
var node = obj.part;
alert(node.data.key + ": " + obj.data.text);
}
// The model data includes item arrays in the node data.
diagram.model = new go.GraphLinksModel( [
{ key: "Alpha",
info: [
{ type: "text", text: "some text" },
{ type: "button", text: "Click me!", handler: "alert"}
]
},
{ key: "Beta",
info: [
{ type: "text", text: "first line" },
{ type: "button", text: "First Button", handler: "alert"},
{ type: "text", text: "second line" },
{ type: "button", text: "Second Button", handler: "alert" }
]
}
],[
{ from: "Alpha", to: "Beta" }
]);
diagram.initialContentAlignment = go.Spot.Center;
Example of Table Header Showing Item Data
The natural way to have a distinct header for a Table Panel is to have the first row (i.e. the first item) hold the data for the header, but have it be styled differently. In this example we define a "Header" item template in the Panel.itemTemplateMap.
var itemTemplateMap = new go.Map();
itemTemplateMap.add("",
$(go.Panel, "TableRow",
$(go.TextBlock, new go.Binding("text", "name"),
{ column: 0, margin: 2, font: "bold 10pt sans-serif" }),
$(go.TextBlock, new go.Binding("text", "phone"),
{ column: 1, margin: 2 }),
$(go.TextBlock, new go.Binding("text", "loc"),
{ column: 2, margin: 2 })
));
itemTemplateMap.add("Header",
$(go.Panel, "TableRow",
$(go.TextBlock, new go.Binding("text", "name"),
{ column: 0, margin: 2, font: "bold 10pt sans-serif" }),
$(go.TextBlock, new go.Binding("text", "phone"),
{ column: 1, margin: 2, font: "bold 10pt sans-serif" }),
$(go.TextBlock, new go.Binding("text", "loc"),
{ column: 2, margin: 2, font: "bold 10pt sans-serif" })
));
diagram.nodeTemplate =
$(go.Node, "Auto",
$(go.Shape, { fill: "white" }),
$(go.Panel, "Table",
new go.Binding("itemArray", "people"),
{
defaultAlignment: go.Spot.Left,
defaultColumnSeparatorStroke: "black",
itemTemplateMap: itemTemplateMap
},
$(go.RowColumnDefinition,
{ row: 0, background: "lightgray" }),
$(go.RowColumnDefinition,
{ row: 1, separatorStroke: "black" })
)
);
diagram.model =
$(go.GraphLinksModel,
{
nodeDataArray: [
{ key: "group1",
people: [
{ name: "Person", phone: "Phone", loc: "Location", category: "Header" },
{ name: "Alice", phone: "2345", loc: "C4-E18" },
{ name: "Bob", phone: "9876", loc: "E1-B34" },
{ name: "Carol", phone: "1111", loc: "C4-E23" },
{ name: "Ted", phone: "2222", loc: "C4-E197" },
{ name: "Robert", phone: "5656", loc: "B1-A27" },
{ name: "Natalie", phone: "5698", loc: "B1-B6" }
] }
],
linkDataArray: [
]
}
);
diagram.initialContentAlignment = go.Spot.Center;
If you do not want to have the header data in the itemArray, and you want to define the header in the node template rather than as an item template, see the example in Item Arrays.
Changing category of a Part
To change the representation of a data object, call Model.setCategoryForNodeData or GraphLinksModel.setCategoryForLinkData. (If you set the Part.category of a data bound Part, it will call the Model method for you.) This causes the diagram to discard any existing Part for the data and re-create it using the new template that is associated with the new category value.
// this function changes the category of the node data to cause the Node to be replaced
function changeCategory(e, obj) {
var node = obj.part;
if (node) {
var diagram = node.diagram;
diagram.startTransaction("changeCategory");
var cat = diagram.model.getCategoryForNodeData(node.data);
if (cat === "simple")
cat = "detailed";
else
cat = "simple";
diagram.model.setCategoryForNodeData(node.data, cat);
diagram.commitTransaction("changeCategory");
}
}
// The "simple" template just shows the key string and the color in the background.
// There is a Button to invoke the changeCategory function.
var simpletemplate =
$(go.Node, "Spot",
$(go.Panel, "Auto",
$(go.Shape, "Ellipse",
new go.Binding("fill", "color")),
$(go.TextBlock,
new go.Binding("text", "key"))
),
$("Button",
{ alignment: go.Spot.TopRight },
$(go.Shape, "AsteriskLine", { width: 8, height: 8 }),
{ click: changeCategory })
);
// The "detailed" template shows all of the information in a Table Panel.
// There is a Button to invoke the changeCategory function.
var detailtemplate =
$(go.Node, "Spot",
$(go.Panel, "Auto",
$(go.Shape, "RoundedRectangle",
new go.Binding("fill", "color")),
$(go.Panel, "Table",
{ defaultAlignment: go.Spot.Left },
$(go.TextBlock, { row: 0, column: 0, columnSpan: 2, font: "bold 12pt sans-serif" },
new go.Binding("text", "key")),
$(go.TextBlock, { row: 1, column: 0 }, "Description:"),
$(go.TextBlock, { row: 1, column: 1 }, new go.Binding("text", "desc")),
$(go.TextBlock, { row: 2, column: 0 }, "Color:"),
$(go.TextBlock, { row: 2, column: 1 }, new go.Binding("text", "color"))
)
),
$("Button",
{ alignment: go.Spot.TopRight },
$(go.Shape, "AsteriskLine", { width: 8, height: 8 }),
{ click: changeCategory })
);
var templmap = new go.Map("string", go.Node);
templmap.add("simple", simpletemplate);
templmap.add("detailed", detailtemplate);
diagram.nodeTemplateMap = templmap;
diagram.layout = $(go.TreeLayout);
diagram.model.nodeDataArray = [
{ key: "Beta", desc: "second letter", color: "lightblue", category: "simple" },
{ key: "Gamma", desc: "third letter", color: "pink", category: "detailed" },
{ key: "Delta", desc: "fourth letter", color: "cyan", category: "detailed" }
];
diagram.model.linkDataArray = [
{ from: "Beta", to: "Gamma" },
{ from: "Gamma", to: "Delta" }
];
Click on the "asterisk" button on any node to toggle dynamically between the "simple" and the "detailed" category for each node.
Changing template maps
You can also replace one or all of the diagram's template maps (e.g. Diagram.nodeTemplateMap) in order to discard and re-create all of the nodes in the diagram. If you are only using the default template for nodes, you would only need to replace the Diagram.nodeTemplate.
One common circumstance for doing this is as the Diagram.scale changes. When the user zooms out far enough, there is no point in having too much detail about each of the nodes.
If you zoom out in this example, the DiagramEvent listener will detect when the Diagram.scale becomes small enough to use the simpler template for all of the nodes. Zoom in again and suddenly it uses the more detailed template.
// The "simple" template just shows the key string and the color in the background.
var simpletemplate =
$(go.Node, "Spot",
$(go.Panel, "Auto",
$(go.Shape, "Ellipse",
new go.Binding("fill", "color")),
$(go.TextBlock,
new go.Binding("text", "key"))
)
);
// The "detailed" template shows all of the information in a Table Panel.
var detailtemplate =
$(go.Node, "Spot",
$(go.Panel, "Auto",
$(go.Shape, "RoundedRectangle",
new go.Binding("fill", "color")),
$(go.Panel, "Table",
{ defaultAlignment: go.Spot.Left },
$(go.TextBlock, { row: 0, column: 0, columnSpan: 2, font: "bold 12pt sans-serif" },
new go.Binding("text", "key")),
$(go.TextBlock, { row: 1, column: 0 }, "Description:"),
$(go.TextBlock, { row: 1, column: 1 }, new go.Binding("text", "desc")),
$(go.TextBlock, { row: 2, column: 0 }, "Color:"),
$(go.TextBlock, { row: 2, column: 1 }, new go.Binding("text", "color"))
)
)
);
diagram.layout = $(go.TreeLayout);
diagram.model.nodeDataArray = [
{ key: "Beta", desc: "second letter", color: "lightblue" },
{ key: "Gamma", desc: "third letter", color: "pink" },
{ key: "Delta", desc: "fourth letter", color: "cyan" }
];
diagram.model.linkDataArray = [
{ from: "Beta", to: "Gamma" },
{ from: "Gamma", to: "Delta" }
];
// initially use the detailed templates
diagram.nodeTemplate = detailtemplate;
diagram.addDiagramListener("ViewportBoundsChanged",
function (e) {
if (diagram.scale < 0.9) {
diagram.nodeTemplate = simpletemplate;
} else {
diagram.nodeTemplate = detailtemplate;
}
});
myDiagram = diagram; // make accessible to the HTML buttons
Caution: if you modify a template Map, there is no notification that the map has changed. You will need to call Diagram.rebuildParts explicitly. If you are replacing the Diagram.nodeTemplate or the Diagram.nodeTemplateMap or the corresponding properties for Groups or Links, the Diagram property setters will automatically call Diagram.rebuildParts.
When one or more templates are replaced in a diagram, layouts are automatically performed again.