Goals This guide explains how to create an educational guide (slideshow) for the Neo4j browser, that enables your audience to explore your database and model interactively. Prerequisites You should have a good understanding of Cypher and the Neo4j Browser and… Read more →
This guide explains how to create an educational guide (slideshow) for the Neo4j browser, that enables your audience to explore your database and model interactively.
You should have a good understanding of Cypher and the Neo4j Browser and graph data modeling for your domain. It’s beneficial if you previously created a GraphGist. Web development experience helps in creating compelling guides.
In Neo4j 2.3 we introduced the ability to run custom “slideshows” in the Neo4j Browser, similar to the existing
:play movie graph.
These guides allow to provide a guided tour to a data set or use case. Your users can interactively read through the slideshow, execute statements to import or query the data or look at pictures, videos or other media for detailed explanations. You can also inlcude special links for interacting with the Neo4j browser.
We use these guides ourselves in many areas:
Others have used them too, here a few examples:
The browser guides are simple HTML pages with one section per slide.
The users can interactively page through the slideshow, execute statements from
<pre/> areas to import or query the data or look at pictures, videos or other media for detailed explanations.
Of course you can use other HTML elements like tables, bullets, links etc.
There are some special CSS classes that interact actions within Neo4j Browser, e.g. for
Since Neo4j 3.1 it is also possible to provide form-fields within the guides whose input is automatically included in the text on slides and in statements.
This is similar to the built-in
:play query template
The guides can be hosted anywhere, for security reasons you have to whitelist any domain besides
localhost in your
The server hosting the guide has to support proper CORS headers for both GET and OPTIONS requests, because the Neo4j Browser accesses a foreign URL. So unfortunately GitHub pages and Dropbox folders don’t work, but S3 can be configured to work well enough (or a custom Python or Java webserver).
If your Neo4j instance is accessed via a
You can also provide your guide as a startup URL in two ways:
Slide Format and Creation
The HTML format is described in detail here. Don’t worry, you do not have to create the HTML manually. Although you can fine tune the generated HTML from the next step afterwards.
To make it easier to create Browser Guides, we created a simple tooling repository that uses AsciiDoc as source format and a HTML template with the slide structure.
AsciiDoc is used in many places, e.g. for O’Reilly books, many Documentation Manuals (ours too), these developer pages, our knowledge base, GraphGists but also in Readme’s and Wiki’s on GitHub. It was developed for technical documentation, and is more powerful than Markdown.
You can find a simple syntax overview here.
Our process is straightforward.
- Just find or create a simple AsciiDoc file (see below) and convert it to the slide-html.
Each second-level header is turned into a new slide, and
[source,cypher]blocks into clickable statements.
- Otherwise all regular HTML transformations apply.
- For deep details on the AsciiDoc syntax, please see the AsciiDoctor User Manual
Clone and enter our repository and start editing your first guide.
After saving the file, pass it to the
run.sh script to convert to the HTML slides.
Test in your local browser:
And test it again:
Guide from GDOC
Something that is also really useful is to create guides from a collaboratively edited Google document.
Just create a Google document with AsciiDoc content (like the one above) for collaborative editing. Make it publicly readable – in sharing settings enable: “everyone with link can read”.
Get the download URL from “Download as Plain Text” and render to a browser guide like we did before.
The new Neo4j Sandbox uses Browser Guides to guide the user through the dataset presented.
Panama Papers Guide
The award winning investigative work around the Panama Papers leak by the journalists of the ICIJ is available as an online database.
It is also available as a Neo4j Panama Papers Sandbox with a comprehensive browser guide to explore the vast network of shell company connections.
The GraphGist Portal allows any GraphGist to be viewed as a browser guide.
Just click the “Run this gist in the Neo4j console” link on the right hand sidebar, e.g.
|You need to whitelist the source hostname.|
Beer Graph Guide – Rik Van Bruggen
Rik van Bruggen demonstrates in detail how to turn a data set or GraphGist into a proper Browser Guide.
HetNet Protein Networks – Daniel Himmelstein
Daniel used Browser Guides to represent the topic of his PhD thesis – Protein Networks in a Graph Database.
He details the process of setting up a public server for hosting the dataset as well as the steps involved in creating the guides in this article.
Daniel also presented about his research at GraphConnect San Francisco.
Game of Thrones Guide
After the mathematicians Andrew Beveridge and Jie Shan published the “Network of Thrones” reseearch paper, William Lyon took the data (with permission) of co-occurrence of characters in volume 3 of “Game of Thrones” and turned it into a Neo4j Graph database.
Using that popular dataset Will explains the basic workings of a graph database and then expands into data science with social network analysis and graph algorithms.
The guide turns Wills blog post into an interactive experience.
We also created a separate “Game of Thrones” guide that aims at recreating the whole universe using data from a variety of sources. It uses this set of accompanying slides to teach about Neo4j.
Also you’ve probably seen it, Graph Commons supports the Neo4j browser, play the URL in the Neo4j browser (note the
/neo4j at the end):
|You need to whitelist the source.|