Panel Item Arrays
How does one display a variable number of elements in a node by data binding to a JavaScript Array? The answer is simple: just bind (or set) Panel.itemArray. The Panel will contain as many elements as there are values in the bound Array.
Simple item lists
Here is a very simple example demonstrating the standard way of binding Panel.itemArray to a data property whose value is an Array.
diagram.nodeTemplate =
$(go.Node, "Vertical",
new go.Binding("itemArray", "items"));
diagram.model =
$(go.GraphLinksModel,
{
nodeDataArray: [
{ key: 1, items: [ "Alpha", "Beta", "Gamma", "Delta" ] },
{ key: 2, items: [ "first", "second", "third" ] }
],
linkDataArray: [
{ from: 1, to: 2 }
]
});
diagram.initialContentAlignment = go.Spot.Center;
Note that the Panel.itemArray property is almost always bound to some data property that always has an Array as its value. One does not use a literal or constructed Array as the initial value for the Panel.itemArray property in a template, unless you expect all parts copied from the template will always have exactly the same unchanging list of items.
As with most data bindings, the name of the data property does not really matter. In this example, the property name is "items", but you can use whatever name seems appropriate to your app. You can also have more than one item array in a node or link.
Item templates
You can customize the elements created for each array item by specifying the Panel.itemTemplate. The template must be an instance of Panel. Each item in the bound Array will get a copy of this Panel that is added to the Panel with the Panel.itemArray. The Panel.data will be the item in the Array, so all of the normal data binding functionality is available to customize each item Panel.
This use of templates and data binding is similar to the way Nodes are created automatically in a Diagram based on an Array of node data in the model. The value of Diagram.nodeTemplate must always be a Node or a simple Part; the value of Panel.itemTemplate must always be a Panel and cannot be a Part.
Note that each item in the Panel.itemArray can be any JavaScript value, including strings and numbers. This is different than the values held by the Model.nodeDataArray, which must all be JavaScript Objects. The item Panel.data value may be a string, as it is in this example; the Part.data value will always be an Object.
Here is a simple customization of the Panel.itemTemplate, working with the same model as above. Note that the second argument to the Binding constructor in this case is the empty string, because strings (and numbers) do not have many useful properties.
diagram.nodeTemplate =
$(go.Node, "Auto",
$(go.Shape, "RoundedRectangle",
{ fill: "#3AA7A3" }),
$(go.Panel, "Vertical",
new go.Binding("itemArray", "items"),
{
itemTemplate:
$(go.Panel, "Auto",
{ margin: 2 },
$(go.Shape, "RoundedRectangle",
{ fill: "#91E3E0" }),
$(go.TextBlock, new go.Binding("text", ""),
{ margin: 2 })
) // end of itemTemplate
})
);
diagram.model =
$(go.GraphLinksModel,
{
nodeDataArray: [
{ key: 1, items: [ "Alpha", "Beta", "Gamma", "Delta" ] },
{ key: 2, items: [ "first", "second", "third" ] }
],
linkDataArray: [
{ from: 1, to: 2 }
]
}
);
diagram.initialContentAlignment = go.Spot.Center;
However even when binding to strings or numbers one could make the use of converters to get the desired binding values.
Of course if the array items are Objects, you can refer to their properties just as you can in a Diagram.nodeTemplate. As with node data, you can have as many properties on your item data as your app demands, using whatever property names you prefer. Use data binding to automatically use those property values to customize the appearance and behavior of your item Panels.
diagram.nodeTemplate =
$(go.Node, "Auto",
$(go.Shape, "RoundedRectangle",
{ fill: "#3AA7A3" }),
$(go.Panel, "Vertical",
new go.Binding("itemArray", "items"),
{
itemTemplate:
$(go.Panel, "Auto",
{ margin: 2 },
$(go.Shape, "RoundedRectangle",
{ fill: "#91E3E0" },
new go.Binding("fill", "c")),
$(go.TextBlock, new go.Binding("text", "t"),
{ margin: 2 })
)
})
);
diagram.model =
$(go.GraphLinksModel,
{
nodeDataArray: [
{
key: 1,
items: [
{ t: "Alpha", c: "orange" },
{ t: "Beta" },
{ t: "Gamma", c: "green" },
{ t: "Delta", c: "yellow" }
]
},
{
key: 2,
items: [
{ t: "first", c: "red" },
{ t: "second", c: "cyan" },
{ t: "third" }
]
}
],
linkDataArray: [
{ from: 1, to: 2 }
]
}
);
diagram.initialContentAlignment = go.Spot.Center;
Different Panel types
Although Panels that have an item array are often of type Panel.Vertical, you can use other panel types that support a variable number of elements. The most common types are Panel.Vertical, Panel.Horizontal, Panel.Table, and Panel.Position. It does not make sense to use a Panel.Viewbox panel, because that panel type only supports a single element.
If the panel type is Panel.Spot, Panel.Auto, or Panel.Link, the first child element of the Panel is assumed to be the "main" object and is kept as the first child in addition to all of the nested panels created for the values in the Panel.itemArray.
Here is an example of a horizontal Panel:
diagram.nodeTemplate =
$(go.Node, "Auto",
$(go.Shape, "RoundedRectangle",
{ fill: "gold" }),
$(go.Panel, "Horizontal",
{ margin: 4 },
new go.Binding("itemArray", "a"),
{
itemTemplate:
$(go.Panel, "Auto",
{ margin: 2 },
$(go.Shape, "RoundedRectangle",
{ fill: "white" }),
$(go.TextBlock, new go.Binding("text", ""),
{ margin: 2 })
) // end of itemTemplate
})
);
diagram.model =
$(go.GraphLinksModel,
{
nodeDataArray: [
{ key: "n1", a: [ 23, 17, 45, 21 ] },
{ key: "n2", a: [ 1, 2, 3, 4, 5 ] }
],
linkDataArray: [
{ from: "n1", to: "n2" }
]
}
);
diagram.initialContentAlignment = go.Spot.Center;
When using a Panel of type Panel.Table as the container, it is commonplace to use an item template that is of type Panel.TableRow or Panel.TableColumn. This is the only way to specify the individual column or row indexes for the elements inside the template.
diagram.nodeTemplate =
$(go.Node, "Auto",
$(go.Shape, { fill: "lightgray" }),
$(go.Panel, "Table",
new go.Binding("itemArray", "people"),
{ margin: 4,
defaultAlignment: go.Spot.Left,
itemTemplate:
$(go.Panel, "TableRow",
new go.Binding("background", "back"),
$(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 })
) // end of itemTemplate
})
);
diagram.model =
$(go.GraphLinksModel,
{
nodeDataArray: [
{ key: "group1",
people: [
{ name: "Alice", phone: "2345", loc: "C4-E18" },
{ name: "Bob", phone: "9876", loc: "E1-B34", back: "red" },
{ name: "Carol", phone: "1111", loc: "C4-E23" },
{ name: "Ted", phone: "2222", loc: "C4-E197" }
] },
{ key: "group2",
people: [
{ name: "Robert", phone: "5656", loc: "B1-A27" },
{ name: "Natalie", phone: "5698", loc: "B1-B6" }
] }
],
linkDataArray: [
{ from: "group1", to: "group2" }
]
}
);
diagram.initialContentAlignment = go.Spot.Center;
Arrays in Models
When a data-bound Part is copied, the Part's Part.data, which must be a JavaScript Object, is copied too. The normal copying method, Model.copyNodeData, make a shallow copy of the original data object.
However that is probably not the desired behavior for arrays. When you use item Arrays, you normally do not want to share those Arrays between copies of the Node. If your node data is not copied correctly, unexpected behavior may occur. So when you are using item Arrays and permit users to copy nodes, you will want to implement your own node data copier function and assign it to Model.copyNodeDataFunction.
This is demonstrated by the Dynamic Ports sample, which not only needs to copy the four item Arrays that each node data holds, but also each Object that is in each of those Arrays.
If you need to dynamically modify the value of a property of an item data, call Model.setDataProperty, just as you would for node data or link data.
If you need to add or remove items from an item Array, call the Model.insertArrayItem or Model.removeArrayItem methods.