Embedding Voyant Tools

Voyant is designed to function as a standalone environment (voyant-tools.org) or as a set of more independent modules that can be embedded into remote sites (much like a YouTube clip). Technically, this is done using an iframe tag that creates a sandbox within your page where Voyant can do its thing (JavaScript security limits the interaction that's possible between your page and Voyant).

Exported Corpus

The Voyant export feature allows you to generate an HTML snippet to embed the current corpus and tool (or skin). Click the Export icon, expand the Export View section, select an HTML snippet radio button, click the Export button, and copy the snippet that appears in the text box.

Export

Here's an example:

<iframe src='http://voyant-tools.org/tool/Cirrus/?corpus=austen' style='width: 400%; height: 400px'></iframe>

The style attribute can be modified as needed for formatting on the containing page. Additional parameters can also be added (for stopword lists, for instance).

Current Page

It's also possible to embed Voyant into the current page and to use the contents of the current page as a corpus. For instance, here is the Cirrus Tool for this page:

<iframe src="http://voyant-tools.org/tool/Cirrus/?useReferer=true" style="width: 300px; height: 300px;"></iframe>

If the page has already been visited, Voyant will have a cached version of the corpus that it will use, unless the page has been modified, in which case it will fetch the contents again.

External Resource

You can also embed a specific page using the input parameter (or a variant format from a given page, such as generated XML or PDF):

<iframe src="http://voyant-tools.org/tool/Cirrus/?input=http://digitalhumanities.org/dhq/vol/3/3/000067/000067.xml"
	style="width: 300px; height: 300px;"></iframe>

Multiple sources can be specified by using additional input parameters:

http://voyant-tools.org/tool/Cirrus/?input=http://digitalhumanities.org/dhq/vol/16/2/000646/000646.html&input=http://digitalhumanities.org/dhq/vol/16/3/000645/000645.html

Here again, cached contents will be reused if possible, and Voyant will check the URL for modifications if needed. If ever Voyant doesn't updated its contents automatically, you can add a string query like ?v1 or &v1 to the source URL to force an update. Note that parameters in the source URL should be escaped as needed so as not to interfere with the parameters to Voyant:

http://voyant-tools.org/tool/Cirrus/?inputFormat=XML&input=http://digitalhumanities.org/dhq/?version%3D1

In this case inputFormat=XML is a parameter of Voyant whereas version%3D1 (escaped form of version=1) is a parameter of the source URL.

Additional Information

It's important to know that for security reasons some content management systems don't allow all authors to use the <iframe> tag. For WordPress, installing the iframe plugin can help.

We assume that screen real-estate is at a premium in embedded instances of Voyant, so the default embedded URL syntax removes the top header that normally appears:

Next Steps