@linkurious/ogma-react v5.0.3

@linkurious/ogma-react

Wrapper library for @linkurious/ogma to use with React.

• Getting started
• Usage
• API
  • <Ogma />
  • Styles:
    • <NodeStyle />
    • <EdgeStyle />
  • Overlays:
    • <Popup />
    • <Tooltip />
    • <CanvasLayer />
    • <Layer />
    • <Overlay />
  • Transformations:
    • <NodeGrouping />
    • <EdgeGrouping />
    • <NodeFilter />
    • <EdgeFilter />
    • <NeighborGeneration />
    • <NeighborMerging />
    • <NodeCollapsing />
  • <Geo />

Getting Started

Add @linkurious/ogma and @linkurious/ogma-react to your project. For Ogma, you should use you NPM link from get.linkurio.us.

npm install <YOUR_LINK_WITH_API_KEY>
npm i @linkurious/ogma-react --save

Or, with yarn:

yarn i <YOUR_LINK_WITH_API_KEY>
yarn add @linkurious/ogma-react

You will need the CSS or Styled Components (see web/src/index.css for an example). No CSS is included by default.

import { Ogma, NodeStyle, Popup } from '@linkurious/ogma-react';
import { MouseButtonEvent, Node as OgmaNode } from '@linkurious/ogma';
...
const [clickedNode, setClickedNode] = useState<OgmaNode|null>(null);
const onMouseMove = ({ target }: MouseButtonEvent) => {
  setClickedNode((target && target.isNode) ? target : null);
}

<Ogma
  options={...}
  onReady={(ogma) => {
    ogma.events.on('click', onClick);
  }}
>
  <NodeStyle attributes={{ color: 'red', radius: 10 }} />
  <Popup
    position={() => clickedNode ? clickedNode.getPosition() : null}
  >
      <div>Popup content here!</div>
  </Popup>
</Ogma>

Usage

See the web/src/App.tsx file for a complete example.

const graph: Ogma.RawGraph = ...;
return <Ogma options={{ backgroundColor: '#9dc5bb'}} graph={graph}>

Custom components

You can (and should) create your own components to implement different behaviors. It's easy, you just need to use the useOgma hook to get access to the instance of Ogma.

import { useOgma } from '@linkurious/ogma-react';

export function MyComponent() {
  const ogma = useOgma();
  const onClick = useCallback(() => {
    ogma.getNodes([1,2,3,4]).setSelected(true);
  }, []);

  return (
    <div>
      <button onClick={onClick}>Select nodes 1, 2, 3, 4</button>
    </div>
  );
}

How to apply the layouts

It's unintuitive to implement the layouts as a React component declaratively. We suggest using custom components and hook to ogma events to apply the layouts.

components/LayoutService.tsx:

import { useEffect } from 'react';
import { useOgma } from '@linkurious/ogma-react';
export function LayoutService () {
  const ogma = useOgma(); // hook to get the ogma instance

  useEffect(() => {
    const onNodesAdded = () => {
      // apply your layout
    }
    ogma.events.on('addNodes', onNodesAdded);

    // cleanup
    return () => {
      ogma.events.off(onNodesAdded);
    };
  }, []);

  return null;
}

App.tsx:

import { LayoutService } from './components/LayoutService';

export default function App() {
  ... // retrive the graph here

  return (<Ogma options={options} graph={graph}>
    <LayoutService />
  </Ogma>);
}

How to load the graph

import { useState, useEffect } from 'react';
import { RawGraph } from '@linkurious/ogma';
import { Ogma } from '@linkurious/ogma-react';

export default function App () {
  const [isLoading, setIsLoading] = useState(true);
  const [graph, setGraph] = useState<RawGraph>();

  useEffect(() => {
    fetch('/graph.json')
      .then(res => res.json())
      .then(json => {
        setGraph(json);
        setIsLoading(false);
      });
  }, []);

  if (isLoading) return (<div>Loading...</div>);
  return (<Ogma graph={graph}/>);
}

Using the parsers:

import { useState, useEffect } from 'react';
import OgmaLib, { RawGraph } from '@linkurious/ogma';
import { Ogma } from '@linkurious/ogma-react';

export default function App () {
  const [isLoading, setIsLoading] = useState(true);
  const [graph, setGraph] = useState<RawGraph>();

  // using ogma parser to parse GEXF format
  useEffect(() => {
    fetch('/graph.gexf')
      .then(res => res.text())
      .then(gexf => OgmaLib.parse.gexf(gexf))
      .then(jsonGraph => {
        setGraph(jsonGraph);
        setIsLoading(false);
      });
  }, []);

  if (isLoading) return (<div>Loading...</div>);

  return (<Ogma graph={graph} />)
}

Components

• <Ogma />
• Styles:
  • <NodeStyle />
  • <EdgeStyle />
• Overlays:
  • <Popup />
  • <Tooltip />
  • <CanvasLayer />
  • <Layer />
  • <Overlay />
• Transformations:
  • <NodeGrouping />
  • <EdgeGrouping />
  • <NodeFilter />
  • <EdgeFilter />
  • <NeighborGeneration />
  • <NeighborMerging />
  • <NodeCollapsing />
