教程：创建自定义浏览器指南

重要 - 页面未维护

此页面不再维护，其内容可能已过时。有关最新指南，请访问 入门手册 。
目标
本指南说明如何为 Neo4j 浏览器创建演练（幻灯片格式），使您的受众能够交互式地浏览您的数据库和模型。
先决条件
您应该对 Cypher 和 Neo4j 浏览器 以及 图数据建模（针对您的领域）有很好的理解。其他有用的知识（虽然不是必需的）包括创建 GraphGist 以及熟悉 Web 用户体验。

中级

如果您熟悉 Neo4j 浏览器，则您可能已经使用过我们的交互式浏览器指南来学习概念、加载数据和浏览您的图。流行的 :play movie graph 浏览器指南就是一个例子。

这些指南可帮助您为连接到 Neo4j 的用户提供数据集或用例的引导游览。您的用户可以交互式地阅读幻灯片，执行语句以导入和查询数据，或查看图片和其他媒体以获取详细说明。您还可以包含用于与 Neo4j 浏览器交互的特殊链接。

浏览器指南有多种用途，从个人开发到与同事或其他开发人员共享知识。公司甚至可以使用这些作为员工的入职或培训工具。我们在许多领域自己使用这些指南，包括下面列出的那些。

  • Neo4j 沙箱 - 每个沙箱都带有一个内置的默认指南，以帮助您开始使用您选择的任何沙箱！

  • 在线和课堂培训 - 在课堂上使用这些已发布的指南，允许参与者以自己的节奏完成材料，并在课程结束后 24/7 访问指南。

  • 聚会和演示文稿 - 演示者可以将幻灯片与代码混合，以在舞台上获得更好的现场体验。

  • 有趣数据集的探索 - 将所有资源（数据模型、导入、查询）发布在一个地方，并在需要时参考该工作。

  • 将 GraphGists 呈现为指南 - 将 GraphGists 转换为浏览器指南允许您在开发环境中访问它们并在其中进行代码编写，而不仅仅是阅读。

示例 Northwind 数据集指南

browser guide northwind

以下是一些我们最喜欢的使用 Neo4j 浏览器指南的示例

技术背景

浏览器指南是简单的 HTML 页面，每个幻灯片一个部分。幻灯片的每个部分都包含在 <slide/> 标记中，用户可以交互式地翻页以查看内容。我们可以通过将语句放在 <pre/> 标记区域内来包含用户执行以导入或查询数据的语句。用于详细说明的图片和其他媒体包含在 <img/> 和其他媒体标记中。您可以使用其他标准 HTML 元素来包含表格、项目符号、链接等。有一些特殊的 CSS 类与 Neo4j 浏览器中的交互操作进行交互，例如用于 :play 或 :help 命令。

browser guide form fields

我们还可以使用指南中的表单字段来自动填充幻灯片上的文本和语句中的输入。这类似于内置的 :play query-template。

托管浏览器指南

指南可以托管在任何地方。出于安全原因，Neo4j 的标准配置设置为接受托管在 guides.neo4j.com 和 localhost 上的文件。但是，如果您想在其他地方托管指南，则需要在您的 $NEO4J_HOME/conf/neo4j.conf 中将其他域与默认白名单一起列入白名单，如下所示。

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

托管指南的服务器需要支持 GET 和 OPTIONS 请求的正确 CORS 标头，因为 Neo4j 浏览器访问的是外部 URL。这意味着 GitHub Pages 和 Dropbox 文件夹无法使用，但 Amazon S3（或自定义 Python 或 Java Web 服务器）可以配置为正常工作。

  1. 出于安全原因，即使来自白名单来源，Javascript 和 Angular 标记也会从 HTML 中剥离。

  2. 如果您的 Neo4j 实例通过 https:// URL 访问，则只有托管在 https:// URL 上的指南才会呈现。

您还可以通过两种方式设置指南以在浏览器启动时显示

1. 在 neo4j.conf 中添加 play 命令作为设置
browser.post_connect_cmd=:play test

浏览器将根据主机站点加上指南名称搜索指南 URL。例如，上面的配置设置将查找路径 https://guides.neo4j.com/test 上的指南。这也可以用于文件夹中的指南（即 https://guides.neo4j.com/folder/test）。
2. 在链接中使用 URL 参数打开浏览器并预填充到指南的命令
https://:7474/browser?cmd=play&arg=<guide url or name>

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

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

幻灯片格式和创建

HTML 格式 在此处详细描述。不用担心，您不必手动创建 HTML。但是，您可以在后续步骤中微调生成的 HTML。

为了更轻松地创建浏览器指南，我们创建了一个 简单的工具存储库，该存储库使用 AsciiDoc 作为源格式以及带有幻灯片结构的 HTML 模板。

