doc/biojsmsa-templates.html

   1 <html>
   2 <!--
   3  *Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   4  *Copyright (C) $$Year-Rel$$ The Jalview Authors
   5  *
   6  *This file is part of Jalview.
   7  *
   8  *Jalview is free software: you can redistribute it and/or
   9  *modify it under the terms of the GNU General Public License
  10  *as published by the Free Software Foundation, either version 3
  11  *of the License, or (at your option) any later version.
  12  *
  13  *Jalview is distributed in the hope that it will be useful, but
  14  *WITHOUT ANY WARRANTY; without even the implied warranty
  15  *of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  16  *PURPOSE.  See the GNU General Public License for more details.
  17  *
  18  *You should have received a copy of the GNU General Public License
  19  *along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  20  *The Jalview Authors are detailed in the 'AUTHORS' file.
  21 -->
  22 <title>The BioJS MSA Templating System</title>
  23 <body>
  24   <h2>BioJS MSA Templates</h2>
  25   <p>The Jalview Desktop uses a template file to embed data when
  26     exporting an alignment as a BioJS MSA HTML page. This means it is
  27     possible to update Jalview's template with different versions of the
  28     BioJS MSA viewer, or even customise the page for your own needs.</p>
  29   <p>NOTE: This is an experimental feature new in jalview 2.9 -
  30     please get in contact with the developers if you're interested in
  31     creating your own templates so we can improve this documentation !</p>
  32   <h3>The components of a BioJS template file</h3>
  33   <ul>
  34     <li>All JavaScripts necessary to render and visualise BioJS
  35       data</li>
  36     <li>JavaScripts to transform BioJSON data to BioJS MSA data</li>
  37     <li>Place holder for BioJSON data (this can be a div or input
  38       element as show below): <pre>
  39         <code>&lt;div name="seqData" id="seqData" style="display: none;"&gt;#valid BioJSON data#&lt;/div&gt;  OR
  40 &lt;input type="hidden" id="seqData" name="seqData" value='#valid BioJSON data#'/&gt;
  41 </code>
  42       </pre>
  43     </li>
  44   </ul>
  45
  46   The externalised BioJS MSA templates are available in the Github
  47   repository
  48   <a
  49     href="https://github.com/jalview/exporter-templates/tree/master/biojs">https://github.com/jalview/exporter-templates/tree/master/biojs</a>.
  50   <br />Jalview processes the
  51   <b>package.json</b> file at
  52   <a
  53     href="https://github.com/jalview/exporter-templates/blob/master/biojs/package.json">https://github.com/jalview/exporter-templates/blob/master/biojs/package.json</a>
  54   to work out the available versions of BioJS MSA Viewer templates and
  55   the latest release version to use for its exports.
  56
  57
  58   <h2>Creating/Updating a new BioJS MSA Template</h2>
  59   The following steps can be taken to create or update a BioJS MSA
  60   template
  61   <ol>
  62     <li>Add/update all BioJS MSA scripts to the template file</li>
  63     <li>Add/update codes for transforming BioJSON data to BioJS MSA
  64       data (this requires knowledge of both data models)</li>
  65     <li>Ensure that the new template created can be employed by
  66       Jalview to generate valid BioJS MSA files. This can be achieved by
  67       following the steps below to deploy the new export template to a
  68       test repository and subsequently configure Jalview to use the test
  69       repository for testing the template:
  70       <ol type="i">
  71         <li>Publish the template along with a valid package.json
  72           file to an online repository</li>
  73         <li>Configure Jalview preferences to point to the raw URL
  74           of package.json in your test repository. This is done by
  75           creating/changing the property <b>'biojs_template_git_repo'</b>
  76           in the <b>jalview_properties</b> file <br />e.g. <b>biojs_template_git_repo=https://raw.githubusercontent.com/gituser/biojs-templates/package.json</b>
  77         </li>
  78         <li>Restart Jalview and ensure that the new templates are
  79           downloaded</li>
  80         <li>Export an alignment to BioJS MSA</li>
  81         <li>Check that the exported file is valid and reflects all
  82           the incorporated changes</li>
  83       </ol>
  84     </li>
  85     <li>Commit the new template to the official Jalview-BioJS
  86       Github template repository <a
  87       href="https://github.com/jalview/exporter-templates/tree/master/biojs">https://github.com/jalview/exporter-templates/tree/master/biojs</a>
  88     </li>
  89     <li>Update the package.json of the official template repository
  90       at <a
  91       href="https://github.com/jalview/exporter-templates/blob/master/biojs/package.json">https://github.com/jalview/exporter-templates/blob/master/biojs/package.json</a>
  92       accordingly
  93     </li>
  94     <li>Restore value for <b>'biojs_template_git_repo'</b> in
  95       jalview_properties to point to the official template repository
  96     </li>
  97     <li>Repeat steps 3iii to 3v above</li>
  98   </ol>
  99
 100 </body>
 101 </html>