Using KeyLines with Angular

Contents

• Introduction
• Step 1: Create and serve an Angular app
• Step 2: Add KeyLines to the app
• Step 3: Create a chart
• Step 4: Add and parse the data
• Step 5: Add details with styling
• Step 6: Customise the chart options
• Step 7: Add event handling
• Step 8: Add foregrounding on selection
• Next steps

Introduction

This start guide shows how to create an Angular application with a KeyLines chart.

For more information about integrating KeyLines with Angular, see also the Angular Integration demo and Angular Reference documentation.

Note that if you store KeyLines in your source control, you must ensure it's not publicly available. Read more about the Obfuscation Requirements before deploying your application.

Step 1: Create and serve an Angular app

If you already have an existing project with non-standalone components up and running, you can skip this step and continue adding KeyLines from Step 2, replacing my‑angular‑app with the name of your project's root directory and integrating the example code into your application code.

To start a new project, run these commands in the console to create the app:

npm install -g @angular/cli@v17
ng new my-angular-app --no-standalone
cd my-angular-app
ng serve --open

yarn global add @angular/cli@v17
ng new my-angular-app --no-standalone
cd my-angular-app
ng serve --open

pnpm install -g @angular/cli@v17
ng new my-angular-app --no-standalone
cd my-angular-app
ng serve --open

If you are prompted about any settings while the commands are running, you can accept the default values for now.

This process might take a while to run. You should now see a simple Angular app in your browser. In case of problems, see the Angular CLI documentation.

Step 4: Add and parse the data

In app.component.ts, replace the existing data object inside the AppComponent class with this data:

data: Data = {
  person: [
    { name: 'Jenny', teamId: 1 },
    { name: 'Rosie', teamId: 0 },
    { name: 'Peter', teamId: 0 },
    { name: 'Sam', teamId: 1 },
  ],
  messages: [
    { from: 'Jenny', to: 'Sam', amount: 17 },
    { from: 'Sam', to: 'Jenny', amount: 12 },
    { from: 'Sam', to: 'Peter', amount: 1 },
    { from: 'Rosie', to: 'Jenny', amount: 2 },
    { from: 'Peter', to: 'Rosie', amount: 7 },
  ],
};

This dataset details messages between two teams of people.

We need to define types for this data. We will define them in the same file, although typically these would be in a separate file. Add the types just after imports at the top:

type Data = {
  person: { name: string; teamId: number }[];
  messages: { from: string; to: string; amount: number }[];
};

KeyLines accepts a ChartData object, which defines an array of chart items and their attributes. This means that we will need to parse our raw data to a KeyLines chart object. This is how we've defined our data model:

• People are represented by nodes. Nodes require a type: 'node' and a unique id. The default node colour is transparent, so we will also set the c property.
• Messages between people are represented as links. Links require a type: 'link', a unique id, and id1 and id2 properties whose values are ids of nodes at each link end.

To parse the data, add this function inside the AppComponent class:

parseData(data: Data): ChartData {
  const items: Array<Node | Link> = [];
  data.person.forEach(({ name }) => {         // defines people as nodes
    items.push({
      id: name,
      type: 'node',
      c: '#43976C',
    });
  });
  data.messages.forEach(({ from, to }) => {   // defines messages as links
    items.push({
      type: 'link',
      id: `link_${from}_${to}`,
      id1: from,
      id2: to,
    });
  });
  return { type: 'LinkChart', items };        // adds 'LinkChart' required by KeyLines
}

At the top of the file, update the list of imported KeyLines TypeScript types to contain the new types Node and Link:

import type { Chart, ChartData, Node, Link } from 'keylines/esm';

And finally, update the klReady function at the bottom of the file:

klReady([chart]: [Chart]) {                     // A function to run when the page is ready for the chart
  this.chart = chart;                           // saves the chart reference
  this.chart.load(this.parseData(this.data));   // loads the data into the chart
  this.chart.layout();                          // runs the default organic layout
}

Your application and developer console should now be clear of any errors and you should see this network in the browser:

Our data model is now visualised as nodes and links, but it's difficult to distinguish the individual items on the chart. To address this, we will incorporate details as styling in the next step.

Step 5: Add details with styling

KeyLines offers a variety of styling options for nodes and links. In our chart, we will use node and link styling as a way of showing item metadata.

To style the nodes, we will:

• Use the c property to set a different colour for each team
• Use the t property to add a text label and style it

To do this, update the first part of the parseData function where we have defined the people as nodes:

data.person.forEach(({ name, teamId }) => {
  items.push({
    id: name,
    type: 'node',
    c: [ '#43976C','#ff6f61' ][teamId],    // node colour by team
    t: { fbc: 'transparent', fs: 'auto', fc: 'white', t: name },    // white backgroundless text sized to fit the node
  });
});

To style the links, we will:

• Use the w property to scale the link widths based on the number of messages sent
• Use the a2 property to set a direction arrow that identifies the direction of the communication

To do this, update the second part of the parseData function where we have defined the messages as links:

data.messages.forEach(({ from, to, amount }) => {
  items.push({
    type: 'link',
    id1: from,
    id2: to,
    id: `link_${from}_${to}`,
    a2: true,    // arrow pointing to the recipient
    w: Math.pow(amount, 0.8)    // link width scalable by amount to the power of 0.8
  });
});

The chart now reveals which individuals belong to a specific group (team) and the strength of the relationship between the individuals (the amount of communication).

Step 6: Customise the chart options

Now let's customise some chart options. The chart options APIs can be used to change styling, display and interaction defaults of the chart as an element that integrates into your application.

Still in app.component.ts, add this object inside the AppComponent class:

chartOptions: ChartOptions = {
  selectedNode: { ha0: { c: "#f5bd1f", r: 37, w: 8 } },    // creates a halo around selected node 
  controlTheme: 'dark' ,    // turns navigation controls and overview window to dark mode
  backColour: '#1b2327',    // a background colour
};

Then update the list of imported KeyLines TypeScript types at the top of the page to contain the new type ChartOptions:

import type { Chart, ChartData, Node, Link, ChartOptions } from 'keylines/esm';

And in src/app/app.component.html, update the kl-component to include the klOptions object that will override the default component options with your new options:

<kl-components (klReady)='klReady($event)'>
  <kl-component klType='chart'
  klContainerClass='chart-container'
  [klOptions]='chartOptions'> <!-- object with options that override the default component options -->
  </kl-component>
</kl-components>

The klOptions object must be wrapped in [ ] punctuation as a data type that flows from source to view. See Types of Data Binding in the Angular documentation.

The resulting chart now looks like this when the 'Peter' node is selected: