jointjs/docs/src/joint/api/highlighters/intro.html

JavaScript diagramming library

<p>Highlighters can be used to provide visual emphasis to an element; during user interactions for example.</p>

<p>Highlighters inherit from <a href="#dia.HighlighterView">dia.HighlighterView</a>.</p>

<iframe src="about:blank" data-src="demo/highlighters/mask.html" style="height: 426px; width: 423px;"></iframe>

<p>In the above demo, we listen to the paper for the <code>element:pointerclick</code> event and highlight the entire element we clicked on.</p>

<pre><code>paper.on('element:pointerclick', (elementView) => {
    joint.highlighters.mask.add(elementView, { selector: 'root' }, 'my-element-highlight', {
        deep: true,
        attrs: {
            'stroke': '#FF4365',
            'stroke-width': 3
        }
    });
});</code></pre>

<p>We also listen to the paper for the <code>element:magnet:pointerclick</code> event and highlight the port we clicked on.</p>

<pre><code>paper.on('element:magnet:pointerclick', (elementView, magnet, evt) => {
    // Prevent highlighting the body of the element
    evt.stopPropagation();
    // Find the port ID of the selected magnet
    const port = cellView.findAttribute('port', magnet);
    joint.highlighters.mask.add(elementView, { port }, 'my-port-highlight', {
        attrs: {
            'stroke': '#FF4365',
            'stroke-width': 3
        }
    });
});</code></pre>

<p>Then we listen for the <code>link:pointerclick</code> event and highlight the line node of the link we clicked on.</p>

<pre><code>paper.on('link:pointerclick', (linkView) => {
    joint.highlighters.mask.add(linkView, { selector: 'line' }, 'my-link-highlight', {
        // Draw the highlighter under the LinkView
        layer: 'back',
        attrs: {
            'stroke': '#FF4365',
            'stroke-width': 3,
            'stroke-linecap': 'square'
        }
    });
});</code></pre>

<p>Next we set up a listener for a custom event <code>link:label:pointerdown</code> and highlight the label we clicked on.</p>

<div class="docs-important-note">
    A custom paper event can be defined with <a href="#dia.attributes.event">event attribute</a>.
</div>

<pre><code>paper.on('link:label:pointerdown', (linkView, evt) => {
    // Prevent highlighting the line of the link
    evt.stopPropagation();
    // Find the index of the selected label
    const label = cellView.findAttribute('label-idx', evt.target);
    joint.highlighters.mask.add(linkView, { label }, 'my-label-highlight', {
        // Decrease the gap between the label and highlighter
        padding: 1,
        attrs: {
            'stroke': '#FF4365',
            'stroke-width': 3
        }
    });
});</code></pre>

<p>Generally, it's possible to highlight a cell (Element or Link) or a part of the cell calling the <code>add()</code> method of a highlighter.</p>
<pre><code>// Add Mask Highlighter with ID `my-mask-highlighter` to the CellView.
// Note: `root` is a shortcut for `{ selector: 'root' }`
joint.highlighters.mask.add(cellView, 'root', 'my-mask-highlighter', {
    deep: true
});

// Add class name `my-highlight` to the CellView's body node.
joint.highlighters.addClass.add(cellView, 'body', 'my-class-highlighter', {
    className: 'my-highlight'
});

// Add Stroke Highlighter to a specific port node (using default options).
joint.highlighters.stroke.add(cellView, { port: 'port-id-1', selector: 'portBody' }, 'my-port-highlighter');</code></pre>

<p>To unhighlight a cell, call the <code>remove()</code> method.</p>
<pre><code>// Remove all highlighters from the CellView
joint.dia.HighlighterView.remove(cellView);

// Remove the highlighter with ID `my-highlighter` from the CellView
joint.dia.HighlighterView.remove(cellView, 'my-highlighter');

// Remove all Mask highlighters from the cellView
joint.highlighters.mask.remove(cellView);

// Remove Stroke Highlighter with ID `my-highlighter` from the cellView.
joint.highlighters.stroke.remove(cellView, 'my-highlighter');

// If you have a reference to a highlighter, calling its prototype `remove()` method is also valid.
const highlighter = joint.dia.HighlighterView.get(cellView, 'my-highlighter');
highlighter.remove();
</code></pre>

<p>To see if a cell has a highlighter, call the <code>get()</code> method.</p>
<pre><code>// Get all the highlighters (an array) from the CellView
joint.dia.HighlighterView.get(cellView);

// Get the highlighter with ID `my-highlighter` from the CellView
joint.dia.HighlighterView.get(cellView, 'my-highlighter');

// Get all Mask highlighters from the cellView
joint.highlighters.mask.get(cellView);

// Get Stroke Highlighter with ID `my-highlighter` from the cellView.
// If there is no such highlighter (ID or Type does not match, `null` is returned).
joint.highlighters.stroke.get(cellView, 'my-highlighter');</code></pre>




<div class="docs-important-note">
    When adding a highlighter, prefer using a node selector over a reference to an actual node.
    <pre><code>// Prefer this:
joint.highlighters.mask.add(elementView, { port: 'port1' }, 'port-highlight');
// Over this:
joint.highlighters.mask.add(elementView, elementView.findPortNode('port1'), 'port-highlight');</code></pre>
    <ul>
        <li>Using the node selector supports asynchronous rendering. No need to wait for an element to be rendered, when adding the highlighter.</li>
        <li>Using the node reference highlights the specific node only. If the view is redrawn, the node could have been replaced with another node which wouldn't be highlighted.</li>
    </ul>
</div>

<p>If a node (determined by the node selector) stops to exist (e.g. a port is removed) the <code>cell:highlight:invalid</code> event is triggered on the paper.</p>

<pre><code>// If we don't want the highlighter wait for the port to reappear, we can remove it when the event occurs.
paper.on('cell:highlight:invalid', (cellView, id) => {
    joint.dia.HighlighterView.remove(cellView, id);
})</code></pre>