Using KeyLines with Vue

Step 2: Add KeyLines to the app

Download the KeyLines package from the link below and move it to the my-vue-app directory.

In the terminal from my-vue-app, add KeyLines as a package dependency:

npm install file:./keylines-8.6.0-11643712880.tgz

yarn add ./keylines-8.6.0-11643712880.tgz

pnpm install file:./keylines-8.6.0-11643712880.tgz

Next, you need to copy the file that contains Vue-style declarations of KeyLines components into your Vue application.

Run the following command from inside the my-vue-app directory to copy the file to the correct location:

cp -R ./node_modules/keylines/vue/ ./src/components

Step 3: Create a chart

Now let's set up a Vue component to create a chart. We will do this in the src/App.vue file.

The App.vue is a Single-File Component (SFC), which means that it contains code for a template, logic, and styling of a Vue component all together:

• Inside the <template> tag - The UI markup in HTML
• Inside the <script> tag - The component's logic in JavaScript
• Inside the <style> tag - The component's styles in CSS

First, replace the existing <template> tag.

The new tag specifies:

• the id of the KeyLines component's parent HTML element,
• the containerClass with the CSS class of the component's container div,
• the data object loaded into the component,
• the kl-ready event which receives the klReady function with a reference to the chart and will be fired when the component is ready:

<template>
  <kl-chart id='kl' containerClass='klchart' :data='data' @kl-ready='klReady'/>
</template>

Then replace the existing <script> tag with one that imports the KeyLines chart component and adds a simple KeyLines chart:

<script>
  import KlChart from './components/Chart.vue';     // imports the KeyLines chart component

  export default {
    name: 'app',
    components: { KlChart },
    methods: {
      klReady(chart) {          // A function called when the KeyLines component is ready to use
        this.chart = chart;     // that calls any other API functions on the component object
      },
    },

    data() {
      return {
        data: {
          type: 'LinkChart',     // A KeyLines Chart type - must be 'LinkChart'
          items: [{
            id: 'node1',
            type: 'node',
            t: 'Hello World',    // node text label
            c: '#43976C'         // node colour
          }],
        },
      }
    }
  }
</script>

And finally replace the existing <style> tag to set the dimensions for the KeyLines chart:

<style>
  #app {
    height: 100vh;
    width: 100vw;
    box-sizing: border-box;
    margin: 0;
    display: block;
    padding: 0;
    max-width: none;
  }
 
  *, *:before, *:after {
    box-sizing: inherit;
  }
 
  body {
    margin: 0;
  }
  
  .klchart {
    width: 100%;
    height: 100%;
  }
</style>

Once the chart component is created, the chart data property containing a node with a green colour (c property) and a text label (t property) is loaded and laid out with the default layout.

Then, the kl-ready event is fired which calls the klReady function with a reference to the chart. Finally, the klReady function saves the chart reference.

The default layout is the organic layout, which is a versatile force-directed layout algorithm that is especially great for large datasets and complex networks, but there are also other layouts you can explore.

When you reload the page, there should be no errors in your developer console or in your application and you should see a simple KeyLines chart in your browser:

Charts have a range of native options such as navigation to pan and zoom or overview window icon at the bottom right corner to toggle a chart overview.

Step 7: Add event handling

In this step, let's add some code to respond when the user clicks an item on the chart.

KeyLines lets you respond to virtually any user event on the chart using chart events.

Add a click handler in the methods object:

clickHandler({ id }) {
  console.log(`you clicked on ${id}`);
},

And then update the <template> tag to bind the kl-click event to the clickHandler function:

<template>
  <KlChart id='kl' containerClass='klchart' :data='data' :options='chartOptions' @kl-ready='klReady' @kl-click='clickHandler'/>
</template>

Reload the page and try clicking chart items, navigation controls or the chart background. In the developer tools console you'll see that a string containing the id of the clicked item or navigation control is passed to the click handler, or null if you click on the chart background.

Step 8: Add foregrounding on selection

Now let's set a foregrounding behaviour that highlights the user-selected item and its immediate neighbours, which is particularly helpful for large charts with densely connected nodes. Add a selectionHandler function responding to a kl-selection-change event after the clickHandler:

selectionHandler() {
  const itemIds = this.chart.selection();
  const selectedItems = this.chart.getItem(itemIds); // Ensure we have clicked on a link or node, not the navigation control
  if (selectedItems.length) {
    const neighbours = this.chart.graph().neighbours(itemIds); // Foreground the selected item and its neighbours
    this.chart.foreground(
      (item) =>
        itemIds.includes(item.id) || neighbours.nodes.includes(item.id)
    );
  } else {
    // Clicked on background - restore all items to the foreground
    this.chart.foreground(() => true);
  }
},

And then update the <template> tag to bind the kl-selection-change event to the selectionHandler function:

<template>
  <KlChart id='kl' containerClass='klchart' :data='data' :options='chartOptions' @kl-ready='klReady' @kl-click='clickHandler' @kl-selection-change='selectionHandler'/>
</template>

Reload the page and click items in the chart.

The selectionHandler function uses chart.getItem to check whether the clicked id belongs to a node or a link in the chart. If it does, then we use chart.graph().neighbours() to find the nodes connected to the clicked item, and then call chart.foreground() to put them in the foreground, and other chart items in the background.

If the user clicked on something else, such as the chart background, then we foreground all the chart items.