From: Jim Procter Date: Wed, 9 Sep 2015 17:20:47 +0000 (+0100) Subject: JAL-1645 relocate developer info about BioJS MSA templates to jalview/doc. X-Git-Tag: Release_2_10_0~451 X-Git-Url: http://source.jalview.org/gitweb/?a=commitdiff_plain;h=dfb7b17a2c6b0019320d6fbdddbbd16b933dc62d;p=jalview.git JAL-1645 relocate developer info about BioJS MSA templates to jalview/doc. --- diff --git a/doc/biojsmsa-templates.html b/doc/biojsmsa-templates.html new file mode 100644 index 0000000..40e326d --- /dev/null +++ b/doc/biojsmsa-templates.html @@ -0,0 +1,81 @@ + +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

+ + + 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 +
    +
  1. Add/update all BioJS MSA scripts to the template file
    2. +
  2. Add/update codes for transforming BioJSON data to BioJS MSA + data (this requires knowledge of both data models)
    3. +
  3. 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. +
    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. +
    3. Restart Jalview and ensure that the new templates are + downloaded
      4. +
    4. Export an alignment to BioJS MSA
      5. +
    5. Check that the exported file is valid and reflects all + the incorporated changes
      6. +
    +
    4. +
  4. Commit the new template to the official Jalview-BioJS + Github template repository https://github.com/jalview/exporter-templates/tree/master/biojs +
    5. +
  5. Update the package.json of the official template repository + at https://github.com/jalview/exporter-templates/blob/master/biojs/package.json + accordingly +
    6. +
  6. Restore value for 'biojs_template_git_repo' in + jalview_properties to point to the official template repository +
    7. +
  7. Repeat steps 3iii to 3v above
    8. +
+ + + \ No newline at end of file diff --git a/help/html/features/biojsmsa.html b/help/html/features/biojsmsa.html index 63c6960..ff4d8da 100644 --- a/help/html/features/biojsmsa.html +++ b/help/html/features/biojsmsa.html @@ -1,44 +1,32 @@ -

BioJS MSA Viewer

- -Since Jalview 2.9, BioJS MSA HTML files can be generated from an alignment within the Jalview desktop application. BioJS MSA Viewer is a JavaScript based multiple sequence alignment visualisation system. Jalview generates BioJS HTML files by parsing a BioJS MSA export template file and embedding BioJSON data from a given alignment on the Jalview desktop application. - -

To ensure that the BioJS MSA export mechanism is easily extensible, the export templates are externalised from the Jalview codebase. Consequently, new versions of BioJS MSA Viewer can easily be integrated into Jalview without having to deploy a new version of Jalview.

- -

What constitutes a BioJS MSA Template

- - -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 -
    -
  1. Add/update all BioJS MSA scripts to the template file
    2. -
  2. Add/update codes for transforming BioJSON data to BioJS MSA data (this requires knowledge of both data models)
    3. -
  3. 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. -
    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. -
    3. Restart Jalview and ensure that the new templates are downloaded
      4. -
    4. Export an alignment to BioJS MSA
      5. -
    5. Check that the exported file is valid and reflects all the incorporated changes
      6. -
    -
    4. -
  4. Commit the new template to the official Jalview-BioJS Github template repository https://github.com/jalview/exporter-templates/tree/master/biojs
    5. -
  5. Update the package.json of the official template repository at https://github.com/jalview/exporter-templates/blob/master/biojs/package.json accordingly
    6. -
  6. Restore value for 'biojs_template_git_repo' in jalview_properties to point to the official template repository
    7. -
  7. Repeat steps 3iii to 3v above
    8. -
- -Note: -When Jalview starts up, provided that there is an internet connection, Jalview checks if there are new updates of BioJS MSA template added to the repository and downloads them to a local user directory for subsequent offline use. +BioJS MSA Viewer Export + +

+ Exporting Alignments for viewing with the BioJS MSA + Viewer +

+

Since Jalview 2.9, HTML files can be generated from an + alignment within the Jalview desktop application that show the + alignment in an interactive viewer called 'BioJS-MSA'. The BioJS MSA + Viewer is a full-featured JavaScript based multiple sequence + alignment visualisation system created by a community of biological + data visualisation developers, and is developed independently of + Jalview.

+

+ To find out more about the BioJS MSA Viewer, please go to http://msa.biojs.net/. +

+ Making sure your BioJS MSA exports uses the latest + BioJS MSA Viewer +

+

In order to allow Jalview to export data with the latest + version of the MSA viewer, the Jalview Desktop will download + templates for HTML export from our public GitHub Repository. + Normally, this should happen without you needing to do anything, but + if you do encounter problems, then please get in contact via the + jalview-discuss mailing list, or file a bug report.

+

Templates are downloaded to a directory called + '.biojs_templates' in your user's home storage space (e.g. + ~/.biojs_templates).

+