Skip to content

Instantly share code, notes, and snippets.

@jexp

jexp/guide-create-neo4j-browser-guide.adoc

Last active March 2, 2023 15:33
Show Gist options
  • Save jexp/1abaa155d214569e458e0770e2cab2e3 to your computer and use it in GitHub Desktop.
Save jexp/1abaa155d214569e458e0770e2cab2e3 to your computer and use it in GitHub Desktop.
Download ZIP
Create a Custom Neo4j Browser Guide
Raw
guide-create-neo4j-browser-guide.adoc

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:

Others have used them too, here a few examples:

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://myguides.example.com/

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 its erb-HTML5 templates.

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

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

AsciiDoc to Guide

Guide Generator ADOC→ Guides https://github.com/neo4j-contrib/neo4j-guides

Guide from GDOC

Create a google document with AsciiDoc content for collaborative editing. Make it publicly readable - "everyone with link can read". Get the file / URL from "Download as Plain Text" and render to a Guide like we did before.

gdoc2guide.sh
id=${1-"1HY3AX6dvd8UtJhp5XAsyFsQ0oyC6Z0pbwJvkyr4WHtM"}
name=${2-network}
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

Beer Graph Guide - Rik Van Bruggen

TODO picture / video

Rik van Bruggen demonstrates in detail how to turn a data set or GraphGist into a proper 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.

Twitter

TODO link to network / sandbox

:play http://guides.neo4j.com/twitter-neo4j/

Twitter Election Graph :play http://guides.neo4j.com/twitterElection/

Exploring Shipping Data

Graphs in Data Journalism:

Graphs in Data Journalism: :play http://guides.neo4j.com/ddj/

Field

Game of Thrones Guide Will Lyon:

TODO text, link to blog posts, link to trumpworld-graph repo

:play http://guides.neo4j.com/got/
:play http://guides.neo4j.com/got_wwc/

Trumpworld:

TODO text, link to blog posts, link to trumpworld-graph repo

:play http://guides.neo4j.com/trumpworld-simple/
:play http://guides.neo4j.com/trumpworld/
:play http://guides.neo4j.com/trump_wwc
:play http://guides.neo4j.com/trumpworld
:play http://guides.neo4j.com/trumpworld-simple/
:play http://guides.neo4j.com/trumpworld/

Legis Graph:

TODO blog posts / repo

:play http://guides.neo4j.com/legisgraph/
:play http://guides.neo4j.com/legisgraphalgo/

Short Term Rental Listings (AirBNB)

:play http://guides.neo4j.com/listings/

RDF

TODO link / url

Panama papers guide

TODO blog post / screen shot

:play http://cloudfront-files-1.publicintegrity.org/offshoreleaks/neo4j/guide/index.html
Note
 Need to whitelist source. 
browser.remote_content_hostname_whitelist=http://cloudfront-files-1.publicintegrity.org

GraphGists

GraphGist Portal allows any GraphGist to be viewed as a Guide.

"Run this gist in the Neo4j console"
:play http://portal.graphgist.org/graph_gists/trumpworld-graph/graph_guide
Note
 Need to whitelist source. 
browser.remote_content_hostname_whitelist=http://portal.graphgist.org

Select GraphGists: :play http://guides.neo4j.com/graphgists/

Graph-Commons

https://twitter.com/graphcommons/status/815999498245853185 Also you’ve probably seen it, Graph Commons supports the Neo4j browser, you can simply type this below in the Neo4j browser (notice the /neo4j at the end): :play https://graphcommons.com/graphs/1a93e8fa-e3ce-4ec7-ba16-814b867d1bcb/neo4j

Note
 Need to whitelist source. 
browser.remote_content_hostname_whitelist=https://graphcommons.com/graphs/
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment