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 →

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 graph data modeling for your domain. It’s beneficial if you previously created a GraphGist. Web development experience helps in creating compelling guides.
intermediate


Introduction

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:

browser guide northwind

Others have used them too, here a few examples:

Technical Background

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 :play or :help commands.

browser guide form fields

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 guides.neo4j.com and localhost in your $NEO4J_HOME/conf/neo4j.conf.

# comma separated list of base-urls, or * for everything
browser.remote_content_hostname_whitelist=http://example.com

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).

For security reasons, Javascript and Angular tags are stripped from the HTML, even from whitelisted sources.
If your Neo4j instance is accessed via a https:// URL, only guides hosted on https:// URLs will render. Currently, as of April 2017, guides.neo4j.com does not support https.

You can also provide your guide as a startup URL in two ways:

add play command as setting in neo4j.conf
browser.post_connect_cmd=play <guide url or name>

browser.post_connect_cmd=play http://guides.neo4j.com/apoc
# or
browser.post_connect_cmd=play intro
use URL parameters in a link, like we do on this page
http://localhost:7474/browser?cmd=play&arg=<guide url or name>

http://localhost:7474/browser?cmd=play&arg=http://guides.neo4j.com/got

http://localhost:7474/browser?cmd=play&arg=northwind%20graph

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.

We use the AsciiDoctor toolchain and a variant of its HTML5 erb-templates.

Our process is straightforward.

  1. Just find or create a simple AsciiDoc file (see below) and convert it to the slide-html.
  2. Each second-level header is turned into a new slide, and [source,cypher] blocks into clickable statements.
  3. Otherwise all regular HTML transformations apply.
  4. For deep details on the AsciiDoc syntax, please see the AsciiDoctor User Manual

Worked Example

Clone and enter our repository and start editing your first guide.

git clone https://github.com/neo4j-contrib/neo4j-guides
cd neo4j-guides
edit adoc/test.adoc
test.adoc
= A Test Guide

== First Slide: Media

image::https://avatars3.githubusercontent.com/u/201120[width=200,float=right]

This is just a test guide.

But it comes with a picture and a video:

++++
<iframe width="560" height="315" src="https://www.youtube.com/embed/V7f2tGsNSck?showinfo=0&controls=2&autohide=1" frameborder="0" allowfullscreen></iframe>
++++

== Second Slide: Statements

=== Creating Data

The area below becomes a clickable statement.

[source,cypher]
----
CREATE (db:Database {name:"Neo4j"})
RETURN db
----

=== Querying Data
:name: pass:a['<span value-key="name">Neo4j</span>']

We use a form field here:

++++
<input style="display:inline;width:30%;" value-for="name" class="form-control" value="Neo4j" size="40">
++++

[source,cypher,subs=attributes]
----
MATCH (db:Database {name:{name}})
RETURN db
----

== Third Slide: Links

* http://neo4j.com/developer/cypher[Learn more about Cypher]
* pass:a[<a help-topic='keys'>Help Keys</a>]
* pass:a[<a play-topic='http://guides.neo4j.com/'>Another Guide</a>]

image::https://avatars3.githubusercontent.com/u/201120[width=100,link="http://example.com"]

After saving the file, pass it to the run.sh script to convert to the HTML slides.

./run.sh adoc/test.adoc html/test.html

# optional arguments, leveloffset - to change the heading level up or down, base-url and additional attributes
./run.sh path/to/test.adoc path/to/test.html [+1] http://example.com/guides/test

# run the local python server to serve on localhost:8001
python http-server.py

Test in your local browser: :play http://localhost:8001/html/test.html

# then upload the file to your target server, e.g.
s3cmd put -P html/test.html s3://guides.example.com/test

And test it again: :play http://guides.example.com/test

browser guide demo

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.

gdoc2guide.sh
id=${1-"1HY3AX6dvd8UtJhp5XAsyFsQ0oyC6Z0pbwJvkyr4WHtM"}
name=${2-network}
# use your plain-text download link format here
url="https://docs.google.com/a/neotechnology.com/document/export?format=txt&id=${id}"

curl -sL "$url" -o adoc/$name.adoc
./run.sh adoc/$name.adoc html/$name.html
s3cmd put -P html/$name.html s3://guides.neo4j.com/$name

Example Collection

Sandbox

The new Neo4j Sandbox uses Browser Guides to guide the user through the dataset presented.

browser guide sandbox

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.

browser guide panama papers

GraphGists

browser guide graphgist

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.
browser.remote_content_hostname_whitelist=http://portal.graphgist.org

And then chose any Graph Gist from the portal to render in your browser, or check out this selection: :play http://guides.neo4j.com/graphgists/

APOC

browser guide apoc

The APOC procedure library comes with a lot of useful functionality for Neo4j. For an “interactive” manual, some of the original documentation was turned into guides.

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.

216f2626 3966 11e6 8a0d 215f70b44be2

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.

Graph-Commons

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.
browser.remote_content_hostname_whitelist=https://graphcommons.com/graphs/

jQAssistant

The Software analytics tool, uses a guide to explore any scanned software project.