How to create a previewer

Using the existing HTML/JS templates

Previewers can be created in any language - they just have to be a webapp that can parse the URL provided by Dataverse via its External Tools API. The initial ones in this repository were all created using some common HTML/Javascript templates, which simplifies their creation. To make your own previewer that leverages an existing viewer component, you need to know just a few things:

• What javascript libraries does it require?
• What HTML elements does it need?
• Does it need a URL to the data or just the bytes from the file? With this information, here are the steps:

HTML file creation

Start from a simple example such as the Audio Previewer's HTML file. In this template, you simply need to

• replace the audio.js javascript file (line 5) with any javascript files used by your previewer,
• minimally you'll need to include a <your-previewer>.js that you'll create below,
• add any css files your previewer needs,
• change the title on line 15, and
• optionally, add any additional HTML elements you'll need inside the div, class='preview' on line 19 (this is optional because you can also add elements dynamically in the javascript you create in the next step).

Javascript file creation

If your previewer uses the file URL, start from an example like the Audio Previewer's Javascript file Change line 7 in the writeContent() function to add any HTML elements you need and provide the 'fileUrl', which is the download URL for the Dataverse file you'll preview, in the appropriate place. For an audio previewer (and image previewer), this means putting the fileUrl as the 'src' attribute of the audio (or img) element. Your previewer may have it's own attribute. If your previewer requires the file contents, start from the text or html example and use the writeContentAndData fuction instead which provides you with the file variable containing the file contents.

Running your Previewer

Now that it's built (that was it), you just need to put the HTML and Javascript files where they can be served from a web address and register your new external tool with your Dataverse instance - see all the examples in the README of this repository.

A partial example - The 3D Heritage Online Presenter

The documentation for 3DHOP describes the javascript files and HTML elements you need to run it. So:

• Add the scripts and css to your HTML (as in their documentation, and as in lines 77-87 of their example - view source in your browser to see the raw HTML with the css and scripts listed.
• Add a line for your 3dhoppreviewer.js file
• Change the title to 3D HOP Previewer
• 3dhop expects a div of class '3dhop' and a <canvas> element as shown in their documentation (linked above) - add those inside your previewer div.
• Create your 3dhoppreviewer.js file. In their documentation, they note that you have to add a a setup3dhop function and call init3dhop and that function once your page is ready. For this example, just copy their setup3dhop function from the example (starting at line 91 in the example linked above) but change the url from "/models/capital.nxz" to fileUrl (the file coming from Dataverse). Also add a $(document).ready(function() as they do (line 126) to call the init and setup methods required.
• Put your previewer on the web, register it, and get a file that works (such as this one ) and add it to your Dataverse
• Try it out!

Why might this not work:

• When I uploaded this file into Dataverse, it's mimetype was not recognized. If you work with this type of file, your computer/browser may provide a useful mimetype to Dataverse which you can then use when you register the previewer. If not, Dataverse may need to have this file extension/mimetype added to it's internal list of known mimetypes.
• If you look in their setup3dhop function, it defines some camera positioning, field of view, etc. These presumably work with the example file, but if you use a different .nxz file, these may not be good defaults. I don't know enough about 3DHOP to know if it will automatically pick some useful defaults if you don't specify these aspects. If not, it may be hard to make this example generally useful - you'd need to know a good camera position. That might be useful metadata to store in Dataverse, and the external tool API would allow you to get that metadata if it existed, but it would be more work to add a metadata field to Dataverse for this purpose.