Creating Custom Viewers

In addition to the public viewers available on the DNAnexus platform, users can create their own custom viewers. In order to create a custom viewer, you will need familiarity with web development and the ability to use the command line. Specifically, you will need access to the DNAnexus SDK (dx-toolkit) from the command line, and you will need to create the viewer yourself as a web application using HTML and JavaScript.

How Viewers Work

A Viewer is an HTML file with embedded JavaScript that has access to some user-specified files. When a Viewer is opened, a dialogue first appears that allows you to choose a set of files in your projects, for which download URLs are then generated. These files' download URLs are then made available to the Viewer through a snippet of JavaScript code. From there, a Viewer can link to another web server, such as the UCSC genome browser, or run some JavaScript within the Viewer itself -- for instance, by using an outside plotting library such as IGV.js.

The only difference between custom and public Viewers is that you can share custom Viewers with collaborators just as you would share any other item in your projects, while public Viewers are available to all users on the platform and can only be created or changed by DNAnexus employees. When a custom Viewer is present in a project you select, it will be listed in the Visualize tab above the DNAnexus Viewers.

Making a Custom Viewer

1. Make sure you have dx-toolkit installed and you can access it from the command line.

2. Download some Viewers to see how they are written. You can also adapt a pre-existing Viewer if one similar to your required viewer exists.

$ dx select project-BQ7k4pj0FVky4kVkgVf0000F
Selected project project-BQ7k4pj0FVky4kVkgVf0000F
$ dx ls -l
Project: Viewers (project-BQ7k4pj0FVky4kVkgVf0000F)
...
$ dx download file-xxxx

1. Write the HTML file using an existing FileViewer as a template. The name of the HTML file will be the name listed for this Viewer in the Visualize tab. The file name does not have to have the .html extension, and it can have spaces if you put the name in quotes.

2. Upload the HTML file into one of your DNAnexus projects using the --type FileViewer and setting --details with a JSON string containing the patterns for files that the Viewer will accept. In the case below, the FileViewer is named "My Bam Viewer", and it will only take files whose names end in .bam or .bai. Be sure to remove spaces from the --details patterns and carefully match the format below, including pairing quotes correctly. For the existing public Viewers, the Viewers' names also contain the file patterns (in parentheses) for informational purposes. It is the --details flag here that directly controls which files can be chosen for the Viewer.

$ dx select "My Project"
$ dx upload --type FileViewer --details='{"patterns":["*.bam","*.bai"]}' "My Bam Viewer"
[===========================================================>] Uploaded 4,043 of 4,043 bytes (100%) My\ Bam\ Viewer

1. Go to the DNAnexus Platform and select the project where you uploaded the Viewer. Under the Visualize tab, you should see a section entitled Custom Viewers. Your new Viewer should be there, which you can now test and iterate. If you need to change the HTML file, you will need to remove it and re-upload it from the command line:

$ dx select "My Project"
Selected project My Project
$ dx rm "My Bam Viewer"
$ dx upload --type FileViewer --details='{"patterns":["*.bam","*.bai"]}' "My Bam Viewer"
[===========================================================>] Uploaded 4,043 of 4,043 bytes (100%) My\ Bam\ Viewer