• <Geo />

API

<Ogma />

Main visualisation component. You can use onReady or ref prop to get a reference to the Ogma instance.

Props

<NodeStyle />

Node style component.

Props

Example

<Ogma>
  <NodeStyle attributes={{ color: "red", radius: 10 }} />
</Ogma>

<EdgeStyle />

Edge style component.

Props

Example

<Ogma>
  <EdgeStyle attributes={{ color: "red" }} />
</Ogma>

<Popup />

Custom popup UI layer.

Props

Example

<Ogma>
  <Popup
    position={() => (clickedNode ? clickedNode.getPosition() : null)}
    size={{ width: 200, height: 200 }}
  >
    <div>Popup content here!</div>
  </Popup>
</Ogma>

<Tooltip />

Tooltip component. Use it for cutom movable tooltips. It automatically adjusts the placement of the tooltip to conainer bounds.

Props

Example

<Ogma>
  <Tooltip
    visible={hoveredNode}
    position={() => (hoveredNode ? hoveredNode.getPosition() : null)}
    size={{ width: 200, height: 200 }}
  >
    <div>Tooltip content here!</div>
  </Tooltip>
</Ogma>

<CanvasLayer />

Custom canvas layer.

Props

Example

<Ogma>
  <CanvasLayer
    render={(ctx) => {
      ctx.fillStyle = 'red';
      ctx.fillRect(0, 0, 100, 100);
    }}
  />
</Ogma>

<Layer />

Generic DOM layer, see ogma.layers.addLayer.

Props

Example

<Ogma>
  <Layer>
    <span>Layer content here!</span>
  </Layer>
</Ogma>

<Overlay />

Generic Overlay layer, see ogma.layers.addOverlay.

Props

Example

<Ogma>
  <Overlay position={{x: 0, y: 0}} >
    <span>Layer content here!</span>
  </Overlay>
</Ogma>

Transformations

All transformations have callback props, making it easy to react to events related to transformations. | Prop | Type | Default | Description | | ------------ | ------------------------------ | ------- | ----------- | | onEnabled | (t: Transformation) => void | null | Triggered when transformation is enabled | | onUpdated | (t: Transformation) => void | null | Triggered when transformation is refreshed | | onDisabled | (t: Transformation) => void | null | Triggered when transformation is disabled | | onDestroyed| (t: Transformation) => void | null | Triggered when transformation is destroyed | | onSetIndex | (t: Transformation, i: number) => void | null | Triggered when transformation changes index |

<NodeGrouping />

Node grouping transformation. See ogma.transformations.addNodeGrouping() for more details.

Props

Example

<Ogma graph={...}>
  <NodeGrouping
    selector={node => node.getAttribute('type') === 'type1'}
    groupIdFunction={node => node.getAttribute('type')}
    disabled={false}
  />
</Ogma>

<EdgeGrouping />

Edge grouping transformation. See ogma.transformations.addEdgeGrouping() for more information.

Props

Example

<Ogma graph={...}>
  <EdgeGrouping
    selector={edge => edge.getAttribute('type') === 'type1'}
    groupIdFunction={edge => edge.getAttribute('type')}
    disabled={false}
  />
</Ogma>

<NodeFilter />

Node filter transformation. See ogma.transformations.addNodeFilter() for more information.

Props

Example

<Ogma graph={...}>
  <NodeFilter
    criteria={node => node.getData('age') > 22}
    disabled={false}
  />
</Ogma>

<EdgeFilter />

Wrapper for the edge filter transformation. See ogma.transformations.addEdgeFilter() for more information.

Props

Example

<Ogma graph={...}>
  <EdgeFilter
    criteria={edge => edge.getData('type') === 'important'}
    disabled={false}
  />
</Ogma>

<NeighborMerging />

Neighbor merging transformation. See ogma.transformations.addNeighborMerging() for more information.

Props

Example

<Ogma graph={...}>
  <NeighborMerging
    selector={node => node.getAttribute('type') === 'type1'}
    dataFunction={node => ({
      type: node.getAttribute('type'),
      label: node.getAttribute('label'),
    })}
    disabled={false}
  />
</Ogma>

<NeighborGeneration />

Neighbor generation transformation. See ogma.transformations.addNeighborGeneration() for more information.

Props

Example

<Ogma graph={...}>
  <NeighborGeneration
    selector={node => node.getAttribute('type') === 'type1'}
    neighborIdFunction={node => node.getAttribute('type')}
    disabled={false}
  />
</Ogma>

<NodeCollapsing />

Node collapsing transformation. See ogma.transformations.addNodeCollapsing() for more information.

Props

<Geo />

Geo mode component. It's the first version of this component and we are still gathering feedback on how you can use it.

Props

Example

<Ogma graph={...}>
  <Geo
    enabled={true}
    tileUrlTemplate="https://{s}.tile.osm.org/{z}/{x}/{y}.png"
    longitudePath="data.lng"
    latitudePath="data.lat"
  />
</Ogma>

License

Apache 2.0