At Cambridge Intelligence, we make KeyLines – a JavaScript SDK for interactive graph visualization. It’s ideal for hands-on Neo4j developers, offering the same power, scalability and flexibility for which the world’s most popular graph database has become known.
Since 2012, hundreds of developers have used KeyLines to build visualization web applications for Neo4j. As a result, we’ve honed our integration code, documentation, and support to make the process as simple as possible.
Build from scratch or use a template
As KeyLines is an SDK, there are limitless ways to customize your application. You have complete control over every aspect – UI, UX, functionality, visual appearance and branding. The most common approach is to use KeyLines’ API to harness functionality like the time bar, combos, SNA, and geospatial visualization. For that, more advanced JavaScript developers can follow our KeyLines & Neo4j integration tutorial.
In this post we’ll describe the quickest and easiest way to get started, using one of our Neo4j demos to kick-start the process. With this approach, we’ll use KeyLines’ Cypher integration and a one-to-one mapping between Neo4j and the chart, so switching the schema and producing your own visualization is fast and simple. Let’s begin.
A few prerequisites…To follow this tutorial, you’ll need:
- a KeyLines SDK login (Not using KeyLines yet? Request a free trial)
- a Neo4j instance, loaded with some data
- basic knowledge of JavaScript and web applications
The visualization architecture
The KeyLines-Neo4j architecture is simple but secure and flexible enough to work in any setup:
KeyLines itself is a JavaScript file, deployed to a web server. The KeyLines chart is then embedded as an HTML element somewhere within your application (or as a standalone component) which allows the user to interact with and explore, the graph.
Graphics rendering is powered by HTML5 Canvas or WebGL – KeyLines will switch between the two depending on the browser – so it performs well even with larger graphs. Also, everything stays inside your corporate firewall so data security shouldn’t be an issue.
Step 1: Download resources from the KeyLines SDK
Once you’re in the KeyLines SDK, take a few minutes to look around the site and check out the Demos tab. Here you’ll find a gallery of KeyLines examples to give you inspiration for your own applications:
The Integrate with Neo4j demo uses Cypher queries and KeyLines’ incremental layout to explore a Neo4j dataset of movies and actors (appropriately starting from The Matrix). To the right of the KeyLines chart, the handy panel contains details of the Cypher queries being raised, and some UI to run layouts from the KeyLines API.
Now click the SDK’s Documentation tab. Once you’re comfortable with the information in the Basics section, head to the Third Party Integrations > Neo4j page. Here you’ll find a more advanced Neo4j third-party integration tutorial complete with example Neo4j source files. Download the Neo4j demo files and, if you haven’t downloaded it already, the latest version of KeyLines.
Finally, move the downloaded keylines.tgz file into the Neo4j folder. At the console, to add KeyLines as a package dependency, run:
npm add file:./keylines-X.XX.X-XXXXXXXXXX_dev.tgz
Step 2: Run the Neo4j demo locally
The downloaded Neo4j folder contains some important items:
- css (as you’d expect) contains the different CSS files for the rest of your webpage. You can use ours, or write your own.
- images contains the image files for nodes, glyphs, etc.
- neo4j-data contains the files used to import the demo database
- neo4j-db.js is the database driver, including Cypher integration and JSON parsing code.
- neo4j-router.js controls the authentication parameters used.
- neo4j.js adds KeyLines functionality, as well as tying some of that functionality to general UI (e.g. run a layout when the user clicks on this button).
To get the Neo4j demo running locally, open ‘index.htm‘ in your preferred browser. You should see something like this:
At this point, the demo is running from our local filesystem. The chart is blank because we haven’t connected it to our database yet.
Step 3: Point the demo at your Neo4j database
In your ‘demo’ folder, find the neo4j-db.js file and add your instance login credentials to the following:
headers: { Authorization: 'Basic '+btoa('username:password') },
Obviously, this approach is only recommended during KeyLines prototyping. When you deploy your app in production, you’ll run Neo4j on a secure web server and only expose certain endpoints to KeyLines.
Using Bolt?
In this example, we’ve assumed you’re using Neo4j’s REST API to send queries back and forth. If you’re using Neo4j’s Bolt protocol, you’ll need to make some adjustments to the KeyLines demo at this stage:
- Set up the JavaScript Bolt library – either in your browser (using the browser version of the Neo4j driver) or on your server (for example by requiring Neo4j-driver in Node)
- Set up the driver – by adding your credentials and creating sessions to run KeyLines’ Cypher queries
- Process the Bolt response into KeyLines JSON – in a single loop you can: a) convert the node IDs, b) do the same for link/edge start and endpoints, c) convert other numeric properties.
More detailed instructions can be found in our blog post on Hooking KeyLines up to the Neo4j Bolt Protocol.
Step 4: Update the schema
Next you need to map your Neo4j data to the KeyLines schema, and choose the visual model you want to use.
This stage can be as simple or as complex as you like, but our Neo4j demo uses one-to-one mapping between the chart and database, and follows a typical user workflow (expand and explore). For most developers, a few simple ‘find and replace’ commands should do the trick.
For example, open neo4j-db.js, find ‘e: item.d.type === ‘movie’ ? 1.7 : 2.5’, which enlarges movie nodes in our demo, and replace movie with whichever node type from your schema you want represented as a larger size.
You’ll also need to adjust the Cypher queries in-line with your own schema. That’s in the queryTemplates object in neo4j-db.js.
Finally, you can also change node and link styles at this stage, for example by finding the ‘dbDemoTheme’ object in neo4j.js and changing the font icons by editing the ‘fi’ property.
Step 5: Run the Neo4j demo
The final step is to start your database and load KeyLines. If you’re using Node, that’s a simple `npm install` followed by `npm start` in the root folder.
Now navigate to http://localhost:8080 to find your interactive KeyLines – Neo4j demo:
Optional step 6: incorporate advanced functionality
By now, you’ll have a simple demo, running from your database with your own visual styling. It’s a great starting point for you to visually explore and understand your Neo4j data.
But if you want to take your insight a step further, the KeyLines API offers a huge library of advanced graph analysis and visualization functionality. With a few lines of JavaScript code (take a look at our 80+ demos for inspiration) you can incorporate graph layouts, SNA centrality measures, advanced filtering, and our ‘combos’ node combining functionality.
Try it for yourself
This tutorial is just the starting point. KeyLines and Neo4j are a powerful combination, and make it easy for you to build custom, flexible and high-performance graph exploration tools.