The BioJS MSA Templating System

BioJS MSA Templates

The Jalview Desktop uses a template file to embed data when exporting an alignment as a BioJS MSA HTML page. This means it is possible to update Jalview's template with different versions of the BioJS MSA viewer, or even customise the page for your own needs.

NOTE: This is an experimental feature new in jalview 2.9 - please get in contact with the developers if you're interested in creating your own templates so we can improve this documentation !

The components of a BioJS template file

All JavaScripts necessary to render and visualise BioJS data
JavaScripts to transform BioJSON data to BioJS MSA data

Place holder for BioJSON data (this can be a div or input element as show below):

        <div name="seqData" id="seqData" style="display: none;">#valid BioJSON data#</div>  OR
<input type="hidden" id="seqData" name="seqData" value='#valid BioJSON data#'/>

The externalised BioJS MSA templates are available in the Github repository https://github.com/jalview/exporter-templates/tree/master/biojs.
Jalview processes the package.json file at https://github.com/jalview/exporter-templates/blob/master/biojs/package.json to work out the available versions of BioJS MSA Viewer templates and the latest release version to use for its exports.

Creating/Updating a new BioJS MSA Template

The following steps can be taken to create or update a BioJS MSA template

Add/update all BioJS MSA scripts to the template file
Add/update codes for transforming BioJSON data to BioJS MSA data (this requires knowledge of both data models)
Ensure that the new template created can be employed by Jalview to generate valid BioJS MSA files. This can be achieved by following the steps below to deploy the new export template to a test repository and subsequently configure Jalview to use the test repository for testing the template:
1. Publish the template along with a valid package.json file to an online repository
2. Configure Jalview preferences to point to the raw URL of package.json in your test repository. This is done by creating/changing the property 'biojs_template_git_repo' in the jalview_properties file
  e.g. biojs_template_git_repo=https://raw.githubusercontent.com/gituser/biojs-templates/package.json
3. Restart Jalview and ensure that the new templates are downloaded
4. Export an alignment to BioJS MSA
5. Check that the exported file is valid and reflects all the incorporated changes
Commit the new template to the official Jalview-BioJS Github template repository https://github.com/jalview/exporter-templates/tree/master/biojs
Update the package.json of the official template repository at https://github.com/jalview/exporter-templates/blob/master/biojs/package.json accordingly
Restore value for 'biojs_template_git_repo' in jalview_properties to point to the official template repository
Repeat steps 3iii to 3v above