### Script includes

To use Cytoscape.js in your HTML document:

```html
<script src="cytoscape.js"></script>
```

To use Cytoscape.js in Node.js:

```js
var cytoscape = require('cytoscape');
```

### Getting started

An instance of Cytoscape.js correeponds to a graph.  You can create an instance as follows:

```js
cytoscape({
  container: someHtmlDomElement,
  ready: function(){}
});
```

If you are running Cytoscape.js in Node.js or otherwise running it headlessly, you will not specify the `container` option.

If you've included jQuery on a HTML document, you can alternatively initialise Cytoscape.js on a HTML DOM element using the traditional jQuery style: 

```js
$("#cy").cytoscape({ // for some div with id 'cy'
  ready: function(){
    // you can access the core object API through cy
  },
  ...
});
```

This initialises Cytoscape.js and returns back to you your instance of jQuery.  You can continue using jQuery functions, as usual for a jQuery plugin.

For example, 

```js
$("#cy").cytoscape(options)
  .css("background", "red")
  .css("border-color", "black"); // can use jquery functions on 'cy' div 
```

Because this style doesn't give you access to the `cy` object outside of the callback function, there is an option to get the `cy` object from a jQuery selector.

```js
$("#cy").cytoscape(options);
var cy = $("#cy").cytoscape("get"); // now we have a global reference to `cy`
```





### The ready callback

All of your code that uses the core object API, i.e. through the `cy` object in the examples above, must do so after the `ready` callback function has executed.  You can specify the `ready` callback in the initialisation options, outlined in the following section.

Because the `ready` event may occur before you can bind to the core, you can use this shortcut to spread your code among several JavaScript files without having to call a bunch of global functions in `options.ready`.

```js
// in foo.js
$(function(){ // on jquery ready

  $("#cy").cytoscape(function(eventObject){ // on Cytoscape.js ready on the `cy` div
    // this code executes when Cytoscape.js is ready even though we
    // don't actually initialise Cytoscape.js on the `cy` div until
    // bar.js is loaded

    var cy = this; // `this` holds the reference to the core object

    console.log("Ready, Freddie!");
  });

});

// in bar.js (should be after foo.js in your js includes)
$(function(){ // on jquery ready
  $("#cy").cytoscape(options);
});
```


### Initialisation options

An instance of Cytoscape.js has a number of options that can be set on initialisation.  They are outlined below.

```js
$("#cy").cytoscape({
  layout: { ... },
  zoom: 1,
  minZoom: 1e-50,
  maxZoom: 1e50,
  pan: { x: 0, y: 0 },
  renderer: { ... },
  style: { ... },
  ready: function(evt){ ... },
  elements: ...
});
```

**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 for the options it supports.

**zoom** : The initial zoom level of the graph.  Make sure to disable viewport manipulation options, such as `fit`, in your layout so that it is not overridden when the layout is applied.  You can set **minZoom** and **maxZoom** to set restrictions on the zoom level.

**pan** : The initial panning position of the graph.  Make sure to disable viewport manipulation options, such as `fit`, in your layout so that it is not overridden when the layout is applied. 

**renderer** : A plain object containing options for the renderer to be used.  The `name` field specifies which renderer is used.  You need not specify anything for this option, unless you want to use a custom renderer.  

**style** : The stylesheet used to style the document.

For example:

```js
{
  ...

  style: cytoscape.stylesheet()
    .selector('node')
      .css({
        'background-color': 'red',
        'border-color': '#ffff00'
      })
    .selector('edge')
      .css({
        'line-color': 'blue'
      })

  ...
}
```

**ready** : A callback function that is called when Cytoscape.js is ready to be interacted with.  You can not call functions on the `cy` object before this function executes.

**elements** : An array of elements specified as plain objects.

For example:

```js
{
  ...

  elements: [
    {
      data: { id: 'foo' }, 
      group: 'nodes'
    },

    {
      data: { id: 'bar' },
      group: 'nodes'
    },

    {
      data: { weight: 100 }, // elided id => autogenerated id 
      group: 'nodes',
      position: {
        x: 100,
        y: 100
      },
      classes: 'className1 className2',
      selected: true,
      selectable: true,
      locked: true,
      grabbable: true
    },

    {
      data: { id: 'baz', source: 'foo', target: 'bar' },
      group: 'edges'
    }
  ]

  ...
}
```

You can alternatively specify separate arrays indexed in a object by the group names so you don't have to specify the `group` property over and over for each element:

```js
{
  ...

  elements: {
    nodes: [
      { data: { id: 'foo' } }, // NB no group specified
      { ... },
      { ... }
    ],

    edges: [
      { ... }
    ]
  }

  ...
}
```
