Key Concepts

An instance of Ogma is a javascript object that stores a graph internally and renders it in an HTML container according to styling rules.

Graph

A graph consists in entities (nodes) connected to each others by relationships (edges). Each node and edge embeds a data object that can be used to store custom properties.

Besides an API to manipulate the internal graph, Ogma offers convenient functions to generate random graphs, import graphs and connect to external data sources.

// Import a graph from a file and set it as ogma's internal graph.
Ogma.parse
  .jsonFromUrl('data/myfile.json')
  .then(rawGraph => ogma.setGraph(rawGraph))
  .then(() => {
    // Retrieve the nodes from the 'Customer' category.
    // 'Category' is a property stored in the node's data object.
    const customers = ogma
      .getNodes()
      .filter(node => node.getData('Category') === 'Customer');

    // Print the customers's names to the console.
    // 'name' is a property stored in the node's data object.
    console.log(customers.getData('name').join());
  });

HTML Container

An instance of Ogma is bound to an HTML container (generally, a <div> element) that holds the graph visualisation. This binding can take place in Ogma's constructor or later on with the ogma.setContainer() function. The following pieces of code are equivalent:

const ogma = new Ogma({
  container: 'graph-container'
});

is equivalent to:

const ogma = new Ogma();
ogma.setContainer('graph-container');

Styling

There are multiple ways to set the style of a graph, by decreasing priority:

• Nodes and edges can have a attributes property that is automatically applied when importing the graph (see the node and edge style formats).
• Styles defined via design rules automatically style nodes and edges.
• The style of specific nodes and edges can be overridden by manual styles that have priority over design rules.

Example:

// Add a node that has a style.
ogma.addNode({ id: 'n0', attributes: { color: 'red', shape: 'circle' } });

// Create a rule that styles all nodes so they have a green color and a radius of 5.
ogma.styles.addNodeRule({
  color: 'green',
  radius: 5
});

// Create a rule that styles the nodes matching a **selector** (a predicate function) so they have a red color.
// Note that the radius fo those nodes is 5 as they also match the rule above.
ogma.styles.addNodeRule(node => node.getData('isValid') === true, {
  color: 'red'
});

// Apply a manual style to the node 'n0'
ogma.getNode('n0').setStyle({ color: 'purple' });

More info on styling

Renderers

Ogma can use three different rendering technologies to display graphs:

• WebGL: most powerful (recommended for graphs over 2,000 nodes)
• HTML 5 Canvas: slower than WebGL but widely supported and better quality (recommended for graphs under 2,000 nodes)
• SVG: slower than Canvas.

By default, Ogma will use WebGL, and fallback on Canvas if not available. It is possible to specify the technology to use in the Ogma constructor.

// Create an instance of Ogma that uses the 'canvas' render
const ogma = new Ogma({
  renderer: 'canvas',
  container: 'graph-container'
});

// Possible values for the `renderer` parameter are: 'webgl' (default), 'canvas' and 'svg'