🎉 JointJS has new documentation! ðŸ¥³

JointJS+ standard

shapes.standard

The Standard shapes plugin provides extra shapes with advanced functionality to extend the JointJS Standard shapes library. The shapes can be used as they are or can serve as an inspiration for creating custom shapes.

source code

shapes.standard.BorderedRecord

An object that displays structured/hierarchical data. Inherits from joint.standard.Record shape and adds a background body rectangle.

Additional attrs properties

Selector Node Description
body SVGRectElement Rectangular body of the shape

To adjust the appearance of a BorderedRecord element, use the Element.attr function:

var borderedRecord = new joint.shapes.standard.BorderedRecord();
borderedRecord.resize(150, 100);
borderedRecord.position(25, 610);
borderedRecord.attr('root/magnet', false);
borderedRecord.attr('body', { fill: 'white', strokeWidth: 2 });
borderedRecord.attr('buttonsGroups/stroke', 'black');
borderedRecord.attr('forksGroups/stroke', 'lightgray');
borderedRecord.attr('itemBodies/stroke', 'black');
borderedRecord.attr('itemBodies_0/fill', '#feb663');
borderedRecord.attr('itemLabels', { fontSize: 12, fontFamily: 'sans-serif' });
borderedRecord.attr('itemLabels_1/magnet', true);
borderedRecord.addTo(graph);

Custom presentation attributes:

All custom presentation attributes are inherited from the joint.standard.Record shape.

var borderedRecord = new joint.shapes.standard.BorderedRecord();
borderedRecord.attr('itemBodies/itemHighlight', { fill: 'lightgray', stroke: 'gray' });
borderedRecord.attr('itemLabels/itemHighlight', { fill: 'orange' });
if (borderedRecord.isItemHighlighted('my_item_id') === false) {
    // `my_item_id` item' background switches to gray and label to orange.
    borderedRecord.toggleItemHighlight('my_item_id');
}
borderedRecord.attr('itemLabels/itemText', { textWrap: true, ellipsis: '*' });

Configuration properties

All configuration properties are inherited from the joint.standard.Record shape. They are set during shape definition with the Cell.define function, or anytime later with the Cell.set function:

borderedRecord.set('itemHeight', 25);
borderedRecord.set('padding', { top: 10, right: 20, bottom: 5, left: 10 });
borderedRecord.set('items', [
    [{ id: 'value1', label: 'Hello' }]
]);
borderedRecord.set('items', [
    [{ id: 'value1', label: 'Hello', items: [
        { id: 'value2', label: 'World!' }]
    }]
]);

Functions

All methods are inherited from the joint.standard.Record shape.

shapes.standard.HeaderedRecord

An object that displays structured/hierarchical data. Inherits from joint.standard.Record shape and adds a background body rectangle, as well as a header rectangle and headerLabel text label.

Additional attrs properties

Selector Node Description
body SVGRectElement Rectangular body of the shape
header SVGRectElement Rectangular header of the shape, positioned above shape's body
headerLabel SVGTextElement Text label inside the header

To adjust the appearance of a HeaderedRecord element, use the Element.attr function:

var headeredRecord = new joint.shapes.standard.HeaderedRecord();
headeredRecord.resize(150, 100);
headeredRecord.position(25, 610);
headeredRecord.attr('root/magnet', false);
headeredRecord.attr('body', { fill: 'white', strokeWidth: 2 });
headeredRecord.attr('header', { fill: 'cornflowerblue', strokeWidth: 2 });
headeredRecord.attr('headerLabel', { fontSize: 24, fontFamily: 'serif' });
headeredRecord.attr('buttonsGroups/stroke', 'black');
headeredRecord.attr('forksGroups/stroke', 'lightgray');
headeredRecord.attr('itemBodies/stroke', 'black');
headeredRecord.attr('itemBodies_0/fill', '#feb663');
headeredRecord.attr('itemLabels', { fontSize: 12, fontFamily: 'sans-serif' });
headeredRecord.attr('itemLabels_1/magnet', true);
headeredRecord.addTo(graph);

Custom presentation attributes:

All custom presentation attributes are inherited from the joint.standard.Record shape.

