JointJS+ GridLayout

GridLayout implements automatic layouts for graphs. This is useful in many scenarios, one of them being e.g. automatically positioning elements in Stencil.

Installation

Include the joint.layout.GridLayout.js file into your HTML:

<script src="joint.layout.GridLayout.js"></script>

Usage

GridLayout plugin exposes one function joint.layout.GridLayout.layout(graphOrElements, options). The first parameter graphOrElements is the joint.dia.Graph or an array of joint.dia.Elements we want to layout. The second parameter options is an object that contains various options for configuring the layout.

graph.addCells([
  new joint.shapes.standard.Rectangle({ size: { width: 80, height: 50 }}),
  new joint.shapes.standard.Rectangle({ size: { width: 50, height: 50 }}),
  new joint.shapes.standard.Ellipse({ size: { width: 80, height: 50 }}),
  new joint.shapes.standard.Ellipse({ size: { width: 50, height: 50 }})
]);

// Layout the entire graph
joint.layout.GridLayout.layout(graph, {
  columns: 2,
  columnWidth: 100,
  rowHeight: 70
});

// Layout the ellipses with minimal resulting `y` coordinate equals 100.
var ellipses = graph.getElements().filter(function(el) {
    return el instanceof joint.shapes.standard.Ellipse;
});
joint.layout.GridLayout.layout(ellipses, {
    columns: 2,
    marginY: 100
});

Here are the options for configuring the GridLayout:

• columns - Number of columns. It defaults to 1.
• columnWidth
  • 'auto' - width of a column is equal to the widest element amongst all elements
  • 'compact' - width of a column is equal to the widest element in the column
  • number - value of a column width (e.g. 200)
  It defaults to 'auto'.
• rowHeight
  • 'auto' - height of a row is equal to the highest element amongst all elements
  • 'compact' - height of a row is equal to the highest element in the row
  • number - value of a row height (e.g. 100)
  It defaults to 'auto'.
• verticalAlign
  • 'top' - the elements in the grid are aligned to the top of a grid cell
  • 'middle' - the elements in the grid are aligned to the center of a grid cell
  • 'bottom' - the elements in the grid are aligned to the bottom of a grid cell
  It defaults to 'top' (if centre) is disabled).
• horizontalAlign
  • 'left' - the elements in the grid are aligned to the left side of a grid cell
  • 'middle' - the elements in the grid are aligned to the center of a grid cell
  • 'right' - the elements in the grid are aligned to the right side of a grid cell
  It defaults to 'left' (if centre) is disabled).
• columnGap - the horizontal gap between columns. It defaults to 0.
• rowGap - the vertical gap between rows. It defaults to 0.
• resizeToFit - Resizes the elements to fit a grid cell, preserving the aspect ratio (default: false)
• marginX - Sets the origin (x coordinate) of the most top-left element. It defaults to 0.
• marginY - Sets the origin (y coordinate) of the most top-left element. It defaults to 0.
• deep - Uses deep positioning for elements when set to true. i.e. moves not only the elements but also their descendants. It defaults to false.
• parentRelative - Position the elements relatively to their parents.

  var padding = 20;
  // layout the children of the element `el`
  joint.layout.GridLayout.layout(el.getEmbeddedCells(), {
    parentRelative: true,
    marginX: padding,
    marginY: padding
  });
  // resize the element `el` to fit all children
  el.fitEmbeds({ padding: padding });
  

• setAttributes(element, { position, size }, opt) - a callback function to customize how the positions (and sizes when resizeToFit enabled) are set to the elements.
• dx deprecated - Shifts the elements horizontally by a given amount. It defaults to 0.
• dy deprecated - Shifts the elements vertically by a given amount. It defaults to 0.
• centre deprecated - Positions the elements in the centre of a grid cell. It defaults to true.

The function returns an object with various geometry information.

• bbox - a tight bounding box around the elements
• gridX - an array of x-coordinates of vertical separators between columns.
• gridY - an array of y-coordinates of horizontal separators between rows.
• rowHeights - an array of row heights
• columnWidths - an array of column widths