# cytoscape-edgehandles

> Edge creation UI extension for Cytoscape

Latest version **4.0.1** (published 2021-07-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install cytoscape-edgehandles
pnpm add cytoscape-edgehandles
yarn add cytoscape-edgehandles
bun add cytoscape-edgehandles
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.1 |
| Published | 2021-07-28 |
| First published | 2015-01-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/cytoscape-edgehandles) |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 196.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Max Franz |
| Maintainers | cytoscapenpm, maxkfranz, dylanfong |
| Keywords | cytoscape, cytoscape-extension |

## Links

- npm: https://www.npmjs.com/package/cytoscape-edgehandles
- Repository: https://github.com/cytoscape/edgehandles
- Issues: https://github.com/cytoscape/edgehandles/issues
- npm.io page: https://npm.io/package/cytoscape-edgehandles

## Dependencies (2)

- [lodash.memoize](https://npm.io/package/lodash.memoize.md) ^4.1.2
- [lodash.throttle](https://npm.io/package/lodash.throttle.md) ^4.1.1

## Recent versions

- 4.0.1 (latest) — 2021-07-28
- 4.0.0 — 2021-07-22
- 3.6.0 — 2019-07-24
- 3.5.1 — 2019-03-08
- 3.5.0 — 2018-12-03
- 3.4.4 — 2018-12-03
- 3.4.3 — 2018-11-30
- 3.4.2 — 2018-10-24
- 3.4.1 — 2018-08-17
- 3.4.0 — 2018-07-12
- 3.3.0 — 2018-07-11
- 3.2.4 — 2018-03-29
- 3.2.3 — 2018-03-15
- 3.2.2 — 2018-03-08
- 3.2.1 — 2018-02-13
- … 42 more at https://npm.io/package/cytoscape-edgehandles/versions

## README

cytoscape-edgehandles
================================================================================

[![DOI](https://zenodo.org/badge/16078488.svg)](https://zenodo.org/badge/latestdoi/16078488)

![Preview](https://raw.githubusercontent.com/cytoscape/cytoscape.js-edgehandles/master/img/preview.png)

## Description


This extension creates handles on nodes that can be dragged to create edges between nodes ([demo](https://cytoscape.github.io/cytoscape.js-edgehandles/), [demo (snapping disabled)](https://cytoscape.github.io/cytoscape.js-edgehandles/demo-snap.html), [compound demo](https://cytoscape.github.io/cytoscape.js-edgehandles/demo-compound.html), [compound demo (snapping disabled)](https://cytoscape.github.io/cytoscape.js-edgehandles/demo-compound-snap.html))


## 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:

```js
import cytoscape from 'cytoscape';
import edgehandles from 'cytoscape-edgehandles';

cytoscape.use( edgehandles );
```

CommonJS require:

```js
let cytoscape = require('cytoscape');
let edgehandles = require('cytoscape-edgehandles');

cytoscape.use( edgehandles ); // register extension
```

AMD:

```js
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:

```js

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 gesture
* `disable()` : disables edgehandles behaviour
* `enable()` : enables edgehandles behaviour
* `enableDrawMode()` : turn on draw mode (the entire node body acts like the handle)
* `disableDrawMode()` : turn off draw mode
* `destroy()` : remove edgehandles behaviour


## Classes

These classes can be used for styling the graph as it interacts with the extension:

* `eh-source` : The source node
* `eh-target` : A target node
* `eh-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 targets
* `eh-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 element
* `eh-presumptive-target` : A node that, during an edge drag, may become a target when released
* `eh-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:

```js
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/**` into `cytoscape-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 server
* `npm 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:

1. Build the extension : `npm run build:release`
1. Commit the build : `git commit -am "Build for release"`
1. Bump the version number and tag: `npm version major|minor|patch`
1. Push to origin: `git push && git push --tags`
1. Publish to npm: `npm publish .`
1. If publishing to bower for the first time, you'll need to run `bower register cytoscape-edgehandles https://github.com/cytoscape/edgehandles.git`a
1. [Make a new release](https://github.com/cytoscape/cytoscape.js-edgehandles/releases/new) for Zenodo.

---
_Source: https://npm.io/package/cytoscape-edgehandles · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._