Developing your first Overview plugin

Start with nothing. By the end of this tutorial, you'll have a real app: a program you run on your computer that does something useful.

This program will print a list of documents.

You

This guide uses the command-line, Git and Python; you'll need a vague understanding of all three.

Prerequisites

We're coding a Python app, so please install Python 3. (You can write an app with Python 2, but this tutorial uses Python 3.)

You need to install NodeJS to finish this tutorial. (You can finish an app without it but not this tutorial.)

Set up Overview locally

Follow the instructions in Setting up a development Environment. By the end of it, you should be able to log in to http://localhost:9000.

Then upload a document set to Overview. The simplest way is to upload a bunch of PDFs.

Get some template source code

Your app needs three variables to access your document set: the document set ID, a viz ID and an API token.

The easiest way to get all three is through one of the simplest apps there is: the Sample Code plugin.

Let's start the app:

cd ~/src
git clone https://github.com/overview/overview-apps.git
cd overview-apps/sample-code-generator
npm install
npm start

Invoke it:

1. Browse to http://localhost:9000/documentsets and open your desired document set.
2. Click "New View / Custom..."
3. Enter "Sample Code" as the name and http://localhost:9001 as the URL. (The sample-code-generator app is running on localhost:9001)
4. Click through the no-SSL warning and click "Create View"

Now you'll be looking at the "Sample Code" view. Scroll down and click on "Python" to load up some Python sample code.

Copy the source code to a new file, app.py. That's it -- your first program!

#!/usr/bin/env python3
import base64
import json
import io
import urllib.request

# Set up variables
server = "http://localhost:9000"       # Overview API host
document_set_id = "8"                  # points to documents
api_token = "o1q5v0bzem9mm6ju3xh9a7rb" # password

# URL to list documents
docs_path = '%s/api/v1/document-sets/%s/documents' % (server, document_set_id)

# Create HTTP(S) request, using HTTP Basic Authentication
# urllib.request certainly doesn't make it simple. An alternative:
# the requests module
auth_base64 = base64.b64encode(
  ('%s:%s' % (api_token, 'x-auth-token')).encode('ascii')
).decode('ascii')
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Basic %s' % auth_base64
}
req = urllib.request.Request(docs_path, headers=headers)

# Send the request, synchronously
# The response is raw bytes
res = urllib.request.urlopen(req)

# Convert from bytes to Unicode string. (Again, this should be
# simpler. The Python standard library is a lacklustre option.)
# The string contains JSON.
buf = io.TextIOWrapper(res, res.headers.get_content_charset())

# Parse the JSON string into a list of dicts
data = json.load(buf)

print("Number of documents: %d" % data.pagination.total)
print(data.items)

Run it

chmod +x app.py
python app.py

Change it

This is a real Overview program. You're done! You may want to change this in several ways:

• You can call other Overview API methods.
• You can save data on Overview for later retrieval. You can do that with the State, StoreObject and DocumentStoreObject APIs.
• You can import and export data.
• You can use other libraries and web services to process your data.
• You can create a website centred around your data.
• You can embed that website as a Plugin. See Writing a Plugin.

Run it on production Overview

Go through the same sample-code steps on production to generate another combination of server, document set ID and API token. Plug those into your program and it'll work on production instead of your development machine.