Create a Custom Neo4j Browser Guide

Introduction

With version Neo4j 2.3 we introduced the ability to run custom "slide-shows" in the Neo4j Browser, similar to the existing :play movie graph.

The idea behind these guides is, that you can provide a guided tour to a data set or use-case. Your users can interactively read through the slide-show, execute statements to import or query the data or look at pictures, videos or other media for detailed explanations.

We use these guides ourselves in many areas:

Online and classroom training
Neo4j Sandbox
Meetups and presentations
Exploration of interesting datasets, like TrumpWorld :play http://guides.neo4j.com/trumpworld
Rendering GraphGists as Guides

Others have used them too, here a few examples:

The Panama Papers Download comes with a comprehensive guide
Rik van Bruggens Beer Graph
Daniel Himmelsteins Protein Networks (Hetnet)
Will Lyons Game of Thrones Graph: :play http://guides.neo4j.com/got
GraphCommons Graphs

Technical Background

Those guides are simple HTML pages with a section per slide. Your users can interactively read through the slide-show, 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 classes that trigger actions within Neo4j Browser, e.g. for :play or :help commands.

Since Neo4j 3.1 it is also possible to provide form-fields whose input is automatically included in the query text.

The guides can be hosted anywhere, for security reasons you have to whitelist any domain besides http://guides.neo4j.com in your $NEO4J_HOME/conf/neo4j.conf.

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

Your server has to support proper CORS headers for both GET and OPTIONS requests, so unfortunately GitHub pages and Dropbox folders don’t work, but s3 works well enough (or a custom Python or Java webserver).

Warning

For security reasons Javascript and Angular tags are stripped from the HTML, even from whitelisted sources.

Warning

If your Neo4j instance is access over a 'https://' URL, only guides hosted on 'https://' URLs will render. Currently, as of 14-Mar-2017, guides.neo4j.com does not support 'https'.

Slide Format and Creation

The HTML format is described in detail here, but don’t despair, you don’t 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), our [GraphGists] but also Readme’s and Wiki’s on GitHub. It was developed for technical documentation, and is more powerful than Markdown. You can find a basic syntax overview here.

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

Our process is very easy, we just get or create a simple AsciiDoc file, for deep details on the AsciiDoc syntax, please see the AsciiDoctor User Manual

Concrete Example

Clone and enter this 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://s3.amazonaws.com/dev.assets.neo4j.com/wp-content/uploads/neo4j_logo-325x150.png[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='key'>Help Keys</a>]
* pass:a[<a play-topic='http://guides.neo4j.com/'>Another Guide</a>]

image::http://example.com/guides/img/logo.png[width=100,link="http://example.com"]

And then run it through the run.sh script to convert it 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

# then upload the file to your target server, e.g.

s3cmd put -P html/test.html s3://guides.neo4j.com/test

Introduction

idea
built in guides
capabilities
format
hosting
whitelist
auto-play command
url-param cmd=play&args=

Creating Process

AsciiDoc to Guide
- 2nd level header to slide
- cypher code blocks
- tables, bullets, images
- javascript / angular attributes are stripped from the HTML source
- iframes are possible
- automatic form fields
neo4j-guides repository

Guide from GDOC

Create a google doc with asciidoc content for collaborative editing Make it publicly readable (with link) Use the "Download as Plain Text URL"

gdoc2-guide.sh

name=${1-network}
url='https://docs.google.com/a/neotechnology.com/document/export?format=txt&id=1HY3AX6dvd8UtJhp5XAsyFsQ0oyC6Z0pbwJvkyr4WHtM&token=AC4w5Vjb20_Xmpe6awpuDyYGC5UO5egnEA%3A1488965039896'

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