var headeredRecord = new joint.shapes.standard.HeaderedRecord();
headeredRecord.attr('itemBodies/itemHighlight', { fill: 'lightgray', stroke: 'gray' });
headeredRecord.attr('itemLabels/itemHighlight', { fill: 'orange' });
if (headeredRecord.isItemHighlighted('my_item_id') === false) {
    // `my_item_id` item' background switches to gray and label to orange.
    headeredRecord.toggleItemHighlight('my_item_id');
}
headeredRecord.attr('itemLabels/itemText', { textWrap: true, ellipsis: '*' });

Configuration properties

All configuration properties are inherited from the joint.standard.Record shape. They are set during shape definition with the Cell.define function, or anytime later with the Cell.set function:

headeredRecord.set('itemHeight', 25);
headeredRecord.set('padding', { top: 10, right: 20, bottom: 5, left: 10 });
headeredRecord.set('items', [
    [{ id: 'value1', label: 'Hello' }]
]);
headeredRecord.set('items', [
    [{ id: 'value1', label: 'Hello', items: [
        { id: 'value2', label: 'World!' }]
    }]
]);

Functions

All methods are inherited from the joint.standard.Record shape.

shapes.standard.Record

An object that displays structured/hierarchical data.

If you are extending the behaviour of Record shapes, and creating custom element definitions, it's necessary to use the RecordView.

Supported attrs properties

Selector Node Description
root SVGGElement Container of all nodes
itemBodies group of SVGRectElements All item bodies across all columns.

The node(s) can have a custom attribute itemHighlight.
itemBodies_[group_index]
itemBodies_[group_name]
group of SVGRectElements Item bodies in the given group (column).

For example, item bodies in the first column are accessed as itemBodies_0.
Alternatively, item bodies in a group named headers are accessed as itemBodies_headers.

The node(s) can have a custom attribute itemHighlight.
itemBody_[item_id] SVGRectElement Body of the given item.

For example, item body for an item with id my_item is accessed as itemBody_my_item.

The node can have a custom attribute itemHighlight.
itemLabels group of SVGTextElements All item labels across all columns

The node(s) can have custom attributes itemHighlight and itemText.
itemLabels_[group_index]
itemLabels_[group_name]
group of SVGTextElements Item labels in the given group (column).

For example, item labels in the first column are accessed as itemLabels_0.
Alternatively, item labels in a group named headers are accessed as itemLabels_headers.

The node(s) can have custom attributes itemHighlight and itemText.
itemLabel_[item_id] SVGTextElement Label of the given item.

For example, item label for an item with id my_item is accessed as itemLabel_my_item.

The node can have custom attributes itemHighlight and itemText.
itemIcons group of SVGImageElements All item icons across all columns
itemIcons_[group_index]
itemIcons_[group_name]
group of SVGImageElements Item icons in the given group (column).

For example, item icons in the first column are accessed as itemIcons_0.
Alternatively, item icons in a group named alerts are accessed as itemIcons_alerts.
itemIcon_[item_id] SVGImageElement Icon of the given item.

For example, item icon for an item with id my_item is accessed as itemIcon_my_item.
bodiesGroups group of SVGGElements All groups of item bodies
labelsGroups group of SVGGElements All groups of item labels
forksGroups group of SVGGElements All groups of hierarchy fork lines
buttonsGroups group of SVGGElements All groups of collapse buttons
iconsGroups group of SVGGElements All groups of item icons

To adjust the appearance of a Record element, use the Element.attr function:

var record = new joint.shapes.standard.Record();
record.resize(150, 100);
record.position(25, 610);
record.attr('root/magnet', false);
record.attr('buttonsGroups/stroke', 'black');
record.attr('forksGroups/stroke', 'lightgray');
record.attr('itemBodies/stroke', 'black');
record.attr('itemBodies_0/fill', '#feb663');
record.attr('itemLabels', { fontSize: 12, fontFamily: 'sans-serif' });
record.attr('itemLabels_1/magnet', true);
record.addTo(graph);

Custom presentation attributes:

