Merge branch 'unstable' into background-image-containment

.github/CONTRIBUTING.md

@@ -2,34 +2,31 @@
 
 Cytoscape.js is an open source project, and we greatly appreciate any and all contributions.
 
-A blog post is available [on blog.js.cytoscape.org](http://blog.js.cytoscape.org/2017/06/13/contributing/) geared towards first-time contributors with more in-depth instructions on the project's structure, the process of creating and merging changes to the code, and more.
+A blog post is available [on blog.js.cytoscape.org](http://blog.js.cytoscape.org/2017/06/13/contributing/) geared towards first-time code contributors with more in-depth instructions on the project's structure, the process of creating and merging changes to the code, and more.
 
-If you'd like to contribute code to Cytoscape.js but you're not sure exactly what you'd like to implement, take a look at our [current milestones](https://github.com/cytoscape/cytoscape.js/milestones) to see what features we have planned in future --- or anything labelled [`help-wanted`](https://github.com/cytoscape/cytoscape.js/issues?q=is%3Aopen+is%3Aissue+label%3Ahelp-wanted).  Of course, we also welcome your own ideas.
+If you'd like to contribute code to Cytoscape.js but you're not sure exactly what you'd like to implement, take a look at our [current milestones](https://github.com/cytoscape/cytoscape.js/milestones) to see what features we have planned in future --- or anything labelled [`help-wanted`](https://github.com/cytoscape/cytoscape.js/issues?q=is%3Aopen+is%3Aissue+label%3Ahelp-wanted).  Of course, we also welcome your own ideas.  You can discuss new ideas with the community on [GitHub discussions](https://github.com/cytoscape/cytoscape.js/discussions).
 
-Our goal is to make Cytoscape.js as comprehensive as possible.  Thank you for taking the time and effort to contribute to help make that happen!
+Our goal is to make Cytoscape.js easy to use and comprehensive.  Thank you for taking the time and effort to contribute to help make that happen!
 
 
 
 ## Submitting issues
 
-Submit issues or feature requests to the [issue tracker](https://github.com/cytoscape/cytoscape.js/issues).  If your issue pertains to an extension, you should file the issue on that extension's issue tracker instead.
+The first step in providing a code contribution is to write [a short, descriptive issue](https://github.com/cytoscape/cytoscape.js/issues).  If your issue pertains to an extension, you should file the issue on that extension's issue tracker instead.
 
-Before submitting an issue, please ensure that the issue still exists in the latest version of the library.  Because we follow semver, you can safely upgrade patch releases (x.y.**z**) and feature releases (x.**y**) without worry of breaking API changes.
+Describe the bug or feature that you are addressing in your issue.  Then, create your issue's corresponding pull request that contains your code changes.
 
-Clearly describe your issue.  List the steps necessary to reproduce your issue along with the corresponding code (preferably a JSBin, as that makes the issue less ambiguous and much faster to fix).
 
-Make certain to mention the version of the library you are using and version of the browser/environment you are using.
-
-
-
-## Where to put changes
+## How to make your changes in a pull request
 
 New features go in the `unstable` branch, which is used for the next (breaking/major or feature/minor) version.  Bugfixes go in the `master` branch for the next bugfix/patch version.  This allows us to follow [semver](http://semver.org/) nicely.
 
-To propose a change, [fork](https://help.github.com/articles/fork-a-repo/) the cytoscape.js repository on Github, make a change, and then submit a [pull request](https://help.github.com/articles/creating-a-pull-request/) so that the proposed changes can be reviewed.
+To propose a change, [fork](https://help.github.com/articles/fork-a-repo/) the cytoscape.js repository on Github, make a change, and then submit a [pull request](https://help.github.com/articles/creating-a-pull-request/) so that the proposed changes can be reviewed.  If this is your first time making a pull request on GitHub, you can refer to [our comprehensive, step-by-step blog post](https://blog.js.cytoscape.org/2017/06/13/contributing/).
 
 The source is organised in relatively the same as the documentation, under `./src`.  Try to maintain that organisation as best you can.  You are free to create new files and `require()` them using ESM [`import`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) and [`export`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export).
 
+Add your new feature to the documentation.  Updates to the documentation should go in [`docmaker.json`](https://github.com/cytoscape/cytoscape.js/blob/unstable/documentation/docmaker.json) file or the accompanying md files.  The documentation's HTML is generated from a template, and so it should not be edited directly.
+
 
 
 ## Code style
@@ -50,4 +47,4 @@ If your change is visual/rendering-related, then Mocha tests are not pragmatic.
 
 Please run `npm test` to make sure all the unit tests are passing before you make your pull request.
 
-We also have support for running the Mocha tests in IE9+ and other old browsers.  You can run the tests in a [Windows IE VM](https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/) while running `npm run watch:umd`.  Go to `http://youripaddress:8081/test/ie.html` in IE to open the Mocha test page.
+We also have support for running the Mocha tests in IE9+ and other old browsers.  You can run the tests in a [Windows IE VM](https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/) while running `npm run watch:umd`.  Go to `http://youripaddress:8081/test/ie.html` in IE to open the Mocha test page.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,41 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Before you post**
+
+A request for help or a requests for a how-to should be directed to Stack Overflow:
+http://stackoverflow.com/questions/tagged/cytoscape.js
+
+
+
+**Environment info**
+
+- Cytoscape.js version :
+- Browser/Node.js & version :
+
+
+
+**Current (buggy) behaviour**
+
+_What does the bug do?_
+
+
+
+**Desired behaviour**
+
+_What do you expect Cytoscape.js to do instead?_
+
+
+
+**Minimum steps to reproduce**
+
+_What do you need to do to reproduce the issue?_
+
+_Fork/clone this JSBin demo and reproduce your issue so that your issue can be addressed quickly and effectively:_
+http://jsbin.com/fiqugiq

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Description of new feature**
+
+_What should the new feature do?  For visual features, include an image/mockup of the expected output._
+
+
+
+**Motivation for new feature**
+
+_Describe your use case for this new feature._

README.md

@@ -2,10 +2,11 @@
 
 [![GitHub repo](https://img.shields.io/badge/Repo-GitHub-yellow.svg)](https://github.com/cytoscape/cytoscape.js)
 [![Twitter updates](https://img.shields.io/badge/Updates-Twitter-yellow.svg)](https://twitter.com/cytoscapejs)
-[![News and tutorials](https://img.shields.io/badge/News%20and%20tutorials-Blog-yellow.svg)](https://blog.js.cytoscape.org)
+[![News and tutorials](https://img.shields.io/badge/News%20%26%20tutorials-Blog-yellow.svg)](https://blog.js.cytoscape.org)
 [![Questions at StackOverflow](https://img.shields.io/badge/Questions-StackOverflow-yellow.svg)](https://stackoverflow.com/questions/tagged/cytoscape.js)
 [![Ask a question at StackOverflow](https://img.shields.io/badge/Ask%20a%20question-StackOverflow-yellow.svg)](https://stackoverflow.com/questions/ask?tags=cytoscape.js,javascript)
-[![GitHub license](https://img.shields.io/badge/License-MIT-blue.svg)](https://raw.githubusercontent.com/cytoscape/cytoscape.js/master/LICENSE)
+[![Community discussions](https://img.shields.io/badge/Community%20discussions-GitHub-yellow.svg)](https://github.com/cytoscape/cytoscape.js/discussions)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://raw.githubusercontent.com/cytoscape/cytoscape.js/master/LICENSE)
 [![DOI](https://zenodo.org/badge/2255947.svg)](https://zenodo.org/badge/latestdoi/2255947)
 [![Cite](https://img.shields.io/badge/Cite-Oxford%20Bioinformatics%20Article-blue.svg)](https://js.cytoscape.org/#introduction/citation)
 [![npm](https://img.shields.io/npm/v/cytoscape.svg)](https://www.npmjs.com/package/cytoscape)
@@ -14,7 +15,6 @@
 [![npm installs](https://img.shields.io/npm/dm/cytoscape.svg?label=npm%20installs)](https://www.npmjs.com/package/cytoscape)
 [![master branch tests](https://img.shields.io/travis/cytoscape/cytoscape.js/master.svg?label=master%20branch)](https://travis-ci.org/cytoscape/cytoscape.js)
 [![unstable branch tests](https://img.shields.io/travis/cytoscape/cytoscape.js/unstable.svg?label=unstable%20branch)](https://travis-ci.org/cytoscape/cytoscape.js)
-[![Greenkeeper badge](https://badges.greenkeeper.io/cytoscape/cytoscape.js.svg)](https://greenkeeper.io/)
 
 # Cytoscape.js
 
@@ -53,9 +53,11 @@ Future versions of Cytoscape.js are planned in the [milestones of the Github iss
 
 ## Contributing to Cytoscape.js
 
-Please refer to [CONTRIBUTING.md](.github/CONTRIBUTING.md).
+Would you like to become a Cytoscape.js contributor?  You can contribute in technical roles (e.g. features, testing) or non-technical roles (e.g. documentation, outreach), depending on your interests.  [Get in touch with us by posting a GitHub discussion](https://github.com/cytoscape/cytoscape.js/discussions).
 
-Feature releases are made at the start of each month, while patch releases are made at the start of each week.  This allows for rapid releases of first- and third-party contributions.
+For the mechanics of contributing a pull request, refer to [CONTRIBUTING.md](.github/CONTRIBUTING.md).
+
+Feature releases are made monthly, while patch releases are made weekly.  This allows for rapid releases of first- and third-party contributions.
 
 
 

documentation/demos/tokyo-railways/index.html

@@ -6,7 +6,7 @@
 <meta charset=utf-8 />
 <meta name="viewport" content="user-scalable=no, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, minimal-ui">
 <title>Tokyo railways</title>
-  <link href="http://maxcdn.bootstrapcdn.com/font-awesome/4.2.0/css/font-awesome.min.css" rel="stylesheet" />
+  <link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.2.0/css/font-awesome.min.css" rel="stylesheet" />
   <link rel="stylesheet" href="https://unpkg.com/tippy.js@2.0.9/dist/tippy.css" />
   <link href="style.css" rel="stylesheet">
 </head>
@@ -17,7 +17,7 @@
   </div>
   <button id="clear">CLEAR</button>
 
-  <script src="http://cdnjs.cloudflare.com/ajax/libs/bluebird/1.2.2/bluebird.min.js"></script>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/bluebird/1.2.2/bluebird.min.js"></script>
   <script src="https://unpkg.com/whatwg-fetch@3.0.0/dist/fetch.umd.js"></script>
   <script src="https://unpkg.com/popper.js@1.14.4/dist/umd/popper.js"></script>
   <script src="https://unpkg.com/tippy.js@2.0.9/dist/tippy.all.js"></script>

documentation/docmaker.json

@@ -66,8 +66,7 @@
         { "name": "Edge arrow types", "id": "edge-arrows" },
         { "name": "Labels", "id": "labels" },
         { "name": "Compound nodes", "id": "compound-nodes" },
-        { "name": "Linkout example", "id": "linkout-example" },
-        { "name": "Pie style", "id": "pie-style" }
+        { "name": "Linkout example", "id": "linkout-example" }
       ],
       "disabledDemos": [
         { "name": "Multiple instances", "id": "multiple-instances" },

documentation/md/core/init.md

@@ -33,6 +33,7 @@ An instance of Cytoscape.js has a number of options that can be set on initialis
   <a href="#init-opts/elements">elements</a>: [ /* ... */ ],
   <a href="#init-opts/style">style</a>: [ /* ... */ ],
   <a href="#init-opts/layout">layout</a>: { name: 'grid' /* , ... */ },
+  <a href="#init-opts/data">data</a>: { /* ... */ },
 
   // initial viewport state:
   <a href="#init-opts/zoom">zoom</a>: 1,
@@ -79,7 +80,8 @@ An instance of Cytoscape.js has a number of options that can be set on initialis
 <span id="init-opts/layout"></span>
 **`layout`** : A plain object that specifies layout options.  Which layout is initially run is specified by the `name` field.  Refer to a [layout's documentation](#layouts) for the options it supports.  If you want to specify your node positions yourself in your elements JSON, you can use the `preset` layout --- by default it does not set any positions, leaving your nodes in their current positions (i.e. specified in `options.elements` at initialisation time).
 
-
+<span id="init-opts/data"></span>
+**`data`** : A plain object that contains [graph-level data](#cy.data) (i.e. data that does not belong to any particular node or edge).
 ### Initial viewport state
 
 <span id="init-opts/zoom"></span>

documentation/md/intro.md

@@ -71,6 +71,7 @@
   * [Google](https://google.com) : [TensorFlow](https://www.tensorflow.org) : SyntaxNet : DRAGNN visualiser
   * [GCHQ](https://www.gchq.gov.uk/) : [Gaffer](https://gchq.github.io/gaffer-doc/)
   * [GeneMANIA](http://genemania.org)
+  * [Global CTO Forum](https://globalctoforum.org)
   * [Graphlytic](http://graphlytic.sk/)
   * [Hacker Target](https://hackertarget.com/) : [Domain Profiler](https://hackertarget.com/domain-profiler/)
   * [Harvard University](https://www.harvard.edu) : [BioPlex](http://bioplex.hms.harvard.edu/bioplexDisplay)
@@ -144,8 +145,10 @@ The library was created at the [Donnelly Centre](http://thedonnellycentre.utoron
 ## Releases
 
 - 3.17
+ - [3.17.1](https://github.com/cytoscape/cytoscape.js/issues?q=milestone%3A3.17.1+is%3Aclosed)
  - [3.17.0](https://github.com/cytoscape/cytoscape.js/issues?q=milestone%3A3.17.0+is%3Aclosed)
 - 3.16
+ - [3.16.5](https://github.com/cytoscape/cytoscape.js/issues?q=milestone%3A3.16.5+is%3Aclosed)
  - [3.16.4](https://github.com/cytoscape/cytoscape.js/issues?q=milestone%3A3.16.4+is%3Aclosed)
  - [3.16.3](https://github.com/cytoscape/cytoscape.js/issues?q=milestone%3A3.16.3+is%3Aclosed)
  - [3.16.2](https://github.com/cytoscape/cytoscape.js/issues?q=milestone%3A3.16.2+is%3Aclosed)

documentation/md/links.md

@@ -2,10 +2,11 @@
 
 [![GitHub repo](https://img.shields.io/badge/Repo-GitHub-yellow.svg)](https://github.com/cytoscape/cytoscape.js)
 [![Twitter updates](https://img.shields.io/badge/Updates-Twitter-yellow.svg)](https://twitter.com/cytoscapejs)
-[![News and tutorials](https://img.shields.io/badge/News%20and%20tutorials-Blog-yellow.svg)](https://blog.js.cytoscape.org)
+[![News and tutorials](https://img.shields.io/badge/News%20%26%20tutorials-Blog-yellow.svg)](https://blog.js.cytoscape.org)
 [![Questions at StackOverflow](https://img.shields.io/badge/Questions-StackOverflow-yellow.svg)](https://stackoverflow.com/questions/tagged/cytoscape.js)
 [![Ask a question at StackOverflow](https://img.shields.io/badge/Ask%20a%20question-StackOverflow-yellow.svg)](https://stackoverflow.com/questions/ask?tags=cytoscape.js,javascript)
-[![GitHub license](https://img.shields.io/badge/License-MIT-blue.svg)](https://raw.githubusercontent.com/cytoscape/cytoscape.js/master/LICENSE)
+[![Community discussions](https://img.shields.io/badge/Community%20discussions-GitHub-yellow.svg)](https://github.com/cytoscape/cytoscape.js/discussions)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://raw.githubusercontent.com/cytoscape/cytoscape.js/master/LICENSE)
 [![DOI](https://zenodo.org/badge/2255947.svg)](https://zenodo.org/badge/latestdoi/2255947)
 [![Cite](https://img.shields.io/badge/Cite-Oxford%20Bioinformatics%20Article-blue.svg)](#introduction/citation)
 [![npm](https://img.shields.io/npm/v/cytoscape.svg)](https://www.npmjs.com/package/cytoscape)
@@ -14,6 +15,5 @@
 [![npm installs](https://img.shields.io/npm/dm/cytoscape.svg?label=npm%20installs)](https://www.npmjs.com/package/cytoscape)
 [![master branch tests](https://img.shields.io/travis/cytoscape/cytoscape.js/master.svg?label=master%20branch)](https://travis-ci.org/cytoscape/cytoscape.js)
 [![unstable branch tests](https://img.shields.io/travis/cytoscape/cytoscape.js/unstable.svg?label=unstable%20branch)](https://travis-ci.org/cytoscape/cytoscape.js)
-[![Greenkeeper badge](https://badges.greenkeeper.io/cytoscape/cytoscape.js.svg)](https://greenkeeper.io/)
 
 </div>

documentation/md/style.md

@@ -92,7 +92,7 @@ In the JSON or function stylesheet formats, it is possible to specify a function
 
 <span class="important-indicator"></span> Note that if using functions as style values, it will not be possible to serialise and deserialise your stylesheet to JSON proper.
 
-<span class="important-indicator"></span> The function should not read any other style values, nor should it mutate state for elements or for the graph.  Generally, it should depend only on reading `ele.data()` or `ele.scratch()`.
+<span class="important-indicator"></span> The function should not read any other style values, nor should it mutate state for elements or for the graph.  Generally, it should depend only on reading `ele.data()`, `ele.scratch()`, `cy.data()`, or `cy.scratch()`.
 
 Example:
 
@@ -298,6 +298,7 @@ A background image may be applied to a node's body.  The following properties su
     * The [`cytoscape-sbgn-stylesheet`](https://github.com/PathwayCommons/cytoscape-sbgn-stylesheet) package serves as a good example for the use of SVG images in a stylesheet.  That stylesheet [creates decorations](https://pathwaycommons.github.io/cytoscape-sbgn-stylesheet/) on nodes in line with the [SBGN standard](https://sbgn.github.io).
 * **`background-image-crossorigin`**: All images are loaded with a [`crossorigin`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-crossorigin) attribute which may be `anonymous` or `use-credentials`. The default is set to `anonymous`.
 * **`background-image-opacity`** : The opacity of the background image.
+* **`background-image-smoothing`** : Determines whether background image is smoothed (`yes`, default) or not (`no`). This is only a hint, and the browser may or may not respect the value set for this property.
 * **`background-width`** : Specifies the width of the image.  A percent value (e.g. `50%`) may be used to set the image width relative to the node width.  If used in combination with `background-fit`, then this value overrides the width of the image in calculating the fitting --- thereby overriding the aspect ratio.  The `auto` value is used by default, which uses the width of the image.
 * **`background-height`** : Specifies the height of the image.  A percent value (e.g. `50%`) may be used to set the image height relative to the node height.  If used in combination with `background-fit`, then this value overrides the height of the image in calculating the fitting --- thereby overriding the aspect ratio.  The `auto` value is used by default, which uses the height of the image.
 * **`background-fit`** : How the background image is fit to the node; may be `none` for original size, `contain` to fit inside node, or `cover` to cover the node.
@@ -328,18 +329,6 @@ The following is an example of valid background image styling using JSON. The ex
 
 
 
-## Pie chart background
-
-These properties allow you to create pie chart backgrounds on nodes ([demo](demos/pie-style)).  Note that 16 slices maximum are supported per node, so in the properties `1 <= i <= 16`.  Of course, you must specify a numerical value for each property in place of `i`.  Each nonzero sized slice is placed in order of `i`, starting from the 12 o'clock position and working clockwise.
-
-You may find it useful to reserve a number to a particular colour for all nodes in your stylesheet.  Then you can specify values for `pie-i-background-size` accordingly for each node via a [mapper](#style/mappers).  This would allow you to create consistently coloured pie charts in each node of the graph based on element data.
-
- * **`pie-size`** : The diameter of the pie, measured as a percent of node size (e.g. `100%`) or an absolute length (e.g. `25px`).
- * **`pie-i-background-color`** : The colour of the node's ith pie chart slice.
- * **`pie-i-background-size`** : The size of the node's ith pie chart slice, measured in percent (e.g. `25%` or `25`).
- * **`pie-i-background-opacity`** : The opacity of the node's ith pie chart slice.
-
-
 
 ## Edge line