Getting Started with Spyral Notebooks

This notebook will help you get started with Spyral Notebooks (it's part of the Art of Literary Text Analysis with Spyral Notebooks). In particular, we'll look at:

• getting setup
• metadata
• rich-text blocks (like this one)
• code blocks
• managing blocks
• saving and exporting a notebook
• creating a new notebook
• a sneak peek at working with Spyral
• next steps
• promises

Getting Setup

The good news is that Spyral Notebooks doesn't require any setup. If you're viewing this page then you're already using a fully functional version of Spyral Notebooks.

Having said that, it may be preferable to run a local installation of Spyral Notebooks, for any number of reasons including privacy, performance and reliability. If your Spyral Notebook is doing some heavy lifting, or if you're just starting to experiment and might send your browser or Spyral into an endless loop, it's best to work in a sandbox on your own machine. Fear not, running Spyral Notebooks is usually quick and painless:

• download the latest release of VoyantServer (select the VoyantServer zip file under downloads), extract the contents of the zip file into your choice of directory
• in the new folder (with extracted contents) click on VoyantServer.jar to launch
• with default settings a new browser will appear with the URL http://localhost:8888, change it to http://localhost:8888/spyral/alta/ instead and press enter (that URL will only work if you've launched VoyantServer locally)

That's it!

Spyral is composed of two main types of editing blocks, rich-text and code blocks. We will consider each one below, but first we'll look at a notebook's metadata.

Metadata

Every Spyral notebook has associated metadata, some of which is displayed on the page. You can modify the metdata of a notebook by clicking on the top title or by clicking on the label icon that appears in the top grey header bar. The metadata fields that can be edited are

• title: the document's title which appears at the top of the page
• author: the document's author(s) which appear at the bottom of the page
• keywords: the document's keywords separated by commas
• description: a short summary or abstract for the notebook
• license: the document's copyright license which appears at the bottom of the page
• language: the document's language

The creation date and modification dates are also stored and usually appear at the bottom of the page.

Rich Text Blocks

Although code blocks are where you can make things happen, the rich text blocks are crucial because that's where you can explain what's happening and why. This is a key concept of literate programming where you can interweave narrative text and functional code (and in the case of Spyral Notebooks, interactive output).

Rich text blocks are essentially WYSIWYG HTML and you shouldn't need to master any markup or coding languages, just use the toolbar that appears when you start editing. You can do this now, in this block, just click here and the editing toolbar should appear. You can make content or styling edits to this text (don't be shy, you can edit with impunity!).

Most editing capabilities are fairly standard and we won't go into them here, but there are some noteworthy details:

• for now the image button assumes that your image is available from a URL, though that will change when Spyral has proper account management
• an iframe editing button is included to make it easier (no need for code blocks!) to incorporate content from Voyant Tools or other sites (such as YouTube).
• if the simple set of editing tools is insufficient, you can always select the source code view and make any tweaks necessary
• links are handled specially: if you click on one while not editing (no toolbar visible) then the link should open normally; otherwise it's editable text

There's nothing to run or specially render in a rich text box, when you're done editing you can click elsewhere on the page to create or edit another block, export, etc. You can also click on the X icon in the editing toolbar that appears when in editing mode.

You could write a Spyral Notebook that consists solely of a text box, especially with Voyant Tools embedded in an iframe tag, Spyral is the ideal platform for writing and sharing experiments in text analysis!

Code Blocks

The other kind of building block in Spyral Notebooks is a code block, which is essentially a special editor for Javascript code that includes several helpful libraries (extra functions) for doing text analysis and visualization. We'll explore the extra functionality in much more detail in subsequent notebooks of this guide, but for now we can experiment with some basic mechanics of the editor and output.