Attribute Selectors Description
itemHighlight itemBodies
itemBodies_[group_index]
itemBodies_[group_name]
itemBody_[item_id]
itemLabels
itemLabels_[group_index]
itemLabels_[group_name]
itemLabel_[item_id]
Object with SVG attributes. Applied on the selected node(s) when the item is highlighted.
itemText itemLabels
itemLabels_[group_index]
itemLabels_[group_name]
itemLabel_[item_id]
An object with two properties that modify the behavior of the selected SVGTextNode(s):

Property Type Description
textWrap boolean Enable text wrapping of item label (true by default)
ellipsis boolean | string Enable label ellipsis (true by default)
maxLineCount number A number to limit the maximum number of lines.
var record = new joint.shapes.standard.Record();
record.attr('itemBodies/itemHighlight', { fill: 'lightgray', stroke: 'gray' });
record.attr('itemLabels/itemHighlight', { fill: 'orange' });
if (record.isItemHighlighted('my_item_id') === false) {
    // `my_item_id` item' background switches to gray and label to orange.
    record.toggleItemHighlight('my_item_id');
}
record.attr('itemLabels/itemText', { textWrap: true, ellipsis: '*' });

Configuration properties

Property Type Description
items object[][] Items in the Record. Index in outer array specifies the column, index in inner array specifies the order within the column. Each item may have several optional properties:

Property Type Description
id string (Required. Must be unique.)

Item's identifier in the DOM and in JointJS.

Use the cellView.findAttribute('item-id', id) function to find an item by given id.
label string Text content of the item's label
icon string Path to item's icon
collapsed boolean Is the item collapsed?
highlighted boolean Is the item highlighted?
height number Height of the item
span number How many columns does this item span across?
group string | string[] Selector postfix adding the item into a group with the given name. An item may be added to multiple groups by providing multiple group names in a string array.

