iVis-at-Bilkent/cytoscape.js-grid-guide

Name: cytoscape.js-grid-guide

Owner: iVis-at-Bilkent

Description: A Cytsocape.js extension to provide a framework for grid interactions such as grid lines and snapping to grid, and guidelines and snap support for alignment of nodes.

Created: 2016-06-27 08:02:07.0

Updated: 2017-12-29 01:50:11.0

Pushed: 2017-12-19 11:27:34.0

Homepage:

Size: 343

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

cytoscape-grid-guide

Description

A sophisticated and highly customizable Cytoscape.js extension for grid and guideline interactions, distributed under The MIT License. The following features are provided:

• Grid: Shows a grid in the canvas (with specified size).
• Auto resizing nodes: Nodes are resized to fit perfectly to grid.
• Alignment guidelines on drag: As a node is dragged different types of guidelines are drawn to indicate both horizontal and vertical alignment of the dragged node with others. Two nodes are considered aligned when the difference between their x or y coordinates are within the specified tolerance:
  • Reference guidelines: When the dragged node aligns horizontally or vertically with the position of the mouse when the node is picked for drag, this guideline is drawn.
  • Geometric guidelines: When the dragged node (center or edge) aligns horizontally or vertically with another node (center or edge) within specified range, this guideline is drawn.
  • Distribution guidelines: This type of guideline is drawn in one of these two different cases:
  • when the center of the dragged node is in the middle of the closer edges of two other nodes horizontally or vertically (i.e. dragged node is in the middle of two other nodes)
  • when the distance between the dragged node A to node C is exactly twice the distance to node B horizontally or vertically (i.e. node B is in the middle of the dragged node A and another node C)
• Snapping nodes: Nodes are snapped either to the grid or alignment location. The following options are available:
  • Snap to grid on mouse release: Upon release of the mouse during drag, the node snaps to theclosest grid location.
  • Snap to grid during drag: During drag the node snaps to the closest grid location; dragging is discrete.
  • Snap to alignment location on mouse release: Note that guidelines are drawn when the node is within a certain 'tolerance' amount to perfect alignment. Upon release of the mouse during drag, the node snaps to shown guideline to form perfect alignment.
  • Snap to alignment location during drag: Note that guidelines are drawn when the node is within a certain 'tolerance' amount to perfect alignment. During drag, the node snaps to shown guideline to form perfect alignment.

The users are allowed to customize various things about the functionality including:

• grid size and color
• snap type
• alignment guideline tolerance
• colors and line styles of each type of guidelines
• range of geometric and distribution guidelines (i.e. do not consider nodes that are outside this range for alignment)
• whether or not edge to center alignment should be ignored

Demo

Click here for demo

API

• cy.gridGuide(options) Sets stated options any time wanted.

• eles.align(horizontal, vertical, alignTo) Aligns vertically/horizontally dimensions of eles to first element of eles ( or if alignTo is specified aligns to it). horizontal param may get top, center, bottom and vertical param may get left, center, right and horizontal.

  For example the code below aligns selected nodes to top left of first selected node.

  odes(":selected").align("top", "left")
  

Default Undo/Redo Actions

o("align", {
nodes: cy.nodes(":selected"),
vertical: "left",
horizontal: "top",
alignTo: cy.nodes(":selected")[0],

Default Options

options = {
// On/Off Modules
/* From the following four snap options, at most one should be true at a given time */
snapToGridOnRelease: true, // Snap to grid on release
snapToGridDuringDrag: false, // Snap to grid during drag
snapToAlignmentLocationOnRelease: false, // Snap to alignment location on release
snapToAlignmentLocationDuringDrag: false, // Snap to alignment location during drag
distributionGuidelines: false, // Distribution guidelines
geometricGuideline: false, // Geometric guidelines
initPosAlignment: false, // Guideline to initial mouse position
centerToEdgeAlignment: false, // Center to edge alignment
resize: false, // Adjust node sizes to cell sizes
parentPadding: false, // Adjust parent sizes to cell sizes by padding
drawGrid: true, // Draw grid background

// General
gridSpacing: 20, // Distance between the lines of the grid.

// Draw Grid
zoomDash: true, // Determines whether the size of the dashes should change when the drawing is zoomed in and out if grid is drawn.
panGrid: false, // Determines whether the grid should move then the user moves the graph if grid is drawn.
gridStackOrder: -1, // Namely z-index
gridColor: '#dedede', // Color of grid lines
lineWidth: 1.0, // Width of grid lines

// Guidelines
guidelinesStackOrder: 4, // z-index of guidelines
guidelinesTolerance: 2.00, // Tolerance distance for rendered positions of nodes' interaction.
guidelinesStyle: { // Set ctx properties of line. Properties are here:
    strokeStyle: "#8b7d6b", // color of geometric guidelines
    geometricGuidelineRange: 400, // range of geometric guidelines
    range: 100, // max range of distribution guidelines
    minDistRange: 10, // min range for distribution guidelines
    distGuidelineOffset: 10, // shift amount of distribution guidelines
    horizontalDistColor: "#ff0000", // color of horizontal distribution alignment
    verticalDistColor: "#00ff00", // color of vertical distribution alignment
    initPosAlignmentColor: "#0000ff", // color of alignment to initial mouse location
    lineDash: [0, 0], // line style of geometric guidelines
    horizontalDistLine: [0, 0], // line style of horizontal distribution guidelines
    verticalDistLine: [0, 0], // line style of vertical distribution guidelines
    initPosAlignmentLine: [0, 0], // line style of alignment to initial mouse position
},

// Parent Padding
parentSpacing: -1 // -1 to set paddings of parents to gridSpacing

Dependencies

• Cytoscape.js >=1.6.10
• jQuery ^{1.4 ||} 2.0 || ^3.0

Usage instructions

Download the library:

• via npm: npm install cytoscape-grid-guide,
• via bower: bower install cytoscape-grid-guide, or
• via direct download in the repository (probably from a tag).

require() the library as appropriate for your project:

CommonJS:

cytoscape = require('cytoscape');
grid-guide = require('cytoscape-grid-guide');

-guide( cytoscape, jquery ); // register extension

AMD:

ire(['cytoscape', 'cytoscape-grid-guide'], function( cytoscape, grid-guide ){
grid-guide( cytoscape ); // register extension

Plain HTML/JS has the extension registered for you automatically, because no require() is needed.

Publishing instructions

This project is set up to automatically be published to npm and bower. To publish:

1. Set the version number environment variable: export VERSION=1.2.3
2. Publish: gulp publish
3. If publishing to bower for the first time, you'll need to run bower register cytoscape-grid-guide https://github.com/iVis-at-Bilkent/cytoscape.js-grid-guide.git

Team

• Ilkin Safarli, Selim Firat Yilmaz, Ugur Dogrusoz of i-Vis at Bilkent University