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.

See samples that make use of item Arrays in the samples index.

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;

Note in this case the item template has a data binding of the TableRow Panel's Panel.background property to the item data's "back" property.

Sometimes one wants to get the row for a particular item, or one wants to have a property value depend on the row index. You can always depend on the value of Panel.itemIndex to get that property. If the item Panel is of type Panel.TableRow, the item Panel's GraphObject.row property will also be set to the zero-based row number, so you can access it in code by finding that Panel. The same is true for GraphObject.column if the itemTemplate is a Panel.TableColumn Panel.

Because that property is set when the item panels are created for Array item data, you can create Bindings where the source is that "row" property: new go.Binding("targetProperty", "row", function(i) { return ...; }).ofObject(). The following example demonstrates binding the Panel.background property to be light green if the row is even. 

  diagram.nodeTemplate =
    $(go.Node, "Auto",
      $(go.Shape, { fill: "white" }),
      $(go.Panel, "Table",
        new go.Binding("itemArray", "people"),
        {
          defaultAlignment: go.Spot.Left,
          itemTemplate:
            $(go.Panel, "TableRow",
              new go.Binding("background", "row",
                             function(i) { return i%2 === 0 ? "lightgreen" : "transparent" })
                  .ofObject(),
              $(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 }),
              $("Button",
                {
                  column: 3,
                  margin: new go.Margin(0, 1, 0, 0),
                  click: function(e, obj) {
                    // OBJ is this Button Panel;
                    // find the TableRow Panel containing it
                    var itempanel = obj.panel;
                    alert("Clicked on row " + itempanel.row + " for " + itempanel.data.name);
                  }
                },
                $(go.Shape, "FivePointedStar",
                  { desiredSize: new go.Size(8, 8) })
              )
            )  // 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" },
              { 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" }
            ] }
        ]
      }
    );

  diagram.initialContentAlignment = go.Spot.Center;

The "Button" Panel in the item template also demonstrates how one can get the particular row index as well as the data to which the item panel is bound.

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. If you want such a behavior, you will want to use multiple templates -- see the example in Template Maps.

If instead you want to have a table header that is "fixed" and not dependent on item Array data, you can have a single "TableRow" (or "TableColumn") Panel in the "Table" Panel that is kept if Panel.isPanelMain is true.

In such cases the constant header element, the literal "TableRow" Panel in the node template, will have a GraphObject.row == 0 and a Panel.itemIndex that is NaN. The "TableRow" Panel corresponding to the first item data, panel.itemArray[0], will have a GraphObject.row == 1, matching its position in the list of Panel.elements. But it will have a Panel.itemIndex == 0, matching its position in the itemArray.

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, makes 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 need to make sure such Arrays and their objects are copied. For the simplest cases, it may be sufficient to set Model.copiesArrays and Model.copiesArrayObjects to true. More generally you may 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. In that sample the Model.copiesArrays and Model.copiesArrayObjects properties are set to true in the JSON-formatted representation of the model that is loaded into the diagram.

For GraphLinksModels, there is also a similar members for link data: the GraphLinksModel.copyLinkData method and GraphLinksModel.copyLinkDataFunction property.

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.