For example, passing 'headers' as the group name would make the item accessible via the itemBodies_headers and itemLabels_headers selectors.
items object[] Nested items
itemHeight number Height of all items
itemOffset number Offset of nested items from parent item
itemMinLabelWidth number Ensure minimum width of item labels
itemButtonSize number Size of collapse buttons
itemIcon object May specify width, height, and padding of item icons
itemOverflow boolean Should item cells be stretched horizontally when model is widened? i.e. Make items overlap the left and right padding.
itemAboveViewSelector string If an item is not in view (it's scrolled out above the record) into which SVGElement (determined by selector) should the links be visually reconnected.
itemBelowViewSelector string If an item is not in view (it's scrolled out below the record) into which SVGElement (determined by selector) should the links be visually reconnected.
padding object Padding within the Record object
scrollTop number | null The number of pixels that a record's content (without the padding) is scrolled vertically. A record's scrollTop value is a measurement of the distance from the content's top to its topmost visible content.

To enable scrolling set the value to a number. If the value is null (default), the record is automatically resized to the minimal size effectively preventing the need for scrolling.

new Record({ scrollTop: 0 });

Configuration properties are set during shape definition with the Cell.define function, or anytime later with the Cell.set function:

record.set('itemHeight', 25);
record.set('padding', { top: 10, right: 20, bottom: 5, left: 10 });
record.set('items', [
    [{ id: 'value1', label: 'Hello' }]
]);
record.set('items', [
    [{ id: 'value1', label: 'Hello', items: [
        { id: 'value2', label: 'World!' }]
    }]
]);

Functions

The Record shape exposes several functions that enable working with the embedded hierarchical data (items):

shapes.standard.Record.prototype.addItemAtIndex
record.addItemAtIndex(parentId, index, item [, opt])

Insert the provided item into the Record as a child of parentId (string) at given index.

record.addItemAtIndex(groupIndex, index, item [, opt])

Insert the provided item into the group (column) with provided groupIndex (number) at given index.


shapes.standard.Record.prototype.addNextSibling
record.addNextSibling(siblingId, item [, opt])

Insert the provided item into the Record after the item identified by siblingId.


shapes.standard.Record.prototype.addPrevSibling
record.addPrevSibling(siblingId, item [, opt])

Insert the provided item into the Record before the item identified by siblingId.


shapes.standard.Record.prototype.getItemGroupIndex
record.getItemGroupIndex(itemId)

Return the group (column) index of the item with the provided itemId. Return null if the item does not exist.


shapes.standard.Record.prototype.getItemParentId
record.getItemParentId(itemId)

Return the itemId of the parent of the item with the provided itemId. Return null if the item does not exist.


shapes.standard.Record.prototype.getItemPathArray
record.getItemPathArray(itemId)

Return the path to the item with the provided itemId, as an array of strings. Return null if the item does not exist.


shapes.standard.Record.prototype.getItemSide
record.getItemSide(itemId)

Return the side on which lies the item with the provided itemId.

Return 'left' if the item lies within the leftmost column of the Record. Return 'right' if the item lies within the rightmost column of the Record. Return 'middle' if the item does not touch either side of the Record - or if there is only one column. Return null if the item does not exist.


shapes.standard.Record.prototype.getPadding
record.getPadding()

Return the normalized padding in the form of { top: Number, right: Number, bottom: Number, left: Number }.


shapes.standard.Record.prototype.getMinimalSize
record.getMinimalSize()

Return the width and height of the minimal bounding box necessary to encompass all of the shape's content.


shapes.standard.Record.prototype.isItemCollapsed
record.isItemCollapsed(itemId)

Return true if the item is collapsed. Return null if the item does not exist.


shapes.standard.Record.prototype.isItemHighlighted
record.isItemHighlighted(itemId)

Return true if the item is highlighted. Return null if the item does not exist.


shapes.standard.Record.prototype.isItemVisible
record.isItemVisible(itemId)

Return true if the item is visible (i.e. it is not a child of a collapsed item). Return null if the item does not exist.


shapes.standard.Record.prototype.item
record.item(itemId)

Return the item with the provided itemId. Return null if the item does not exist.

record.item(itemId, item [, opt])

Add/merge the provided item properties into the Record for the given itemId.


shapes.standard.Record.prototype.removeItem
record.removeItem(itemId)

Remove the item with the provided itemId and all its children. Return the removed item, or null if the item does not exist.


shapes.standard.Record.prototype.toggleItemCollapse
record.toggleItemCollapse(itemId [, opt])

Collapse/expand the item with the provided itemId.


shapes.standard.Record.prototype.toggleItemHighlight
record.toggleItemHighlight(itemId [, opt])

Highlight/unhighlight the item with the provided itemId.


shapes.standard.Record.prototype.getItemBBox
record.getItemBBox(itemId)

Return the bounding box (g.Rect) of the item in the element's coordinate system. Returns null if no item with such an id exists.


shapes.standard.Record.prototype.getItemViewSign
record.getItemViewSign(itemId)

For the item with the provided itemId, the method is taking the current scrollTop value into account and

  • return 0 if the item is visible in view.
  • return -1 if the item is scrolled out above the view.
  • return 1 if the item is scrolled out below the view.
The method throws an error if the item is hidden within a collapsed ancestor.


shapes.standard.Record.prototype.isItemInView
record.isItemInView(itemId)

Is the item with the provided itemId visible in view and not scrolled out?

The method throws an error if the item is hidden within a collapsed ancestor.


shapes.standard.Record.prototype.isEveryItemInView
record.isEveryItemInView()

Are all the items visible in view?


shapes.standard.Record.prototype.getScrollTop
record.getScrollTop()

Return the normalized value of model's scrollTop property. It is the current number of pixels the record's content is scrolled vertically.


shapes.standard.Record.prototype.setScrollTop
record.setScrollTop(number, [opt])

Normalize and set the scrollTop property of the model.

shapes.standard.RecordView

The view for shapes.standard.Record. It inherits from joint.dia.ElementView. If you are extending the behaviour of Record shapes, and creating custom element definitions, it's necessary to use the RecordView. The RecordView is responsible for interactivity among other things, so it ensures your custom Record behaves as expected.

class CustomRecord extends shapes.standard.HeaderedRecord {
    defaults() {
        return util.defaultsDeep({
            type: 'customNamespace.CustomRecord',
            attrs: {
                // attributes
            }
        }, super.defaults);
    }

    preinitialize() {
        this.markup = util.svg/* xml */ `
            // markup
        `;
    }
}

const CustomRecordView = shapes.standard.RecordView;

Object.assign(shapes, {
    customNamespace: {
        CustomRecord,
        CustomRecordView
    }
});