jointjs
Version:
JavaScript diagramming library
299 lines (235 loc) • 13.6 kB
HTML
<html>
<head>
<link rel="canonical" href="http://www.jointjs.com/" />
<meta name="description" content="Create interactive diagrams in JavaScript easily. JointJS plugins for ERD, Org chart, FSA, UML, PN, DEVS, LDM diagrams are ready to use." />
<meta name="keywords" content="JointJS, JavaScript, diagrams, diagramming library, UML, charts" />
<link href="http://fonts.googleapis.com/css?family=Source+Sans+Pro:400,700" rel="stylesheet" type="text/css" />
<link href="https://fonts.googleapis.com/css?family=Open+Sans" rel="stylesheet">
<link rel="stylesheet" href="css/tutorial.css" />
<link rel="stylesheet" href="../node_modules/prismjs/themes/prism.css">
<!-- Dependencies: -->
<script src="../node_modules/jquery/dist/jquery.js"></script>
<script src="../node_modules/lodash/lodash.js"></script>
<script src="../node_modules/backbone/backbone.js"></script>
<link rel="stylesheet" type="text/css" href="../build/joint.min.css" />
<script type="text/javascript" src="../build/joint.min.js"></script>
<title>JointJS - JavaScript diagramming library - Getting started.</title>
</head>
<body class="language-javascript tutorial-page">
<script>
SVGElement.prototype.getTransformToElement = SVGElement.prototype.getTransformToElement || function(toElement) {
return toElement.getScreenCTM().inverse().multiply(this.getScreenCTM());
};
</script>
<div class="tutorial">
<h2>Element Tools</h2>
<p>This is the seventh article of the intermediate section of the JointJS tutorial.
<a href="link-labels.html">Go back to link labels.</a>
Alternatively, you can <a href="intermediate.html">return to index</a> of all articles.</p>
<p>JointJS allows creating fully customizable <a href="/docs/jointjs#elementTools" target="_blank">user
interaction tools for your elements</a>.
These tools show up on user interaction (e.g. mouseover) with an element view and allow the user to
interact with the underlying <a href="elements.html">element model</a>.
For example:</p>
<div class="paper" id="paper-element-tools-example"></div>
<p>JointJS source code: <a href="js/element-tools-example.js" target="_blank">element-tools-example.js</a></p>
<p>The process of getting element tools up and running on your element view is relatively straightforward:</p>
<ul>
<li><a href="#element-tools">Create individual element tools.</a></li>
<li><a href="#add-to-tools-view">Add the element tools to a toolsView.</a></li>
<li><a href="#add-to-element-view">Add the toolsView to an element view.</a></li>
<li><a href="#interaction">Make the tools interactive.</a></li>
</ul>
<p>We will explain every step in turn.
We will also touch on <a href="#custom-button">creating custom buttons</a>.</p>
<h3 id="element-tools">Element Tools</h3>
<p>An <a href="/docs/jointjs#elementTools" target="_blank">element tool</a> (type
<a href="/docs/jointjs#dia.ToolView" target="_blank"><code>joint.dia.ToolView</code></a>) is a view that
renders a certain type of control elements on top of the element view it is attached to; for example the
<code>Boundary</code> <a href="/docs/jointjs#elementTools.Boundary" target="_blank">tool</a> renders an
outline around the bounding box of the element.
The JointJS library comes with a collection of pre-made element tool definitions in the
<a href="/docs/jointjs#elementTools" target="_blank"><code>joint.elementTools</code></a> namespace.</p>
<p>The pre-made element tools include:</p>
<ul>
<li><a href="/docs/jointjs#elementTools.Boundary" target="_blank"><code>Boundary</code></a> - shows the
bounding box of the element</li>
<li><a href="/docs/jointjs#linkTools.Remove" target="_blank"><code>Remove</code></a> - adds an
interactive remove button</li>
</ul>
<p>To create a new element tool, we call its constructor:</p>
<pre><code>var boundaryTool = new joint.elementTools.Boundary();</code></pre>
<p>The element tool constructors also accept optional arguments that modify the appearance and function of the
created tools:</p>
<pre><code>var boundaryTool = new joint.elementTools.Boundary({
padding: 20,
rotate: true,
useModelGeometry: true,
});</code></pre>
<h3 id="add-to-tools-view">Add to Tools View</h3>
<p>Element tools always need to come bundled in a tools view object (type
<a href="/docs/jointjs#dia.ToolsView" target="_blank"><code>joint.dia.ToolsView</code></a>).
This allows them to be shown/hidden as a group above an element.
We create a new tools view and add our tools to it:</p>
<pre><code>var boundaryTool = new joint.elementTools.Boundary();
var removeButton = new joint.elementTools.Remove();
var toolsView = new joint.dia.ToolsView({
tools: [
boundaryTool,
removeButton
]
});</code></pre>
<p>Remember, it is necessary to create a new set of tools for every new tools view object we create; tools
are automatically reassigned to the last tools view that uses them.</p>
<h3 id="add-to-link-view">Add to Element View</h3>
<p>Finally, we need to add our tools view to an element view.
The <a href="/docs/jointjs#dia.ElementView" target="_blank"><code>joint.dia.ElementView</code></a> class
comes with a suite of tools-related methods:</p>
<ul>
<li><a href="/docs/jointjs#dia.ElementView.prototype.addTools" target="_blank"><code>elementView.addTools(toolsView)</code></a>
- adds given <code>toolsView</code> onto the element view.
The tools are visible by default.</li>
<li><a href="/docs/jointjs#dia.ElementView.prototype.showTools" target="_blank"><code>elementView.showTools()</code></a>
- shows tools on the element view.</li>
<li><a href="/docs/jointjs#dia.ElementView.prototype.hideTools" target="_blank"><code>elementView.hideTools()</code></a>
- hides tools on the element view.</li>
<li><a href="/docs/jointjs#dia.ElementView.prototype.removeTools" target="_blank"><code>elementView.removeTools()</code></a>
- removes tools from the element view.</li>
</ul>
<p>We can thus show all of our tools in one place:</p>
<div class="paper" id="paper-element-tools-all"></div>
<pre><code>var elementView = element.findView(paper);
elementView.addTools(toolsView);</code></pre>
<p>JointJS source code: <a href="js/element-tools-all.js" target="_blank">element-tools-all.js</a></p>
<p>Remember, it is necessary to create a new tools view object for every element view; tools view objects are
automatically reassigned to the last element view that uses them.</p>
<h3 id="interaction">Interaction</h3>
<p>You can easily toggle visibility of element tools using the
<code>'element:mouseenter'</code>/<code>'element:mouseleave'</code> Paper events:</p>
<div class="paper" id="paper-element-tools-interaction"></div>
<pre><code>paper.on('element:mouseenter', function(elementView) {
elementView.showTools();
});
paper.on('element:mouseleave', function(elementView) {
elementView.hideTools();
});</code></pre>
<p>JointJS source code: <a href="js/element-tools-interaction.js" target="_blank">element-tools-interaction.js</a></p>
<p>More complex interaction scenarios might require showing, hiding or removing all tools at once.
You can find relevant functions in the Paper class:</p>
<ul>
<li><a href="/docs/jointjs#dia.Paper.prototype.showTools" target="_blank"><code>paper.showTools()</code></a>
- shows tools on all element and link views.</li>
<li><a href="/docs/jointjs#dia.Paper.prototype.hideTools" target="_blank"><code>paper.hideTools()</code></a>
- hides tools on all element and link views.</li>
<li><a href="/docs/jointjs#dia.Paper.prototype.removeTools" target="_blank"><code>paper.removeTools()</code></a>
- removes tools from all element and link views.</li>
</ul>
<p>Note that our example toggles visibility of element tools by using the
<code>showTools()</code>/<code>hideTools()</code> functions.
Element tools may also be toggled by <code>addTools()</code>/<code>removeTools()</code> functions, which
are demonstrated in the <a href="link-tools.html#interaction">link tools tutorial</a>.
For element tools, there is no practical difference between the two approaches.</p>
<h3 id="custom-button">Custom Buttons</h3>
<p>It is possible to create <a href="/docs/jointjs#elementTools.Button" target="_blank">custom buttons</a> to
complement the pre-made <a href="/docs/jointjs#elementTools.Remove" target="_blank"><code>Remove</code></a>
button tool;
JointJS exposes the
<a href="/docs/jointjs#elementTools.Button" target="_blank"><code>joint.elementTools.Button</code></a>
class for you to extend.
The markup of the new button can be sent as <code>options.markup</code>, while the behavior of the
button on pointerdown interaction is determined by the callback function provided in
<code>options.action</code>.</p>
<div class="paper" id="paper-element-tools-custom-button"></div>
<p>You can add the extended button to the <code>joint.elementTools</code> namespace and then just use that
class in the code:</p>
<pre><code>joint.elementTools.InfoButton = joint.elementTools.Button.extend({
name: 'info-button',
options: {
markup: [{
tagName: 'circle',
selector: 'button',
attributes: {
'r': 7,
'fill': '#001DFF',
'cursor': 'pointer'
}
}, {
tagName: 'path',
selector: 'icon',
attributes: {
'd': 'M -2 4 2 4 M 0 3 0 0 M -2 -1 1 -1 M -1 -4 1 -4',
'fill': 'none',
'stroke': '#FFFFFF',
'stroke-width': 2,
'pointer-events': 'none'
}
}],
x: '100%',
y: '100%'
offset: {
x: 0,
y: 0
},
rotate: true,
action: function(evt) {
alert('View id: ' + this.id + '\n' + 'Model id: ' + this.model.id);
}
}
});
var infoButton = new joint.elementTools.InfoButton();
var toolsView = new joint.dia.ToolsView({
tools: [infoButton]
});
var elementView = element.findView(paper);
elementView.addTools(toolsView);</code></pre>
<p>JointJS source code: <a href="js/element-tools-custom-button.js" target="_blank">element-tools-custom-button.js</a></p>
<p>A single-use custom button can also be created by direct reference to the
<a href="/docs/jointjs#elementTools.Button" target="_blank"><code>Button</code></a> class, without making
an entry in the <code>joint.elementTools</code> namespace:</p>
<pre><code>var infoButton = new joint.elementTools.Button({
markup: [{
tagName: 'circle',
selector: 'button',
attributes: {
'r': 7,
'fill': '#001DFF',
'cursor': 'pointer'
}
}, {
tagName: 'path',
selector: 'icon',
attributes: {
'd': 'M -2 4 2 4 M 0 3 0 0 M -2 -1 1 -1 M -1 -4 1 -4',
'fill': 'none',
'stroke': '#FFFFFF',
'stroke-width': 2,
'pointer-events': 'none'
}
}],
x: '100%',
y: '100%',
offset: {
x: 0,
y: 0
},
rotate: true,
action: function(evt) {
alert('View id: ' + this.id + '\n' + 'Model id: ' + this.model.id);
}
});
var toolsView = new joint.dia.ToolsView({
tools: [infoButton]
});
var elementView = element.findView(paper);
elementView.addTools(toolsView);</code></pre>
<p><a href="link-tools.html">In the next section of the intermediate tutorial, we will learn about link
tools.</a></p>
</div><!--end tutorial-->
<script src="../node_modules/prismjs/prism.js"></script>
<script src="js/element-tools-example.js"></script>
<script src="js/element-tools-all.js"></script>
<script src="js/element-tools-interaction.js"></script>
<script src="js/element-tools-custom-button.js"></script>
</body>
</html>