AsciiDoc 在许多地方使用，包括 O'Reilly 图书、各种文档手册（例如我们的文档手册）、这些开发者页面、我们的 知识库、GraphGists，以及 GitHub 上的 Readme 和 Wiki 文件。它是为技术文档开发的，比 Markdown 更强大。

您可以在此处找到一个简单的 语法概述。

我们使用 AsciiDoctor 工具链及其 HTML5 erb-templates 的变体。

我们的过程很简单。

  1. 查找或创建一个简单的 AsciiDoc 文件（见下文），并将其转换为幻灯片 HTML。

  2. 将每个二级标题转换为一个新的幻灯片，并将 [source,cypher] 块转换为可点击的语句。

  3. 对其他内容遵循任何其他常规 HTML 转换。

  4. 有关 AsciiDoc 语法的更深入详细信息，请参阅 AsciiDoctor 用户手册。

工作示例

我们将简要介绍一个测试指南作为示例。稍后，您可以使用相同的步骤为您的材料创建自己的自定义指南。

  1. 克隆并打开指南存储库。

    git clone https://github.com/neo4j-contrib/neo4j-guides
#SSH command is `git clone git@github.com:neo4j-contrib/neo4j-guides.git`
cd neo4j-guides

  2. 找到 adoc 目录并在其中创建一个名为 test.adoc 的文件。

    custom guide test

  3. 将下面的内容插入到新创建的 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:

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

== Second Slide: Statements

=== Creating Data

The area below becomes a clickable statement.

[source,shell]
----
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

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

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

  4. 将 test.adoc 文件传递给 run.sh 脚本（如下所示）以转换为 HTML 幻灯片。

    ./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] https://example.com/guides/test

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

  5. 在本地浏览器中测试测试指南： :play https://:8001/html/test.html

  6. 将文件上传到目标服务器。

    #Example target server
s3cmd put -P html/test.html s3://guides.example.com/test

  7. 最后再测试一下指南：:play https://guides.example.com/test

    browser guide demo

恭喜！您已创建了自己的自定义浏览器指南，可以用来分享您关于 Neo4j 的知识，并且可以使用这些步骤创建其他有用的指南。

从 Google Docs 创建指南

另一个非常有用的功能是从协作编辑的 Google 文档创建指南。我们将简要说明如何操作。

您可以简单地创建一个包含 AsciiDoc 内容（如上所示）的 Google 文档以进行协作编辑。将其设置为公开可读 - 在共享设置中，启用：“任何拥有链接的人都可以查看”。

在文档中，选择文件，另存为 >，纯文本 (.txt)。

gdownload plaintxt

然后找到浏览器下载并复制 Google 文档下载的链接地址。

chrome downloads link address

像之前一样，将 Google 文档渲染为浏览器指南。下面显示了一个使用脚本的示例。

gdoc2guide.sh
#use the download id (not full link) to set the document id
id=${1-"1HY3AX6dvd8UtJhp5XAsyFsQ0oyC6Z0pbwJvkyr4WHtM"}
#choose a name for your guide
name=${2-network}

#use your full 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

示例集合

在本节中，我们将列出我们为用户创建的一些现有且最受欢迎的浏览器指南，供他们学习和探索 Neo4j。我们希望这些示例能展示您可以使用自定义指南执行的操作，并鼓励您与我们一起创建和发布更多指南。

此类资源可以帮助传播关于 Neo4j 的知识，以及它可以执行的不同类型操作和可以解决的问题。它还可以向其他人展示您如何构建图模型、导入数据集以及以图的形式探索这些数据。

要查看更多内置和社区浏览器指南，请查看开发者指南，以获取完整列表，了解哪些内容公开可用。

沙盒

sandbox use cases 2019

Neo4j 沙盒使用浏览器指南引导用户逐步了解为特定用例提供的数据集。这些指南在沙盒加载时显示，并显示数据集背景、模型、加载和查询的步骤。我们的一些沙盒甚至集成了扩展和其他工具，例如图算法、APOC 和 Bloom。

ICIJ 巴拿马文件指南

browser guide panama papers

围绕巴拿马文件泄密的屡获殊荣的调查工作由ICIJ的记者完成，他们使用 Neo4j 分析了数 TB 的非结构化和结构化数据。ICIJ 随后发布了对初始泄密的后续报道，包括天堂文件、离岸泄密和巴哈马泄密。

所有这些调查的数据都可以作为数据库下载获取。我们还在天堂文件上有一个沙盒，其中包含一个全面的浏览器指南，用于探索庞大的离岸网络。

GraphGist 门户

browser guide graphgist

