cytoscape-edgehandles
v4.0.1
Published
Edge creation UI extension for Cytoscape
Downloads
39,512
Readme
cytoscape-edgehandles
Description
This extension creates handles on nodes that can be dragged to create edges between nodes (demo, demo (snapping disabled), compound demo, compound demo (snapping disabled))
Dependencies
- Cytoscape.js ^3.2.0
Usage instructions
Download the library:
- via npm:
npm install cytoscape-edgehandles
, - via bower:
bower install cytoscape-edgehandles
, or - via direct download in the repository (probably from a tag).
Import the library as appropriate for your project:
ES import:
import cytoscape from 'cytoscape';
import edgehandles from 'cytoscape-edgehandles';
cytoscape.use( edgehandles );
CommonJS require:
let cytoscape = require('cytoscape');
let edgehandles = require('cytoscape-edgehandles');
cytoscape.use( edgehandles ); // register extension
AMD:
require(['cytoscape', 'cytoscape-edgehandles'], function( cytoscape, edgehandles ){
edgehandles( cytoscape ); // register extension
});
Plain HTML/JS has the extension registered for you automatically, because no require()
is needed.
Initialisation
You initialise the extension on the Cytoscape instance:
let cy = cytoscape({
container: document.getElementById('#cy'),
/* ... */
});
// the default values of each option are outlined below:
let defaults = {
canConnect: function( sourceNode, targetNode ){
// whether an edge can be created between source and target
return !sourceNode.same(targetNode); // e.g. disallow loops
},
edgeParams: function( sourceNode, targetNode ){
// for edges between the specified source and target
// return element object to be passed to cy.add() for edge
return {};
},
hoverDelay: 150, // time spent hovering over a target node before it is considered selected
snap: true, // when enabled, the edge can be drawn by just moving close to a target node (can be confusing on compound graphs)
snapThreshold: 50, // the target node must be less than or equal to this many pixels away from the cursor/finger
snapFrequency: 15, // the number of times per second (Hz) that snap checks done (lower is less expensive)
noEdgeEventsInDraw: true, // set events:no to edges during draws, prevents mouseouts on compounds
disableBrowserGestures: true // during an edge drawing gesture, disable browser gestures such as two-finger trackpad swipe and pinch-to-zoom
};
let eh = cy.edgehandles( defaults );
API
The object returned by cy.edgehandles()
has several functions available on it:
start( sourceNode )
: manually start the gesture (as if the handle were already held)stop()
: manually completes or cancels the gesturedisable()
: disables edgehandles behaviourenable()
: enables edgehandles behaviourenableDrawMode()
: turn on draw mode (the entire node body acts like the handle)disableDrawMode()
: turn off draw modedestroy()
: remove edgehandles behaviour
Classes
These classes can be used for styling the graph as it interacts with the extension:
eh-source
: The source nodeeh-target
: A target nodeeh-preview
: Preview edges (i.e. shown before releasing the mouse button and the edge creation is confirmed)eh-hover
: Added to nodes as they are hovered over as targetseh-ghost-node
: The ghost node (target), used when the cursor isn't pointed at a target node yet (i.e. in place of a target node)eh-ghost-edge
: The ghost handle line edge, used when the cursor isn't pointed at a target node yet (i.e. the edge is pointing to empty space)eh-ghost
: A ghost elementeh-presumptive-target
: A node that, during an edge drag, may become a target when releasedeh-preview-active
: Applied to the source, target, and ghost edge when the preview is active
Events
During the course of a user's interaction with the extension, several events are generated and triggered on the core. Each event callback has a number of extra parameters, and certain events have associated positions.
ehstart
: when the edge creation gesture starts(event, sourceNode)
event.position
: handle position
ehcomplete
: when the edge is created(event, sourceNode, targetNode, addedEdge)
event.position
: cursor/finger position
ehstop
: when the edge creation gesture is stopped (either successfully completed or cancelled)(event, sourceNode)
event.position
: cursor/finger position
ehcancel
: when the edge creation gesture is cancelled(event, sourceNode, cancelledTargets)
event.position
: cursor/finger position
ehhoverover
: when hovering over a target(event, sourceNode, targetNode)
event.position
: cursor/finger position
ehhoverout
: when leaving a target node(event, sourceNode, targetNode)
event.position
: cursor/finger position
ehpreviewon
: when a preview is shown(event, sourceNode, targetNode, previewEdge)
event.position
: cursor/finger position
ehpreviewoff
: when the preview is removed(event, sourceNode, targetNode, previewEdge)
event.position
: cursor/finger position
ehdrawon
: when draw mode is enabled(event)
ehdrawoff
: when draw mode is disabled(event)
Example binding:
cy.on('ehcomplete', (event, sourceNode, targetNode, addedEdge) => {
let { position } = event;
// ...
});
Build targets
npm run test
: Run Mocha tests in./test
npm run build
: Build./src/**
intocytoscape-edgehandles.js
npm run watch
: Automatically build on changes with live reloading (N.b. you must already have an HTTP server running)npm run dev
: Automatically build on changes with live reloading with webpack dev servernpm run lint
: Run eslint on the source
N.b. all builds use babel, so modern ES features can be used in the src
.
Publishing instructions
This project is set up to automatically be published to npm and bower. To publish:
- Build the extension :
npm run build:release
- Commit the build :
git commit -am "Build for release"
- Bump the version number and tag:
npm version major|minor|patch
- Push to origin:
git push && git push --tags
- Publish to npm:
npm publish .
- If publishing to bower for the first time, you'll need to run
bower register cytoscape-edgehandles https://github.com/cytoscape/edgehandles.git
a - Make a new release for Zenodo.