Start by clicking in the editor box below to put it in editing mode. Among other things a run (or play) icon should appear in the left column (below the plus icon) that allows you to run the code. Try changing Hello to Hi and then run the code block (by clicking on the run/play icon). As you can see, the value of the code block (in this case the string "Hello world!" appears as output. This is the first important aspect of Spyral coding: output appears according to what is evaluated in the code blocks.

The code editor does some syntax checking as you type, so, for instance, if you remove one of the double quotes from "Hello World! you should see an x appear in the margin and you can hover over the icon for more information. Restore the double quote and then click somewhere on the word show to position the cursor there.

The editor also includes some automatic suggestions that sometimes appear as your typing and sometimes can be summoned with Ctrl-space. For instance, in the box below, add a dot after "Corpus" and you should see a list of suggestions appear.

If Javascript is new to you, don't worry too much for now about the syntax, we'll introduce concepts as we go along.

Data Block

A code block can also be used to edit other kinds of data, such as plain text, HTML, XML and JSON. This make code blocks a convenient way of creating data sets that can be referenced in other code blocks. We'll see examples of this later in the guide. In the left side toolbar of a code block (not a text box like this one) you will see a code icon appear (the one at the bottom) that allows you to convert a block to a different data format.

Managing Blocks

We've already seen the run button from code blocks, but both text and code blocks have some additional functionality, available in the left and right column gutters of the editor:

• add a new block below the current one (text and code blocks will alternate, you can press the shift key while clicking add to get a new block of the same kind)
• remove the current block and delete its contents (you will be prompted to confirm you really wish to do this)
• move up the current block (if it's not already first)
• move down the current block (if it's not already last)

You can try this buttons now. If you remove a block that you didn't mean to remove on this page, you can always reload the page to see it restored.

It's not possible to convert a text block to a code block, or vice-versa, but you can always create new blocks and move content between blocks, as needed.

Saving & Exporting a Notebook

Please note: the current preview version of Spyral Notebooks is experimenting with different mechanisms for storing notebooks and things may change. For now it should be possible to make and edit and then press the cloud/save icon in the upper right-hand part of the header.

There are two major storage solutions in Spyral:

1. Local Storage (this is what is used when you press "Save" from the cloud icon)
2. GitHub (this is what is used when you press "Save as" from the cloud icon)

Save

When you save a notebook you will be given an access code that will allow you to make saves to the same notebook if you open it in the future. If you loose your code there's no mechanism for retrieving it.

Save As

[to be written]

Export

In addition to saving a Spyral Notebook you can also export an HTML view of a notebook that's a static view; this is usually more suitable for printing. To export as HTML click on the export icon in the upper-right-hand part of the header, the box with the diagonal arrow. Expand the "Export View" menu, select HTML, and then click the Export button. Note: this will only work if you allow popup windows from the current page/server.

You can also select the "Download" version from the Export dialog box, this saves a copy of the Notebook to your file system (the file can be opened and viewed in a browser without Voyant/Spyral running – this is one of the major advantages of working in Spyral).

Step 1) Export HTML: as with exporting HTML above, click on the export button icon that appears in the top right part of the grey Spyral Notebook title bar when you're hoving over it. Then select Spyral Notebook data format (JSON) and click the "Export" button. This will produce a dialog box and a text area. Select the contents of the text area (Command/Control-A) and copy it to the clipboard (Command/Control-C).

Step 2) Create Gist: Gist is a service run by GitHub that allows you to instantly share code and snippets. You can save gists into your GitHub account if you have one and are logged in, but you can also create gists anonymously (without creating an account). To create a new gist, go to gist.github.com and paste (Command/Control-V) into the larger box the exported JSON code from Step 1. Give your gist a filename with the extension .json (like SpyralNotebook1.json) and add a description if you wish (this is optional). Click the "Create Public gist" button below the editor (the private gist won't work for our purposes). Finally, copy the browser's URL into the clipboard (the URL is actually not the raw JSON data, but a Spyral Notebook handles it properly).

Step 3) Open Gist: to reopen your Notebook using data from the gist, click the open icon that appears in the right part of the grey Spyral Notebook toolbar. A dialog window will appear with a box where you can paste the URL you copied at the end of Step 2. Click the Open button, and that's it!

Please note:

• you can easily edit a gist that you've created if you're logged into GitHub - an updated gist should have the same URL as before (but you can also  get URLs for previous revisions)
• you can't edit an anonymous gist (one created without at GitHub account), but you can create a new anonymous gist (you can create a free GitHub account if you prefer)
• instead of creating a gist, you can save the exported HTML from Step 1 into a local file or editor and paste in the HTML contents in the dialog box from Step 3.

Creating a New Notebook

Creating a new Spyral Notebook is very simple: when you hover over the top grey title bar (the one that says "Spyral Notebook" on the left and has a help icon on the right), you'll see a plus icon; click on it and a new window should appear with a Spyral Notebook template (if popup windows are blocked you may need to click on a link in a dialog window first).

Sneak Peek at Working with Spyral

This guide will progressively introduce new concepts and techniques for working with Spyral, but for the impatient, here's a quick example. We create a new Corpus from a URL (hermeneuti.ca). The newly created corpus has an embed method that we can use to display one of several tools, in this case we've selected Cirrus (a kind of word cloud). If you're interested, go ahead an modify the arguments (the parts between quotes), providing your own URL or a valid tool type for embedding the corpus.

As with elsewhere in this guide, we won't necessarily explain the coding in detail, we take a pragmatic approach to learning Javascript and Spyral syntax: we learn what's needed to do what want next. Exactly how or why things work that way may not always be fully explained, though in general we'll provide ample documentation. For the code snippet below, for instance, we're using objects, arguments, and functions in the specific context of a Corpus which can embed a Cirrus tool.

Promises

There's a crucial concept in working with Spyral code: several functions involve calls to the server that return data eventually, but not immediately. This is call asynchronous behaviour and Javascript has a mechanism called Promises that allow us to control the flow of code, to execute code once data is returned from the server. The loadCorpus function actually returns a promise, so the code above should normally be written as something like this:

loadCorpus("http://hermeneuti.ca").then(corpus => corpus.tool("cirrus"))
----------------------------------      ------    ---------------------
          promise                      argument      return expression
                                       ---------------------------------
                                                  function

The general form is [promise].then([function]) where function is called once the promise is fulfilled. The syntax above is a newer form of Javascript, the form below is functionally identical and might be more recongnizable for some:

loadCorpus("http://hermeneuti.ca").then(function(corpus) {return corpus.tool("cirrus")})
----------------------------------               ------   -----------------------------
         promise                                argument         return expression
                                        -----------------------------------------------
                                                          function

To make life easier most of the methods from the Corpus class are specially created to allow them to be called without the promise syntax (though internally the same thing is happening). However, the methods of Corpus also usually return promises and if further treatment is needed, the promise syntax is required. Below is an example of showing the top 10 terms in a document.

Next Steps

Here are some exercises to try, based on the contents of this notebook:

• create a new notebook
• try to create two text blocks in a row
• create a new code block and experiment with loading a different URL than the one we used (hermeneuti.ca)
• try experimenting with a couple of the other tools that are available (see the list from the tool function).
• create a code block and try to embed a Cirrus word cloud with the URL from the previous step
• export the notebook as HTML data and create a new Gist
• re-open your notebook using the Gist URL that you just created

If you're working sequentially through the Art of Literary Text Analysis with Spyral Notebooks, the next notebook is Creating a Corpus.