Port layouts are functions that accept an array of port's `args` and return an array of port positions. Positions are relative to the element model bounding box. For example if we have an element at position `{ x:10, y:20 }` with a relative port position `{ x:1, y:2 }`, the absolute port position will be `{ x:11, y:22 }`. Port layout can be defined only at the `group` level. Optionally you can pass some additional arguments into the layout function via `args`. The `args` is the only way to adjust port layout from the port definition perspective. ```javascript var rect = new joint.shapes.basic.Rect({ // ... ports: { groups: { 'a': { position: { name: 'layoutType', args: {}, } } }, items: [ // initialize 'rect' with port in group 'a' { group: 'a', args: {} // overrides `args` from the group level definition. }, // ... other ports ] } }); // .... // add another port to group 'a'. rect.addPort({ group:'a' }); ``` ### Pre-defined layouts: #### On sides A simple layout suitable for rectangular shapes. It evenly spreads ports along a single side.
name string Can be either `left`, `right`, `top`, `bottom`.
args object
x number Overrides the `x` value calculated by the layout function
y number Overrides the `y` value calculated by the layout function
dx number Added to the `x` value calculated by the layout function
dy number Added to the `y` value calculated by the layout function
angle number The port rotation angle.
```javascript { name: 'left', args: { x: 10, y: 10, angle: 30, dx: 1, dy: 1 } } ``` #### Line A layout which evenly spreads ports along a line defined by a `start` and en `end` point.
name string `line`
args object
start { x:number, y:number } The line starting point
end { x:number, y:number } The line end point
```javascript { name: 'line', args: { start: { x: 10, y: 10 }, end: { x: 20, y: 50 } } } ``` #### Absolute It lay a port out at the given position (defined as a `x`, `y` coordinates or percentage of the element dimensions).
name string `absolute`
args object
x number | string Sets the port's `x` coordinate. Can be defined as a percentage string ('50%') or as a number
y number | string Sets the port's `y` coordinate. Can be defined as a percentage string ('50%') or as a number
angle number The port rotation angle.
```javascript { name: 'absolute', args: { x: '10%', y: 10, angle: 45 } } ``` #### Radial Suitable for circular shapes. The `ellipseSpreads` evenly spreads ports along an ellipse. The `ellipse` spreads ports from the point at `startAngle` leaving gaps between ports equal to `step`.
name string Can be either `ellipse`, `ellipseSpread`.
args object
x number Overrides the `x` value calculated by the layout function
y number Overrides the `y` value calculated by the layout function
dx number Added to the `x` value calculated by the layout function
dy number Added to the `y` value calculated by the layout function
dr number Added to the port delta rotation
startAngle number Default value is `0`.
step number Default `360 / portsCount` for the `ellipseSpread`, `20` for the `ellipse`
compensateRotation boolean set `compensateRotation:true` when you need to have ports in the same angle as an ellipse tangent at the port position.
```javascript { name: 'ellipseSpread', args: { dx: 1, dy: 1, dr: 1, startAngle: 10, step: 10, compensateRotation: false } } ``` ### Custom layout An alternative for built-in layouts is providing a function directly, where the function returns an array of port positions. ```javascript /** * @param {Array} portsArgs * @param {g.Rect} elBBox shape's bounding box * @param {object} opt Group options * @returns {Array} */ function(portsArgs, elBBox, opt) { // ports on sinusoid return _.map(portsArgs, function(portArgs, index) { var step = -Math.PI / 8; var y = Math.sin(index * step) * 50; return g.Point({ x: index * 12, y: y + elBBox.height }); }); } ``` ### Port layouts demo