如果您不熟悉我们的GraphGists，它们旨在作为 Neo4j 社区与他人分享其用例和图形的一种方式。我们的常规 GraphGists 发布在网页上，通常包含有关项目的信息，例如数据模型、示例查询和项目背景。这些页面还设计为交互式的，以便访问者可以在页面中执行查询并查看结果。

GraphGist 门户是 Neo4j 之外的独立网站，显示所有 GraphGists。该门户还提供了一些其他功能，最值得注意的是，它允许以浏览器指南的形式查看任何 GraphGist。

要将任何一个 GraphGist 作为浏览器指南启动，您只需点击顶部“GraphGists”选项卡中您感兴趣的 GraphGist，然后点击右侧边栏上的在 Neo4j 控制台中运行此 gist链接即可。这将弹出一个较小的窗口，其中包含:play命令，用于在 Neo4j Browser 中运行指南以及任何潜在的白名单设置。

您还可以执行此浏览器指南，该指南列出了一些要查看的 GraphGist 指南：:play https://guides.neo4j.com/graphgists/

内置培训指南

Neo4j 为 Neo4j 新手创建了一些入门指南，以向他们展示如何使用它。主题从了解什么是图到 Cypher，再到建模和导入，以下列出了相关链接。

指南名称 浏览器命令

Neo4j 浏览器简介

:play intro

Neo4j 概念

:play concepts

关于 Cypher

:play fundamentals

Cypher 入门

:play cypher

电影图

:play movie-graph

导入：关系到图

:play northwind-graph

数据建模：航班

:play modeling_airports

APOC

browser guide apoc

我们在上面提到过，一些 Neo4j 扩展和工具也包含浏览器指南。Neo4j 最受欢迎的库之一是APOC（Cypher 上的强大过程）。该项目包含大量有用的过程和函数，用于文本操作、图重构、数据导入等等。它也是我们Neo4j Labs项目的一部分。

APOC 的一些Github 文档内容被转换为指南，作为交互式手册。浏览器指南版本包括有关项目和如何安装 APOC 的背景信息，以及一些关键过程，用于加载不同类型的数据、转换日期以及处理批处理和后台操作。

啤酒图指南 - Rik Van Bruggen

Rik van Bruggen 在提供的链接中详细演示了如何将数据集或 GraphGist 转换为正确的浏览器指南。

HetNet 蛋白质网络 - Daniel Himmelstein

216f2626 3966 11e6 8a0d 215f70b44be2

Daniel 使用浏览器指南来表示其博士论文的主题 - 图数据库中的蛋白质网络。在这篇文章中，他详细介绍了设置用于托管数据集的公共服务器的过程，以及创建指南所涉及的步骤。Daniel 还在他的视频中介绍了他在 GraphConnect San Francisco 的研究。

权力的游戏角色互动 - Andrew Beveridge/Will Lyon

基于广受欢迎的权力的游戏书籍系列，数学家 Andrew Beveridge 和 Jie Shan 发布了“权力的游戏网络”研究论文，探讨了书籍中角色之间的互动。由于图数据库遵循网络科学的原理，Neo4j 的 Will Lyon 因此请求并获得了许可，将已发布的数据导入 Neo4j 以进行分析。

使用这个有趣且熟悉的数据集，Will 创建了一个博文，解释了如何将数据导入 Neo4j，然后扩展到社会网络分析和图算法的数据科学概念。从那时起，Andrew Beveridge 发布了现有书籍卷以及电视剧版本所有季的所有数据。

相关的“权力的游戏”浏览器指南借鉴了 Will 原博文的基石，但也介绍了Neo4j 图算法库。此库是 Neo4j 另一个受欢迎的扩展，其中包括用于路径查找、中心性、社区等等的算法。与APOC一样，图算法库也是Neo4j Labs的一部分。

我们还创建了一个独立的权力的游戏指南，旨在结合来自各种来源的更多宇宙数据。

Graph Commons

Graph Commons是一个创建和共享数据网络的网站，它有一个 Neo4j 示例，可以使用下面显示的 URL 以浏览器指南的形式播放。

:play https://graphcommons.com/graphs/1a93e8fa-e3ce-4ec7-ba16-814b867d1bcb/neo4j

您需要将 GraphCommons URL 添加到白名单配置中，以及默认的白名单。

browser.remote_content_hostname_whitelist=https://graphcommons.com,https://guides.neo4j.com,localhost

jQAssistant

jQAssistant软件分析工具使用指南来探索任何扫描的软件项目。下面列出了与 jQAssistant 相关的 Neo4j 浏览器指南。

:play https://guides.neo4j.com/jqassistant

资源

© . All rights reserved.