examples/jalviewLiteJs.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   2 <!--
   3  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8)
   4  * Copyright (C) 2012 J Procter, AM Waterhouse, LM Lui, J Engelhardt, G Barton, M Clamp, S Searle
   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 of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  18 -->
  19 <html xmlns="http://www.w3.org/1999/xhtml">
  20 <head>
  21
  22  <title>JalviewLite API documentation</title>
  23  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  24
  25  <link href="css/reset.css" rel="stylesheet" type="text/css" />
  26  <link href="css/style.css" rel="stylesheet" type="text/css" />
  27
  28   <!--[if IE 6]>
  29         <link rel="stylesheet" type="text/css" href="css/ie6.css" />
  30 <![endif]-->
  31
  32 <!--[if IE 7]>
  33         <link rel="stylesheet" type="text/css" href="css/ie7.css" />
  34 <![endif]-->
  35
  36 <!-- dd menu -->
  37 <script type="text/javascript">
  38 <!--
  39 var timeout         = 500;
  40 var closetimer          = 0;
  41 var ddmenuitem      = 0;
  42
  43 // open hidden layer
  44 function mopen(id)
  45 {
  46         // cancel close timer
  47         mcancelclosetime();
  48
  49         // close old layer
  50         if(ddmenuitem) ddmenuitem.style.visibility = 'hidden';
  51
  52         // get new layer and show it
  53         ddmenuitem = document.getElementById(id);
  54         ddmenuitem.style.visibility = 'visible';
  55
  56 }
  57 // close showed layer
  58 function mclose()
  59 {
  60         if(ddmenuitem) ddmenuitem.style.visibility = 'hidden';
  61 }
  62
  63 // go close timer
  64 function mclosetime()
  65 {
  66         closetimer = window.setTimeout(mclose, timeout);
  67 }
  68
  69 // cancel close timer
  70 function mcancelclosetime()
  71 {
  72         if(closetimer)
  73         {
  74                 window.clearTimeout(closetimer);
  75                 closetimer = null;
  76         }
  77 }
  78
  79 // close layer when click-out
  80 document.onclick = mclose;
  81 // -->
  82 </script>
  83 <!--//--><![CDATA[//><!--
  84 var _gaq = _gaq || [];_gaq.push(["_setAccount", "UA-9060947-1"]);_gaq.push(["_trackPageview"]);(function() {var ga = document.createElement("script");ga.type = "text/javascript";ga.async = true;ga.src = ("https:" == document.location.protocol ? "https://ssl" : "http://www") + ".google-analytics.com/ga.js";var s = document.getElementsByTagName("script")[0];s.parentNode.insertBefore(ga, s);})();
  85 //--><!]]>
  86 </head>
  87
  88
  89 <body>
  90
  91
  92 <div id="header">
  93 <div id="logo"><a href="http://www.jalview.org" title="Home"></a></div>
  94 <ul id="buttons">
  95 <li id="applet"><a href="applets.html" title="applet"></a></li>
  96 <li id="desktop"><a href="../webstart/jalview.jnlp" title="desktop"></a></li>
  97 </ul>
  98 </div>
  99
 100
 101 <div id ="nav">
 102 <div id="navInner">
 103
 104 <ul id="sddm">
 105  <li><a href="http://www.jalview.org">Home</a></li>
 106  <li><a href="http://www.jalview.org/about" onmouseover="mopen('m1')" onmouseout="mclosetime()">About</a>
 107   <div id="m1" onmouseover="mcancelclosetime()" onmouseout="mclosetime()">
 108   <a href="http://www.jalview.org/about/documentation">Documentation</a>
 109   <a href="http://www.jalview.org/about/citation">Publications</a>
 110   <a href="http://www.jalview.org/about/credits">Credits</a>
 111   </div>
 112  </li>
 113  <li><a href="http://www.jalview.org/faq">FAQ</a></li>
 114  <li><a href="http://www.jalview.org/community" onmouseover="mopen('m3')" onmouseout="mclosetime()" class="community">Community</a>
 115   <div id="m3" onmouseover="mcancelclosetime()" onmouseout="mclosetime()">
 116   <a href="http://www.jalview.org/mailman/listinfo/jalview-announce">News Mailing List</a>
 117   <a href="http://www.jalview.org/mailman/listinfo/jalview-discuss">Discussion Mailing List</a>
 118   <a href="http://www.jalview.org/community/links">Links</a>
 119   <a href="http://www.jalview.org/community/community-news">Community News</a>
 120   </div>
 121  </li>
 122  <li><a href="http://www.jalview.org/development" onmouseover="mopen('m4')" onmouseout="mclosetime()" class="development">Development</a>
 123   <div id="m4" onmouseover="mcancelclosetime()" onmouseout="mclosetime()">
 124   <a href="http://www.jalview.org/development/release-history">Release History</a>
 125   <a href="http://issues.jalview.org">Jalview Bug Tracker</a>
 126   <a href="http://source.jalview.org/gitweb/">Jalview Git Web</a>
 127   <a href="http://www.jalview.org/development/development-news">Development News</a>
 128   </div>
 129  </li>
 130  <li><a href="http://www.jalview.org/training" onmouseover="mopen('m5')" onmouseout="mclosetime()" class="training">Training</a>
 131   <div id="m5" onmouseover="mcancelclosetime()" onmouseout="mclosetime()">
 132   <a href="http://www.jalview.org/training/training-courses">Training Courses</a>
 133   <a href="http://www.jalview.org/training/training-news">Training News</a>
 134   </div>
 135  </li>
 136  <li><a href="http://www.jalview.org/download" class="download-right">Download</a></li>
 137 </ul>
 138 <div style="clear:both"></div>
 139 </div>
 140
 141 </div>
 142
 143
 144 <div id="pageWrap">
 145
 146 <div id="sideNav">
 147 <ul>
 148 <li><a href="applets.html">JalviewLite Examples</a></li>
 149 <li><a href="appletParameters.html">Applet Parameters</a></li>
 150 <li class="jvlite-nav-small"><a href="jalviewLiteJs.html">Javascript API</a></li>
 151 <li><a href="formComplete.html">in-page API demo</a></li>
 152 <li><a href="linkedapplets_ng.html">Two JalviewLites demo</a></li>
 153 <li><a href="embeddedWJmol.html">Jalview and Jmol demo</a></li>
 154 </ul>
 155 </div>
 156
 157 <div id="content" class="content">
 158                 <p>The jalviewLite applet's application programming interface (API) includes two components. A <a href="javascript/jalview.js">JalviewLite Javascript Library</a> and the <a href="#api">public methods on the JalviewLite applet</a>.
 159 </p>
 160                 <h3>Notes</h3>
 161                 <ul>
 162                 <li>Unfortunately Javascript - Java communication is not possible
 163                 using Internet Explorer or Opera on Macs. Please use Safari or
 164                 Firefox.</li>
 165                 <li>If more than one Jalview window is open, Jalview returns the
 166                 alignment in the active window, unless you provide an AlignFrame
 167                 object reference.</li>
 168                 <li>The alignment output format can be either Fasta, PFAM, Clustal,
 169                 MSF, PIR, or BLC.</li>
 170                 <li>When referring to the Jalview applet in javascript, you must
 171                 either give Jalview a name in the applet tag or use the document.applets index.</li>
 172                 <li>When creating javascript functions that are called by jalviewLite (e.g. the <em>oninit</em> parameter, or any mouseOver, selection or structureListener handlers), ensure they complete very quickly, and do not access any jalview API methods that might result in more javascript calls (this which will cause your browser to hang). If you need to do this, we suggest that jalviewLite callbacks are used to add new javascript events to a queue (e.g. using a Jquery timer callback) to avoid any concurrency issues.
 173                 </li>
 174                 </ul>
 175                 <a name="api">
 176                 <h1>JalviewLite's Javascript API</h1></a>
 177                 <p>The following public methods on the jalviewLite applet are available to be called from javascript:</p>
 178                 <pre>//get list of IDs of selected sequences
 179 public String getSelectedSequences()
 180
 181 // list of IDs of selected sequences terminated by sep or, if sep is null, '&#172;' (&amp;#172;)
 182 public String getSelectedSequences(sep)
 183
 184 // get list of selected sequences from specific alignFrame. (2.7)
 185 public String getSelectedSequencesFrom(AlignFrame alf)
 186 public String getSelectedSequencesFrom(AlignFrame alf, String sep)
 187
 188 // highlight a position in a specific sequence or a column in an alignment containing it
 189 // provide ID sequence to highlight, integer (range highlighting will be supported in future versions)
 190 // and flag indicating if position is an alignment column or given according to sequence numbering (2.7)
 191 public void highlight(String sequenceId, String position, String alignedPosition)
 192 public void highlightIn(AlignFrame alf, String sequenceId, String position, String alignedPosition)
 193
 194
 195 // select regions of the currrent alignment frame using a list of sequence ids and a list of
 196 // column numbers and ranges (with minus sign indicating start-end) (separated by default separator) (2.7)
 197 public void select(String sequenceIds, String columns)
 198 public void select(String sequenceIds, String columns, String sep)
 199 public void selectIn(AlignFrame alf, String sequenceIds, String columns)
 200 public void selectIn(AlignFrame alf, String sequenceIds, String columns, String sep)
 201
 202
 203 // get selected sequences as alignment as format with or without start-end suffix
 204 public String getSelectedSequencesAsAlignment(String format, boolean suffix)
 205
 206 // get selected sequences as alignment from given view as format with or without start-end suffix
 207 public String getSelectedSequencesAsAlignmentFrom(AlignFrame alf, String format, boolean suffix)
 208
 209 // get a separator separated list of sequence IDs reflecting the order of the current alignment (2.7)
 210 public String getAlignmentOrder();
 211 public String getAlignmentOrderFrom(AlignFrame alf);
 212 public String getAlignmentOrderFrom(AlignFrame alf, String sep);
 213
 214 // re-order the current alignment using the given list of sequence IDs separated by sep
 215 // undoName - is string to use when referring to ordering action in undo buffer
 216 // returns 'true' if alignment was actually reordered. empty string if alignment did not contain sequences.
 217 // (v2.7)
 218 public String orderBy(String order, String undoName)
 219 public String orderBy(String order, String undoName, String sep)
 220 String orderAlignmentBy(AlignFrame alf, String order, String undoName, String sep)
 221
 222
 223 // get alignment as format
 224 public String getAlignment(String format)
 225
 226 // get alignment as format with jalview
 227 // start-end sequence suffix appended
 228 public String getAlignment(String format, String suffix)
 229
 230 // get alignment displayed in alf as format
 231 public String getAlignmentFrom(AlignFrame alf, String format)
 232
 233 // get alignment displayed in alf as format
 234 // with jalview start-end sequence suffix appended
 235 public String getAlignmentFrom(AlignFrame alf, String format, String suffix)
 236
 237 // add the given features or annotation to the current alignment
 238 // if features are loaded, feature display is automatically enabled
 239 public void loadAnnotation(String annotation)
 240
 241 // add the given features or annotation to the given alignment view
 242 // if features are loaded, feature display is automatically enabled
 243 public void loadAnnotationFrom(AlignFrame alf, String annotation)
 244
 245 // parse the given string as a jalview or GFF features file and optionally enable feature display on the current alignment
 246 // (v2.8)
 247 public abstract void loadFeatures(String features, boolean autoenabledisplay)
 248
 249 // parse the given string as a jalview or GFF features file and optionally enable feature display on the given alignment
 250 // (v2.8)
 251 public abstract void loadFeaturesFrom(AlignFrame alf, String features, boolean autoenabledisplay)
 252
 253 // get the sequence features in the given format (Jalview or GFF)
 254 public String getFeatures(String format)
 255
 256 // get the sequence features in alf in the given format (Jalview or GFF)
 257 public String getFeaturesFrom(AlignFrame alf, String format)
 258
 259 // get current alignment's annotation as an annotation file
 260 public String getAnnotation()
 261
 262 // get alignment view alf's annotation as an annotation file
 263 public String getAnnotationFrom(AlignFrame alf)
 264
 265 // create a new view and return the alignFrame instance
 266 public AlignFrame newView()
 267
 268 // create a new view named name and return the alignFrame instance
 269 public AlignFrame newView(String name)
 270
 271 // create a new view on alf and return the alignFrame instance
 272 public AlignFrame newViewFrom(AlignFrame alf)
 273
 274 // create a new view named name on alf
 275 // and return the alignFrame instance
 276 public AlignFrame newViewFrom(AlignFrame alf, String name)
 277
 278 // load a new alignment
 279 // remember to store the AlignFrame object reference
 280 // if you want to manipulate the new alignment view.
 281 public AlignFrame loadAlignment(String text, String title)
 282
 283
 284 // register a javascript function to handle any alignment mouseover events
 285 // listener is name of javascript function  which will be called
 286 // with arguments [jalview.appletgui.AlignFrame,String(sequence id),
 287 // String(column in alignment), String(position in sequence)]
 288 // (v2.7)
 289 public void setMouseoverListener(String listener)
 290
 291 // register a javascript function to handle mouseover events for specific alignframe
 292 // (v2.7)
 293 public void setMouseoverListener(AlignFrame af, String listener)
 294
 295 // register a javascript function to handle alignment selection events.
 296 // Events are generated when the user completes a selection event, or when
 297 // the user deselects all selected regions.
 298 // listener is name of javascript function  that will be called with arguments
 299 //  [jalview.appletgui.AlignFrame, String(sequence set id),
 300 //   String(separator separated list of sequences which were selected),
 301 //   String(separator separated list of column ranges)]
 302 // (v2.7)
 303 public void setSelectionListener(String listener)
 304
 305 // register a selection listener for a specific alignment frame
 306 // (v2.7)
 307 public void setSelectionListener(AlignFrame af, String listener)
 308
 309 // register a javascript function to handle events normally routed
 310 // to a Jmol structure viewer.
 311 // listener is a javascript function called with several different types
 312 // of arguments, dependent on the type of structure callback event.
 313 // See jalview.javascript.MouseOverStructureListener for full details or
 314 // the embedded Jmol example.
 315 // modelSet - is a separator separated list of PDB file URIs that this viewer is handling (where position in list equals model number in Jmol).
 316 // (v2.7)
 317 public void setStructureListener(String listener, String modelSet)
 318
 319 // remove any callback using the given listener function and associated with
 320 // the given alignFrame (or null for all callbacks) (v2.7)
 321 public void removeJavascriptListener(AlignFrame af, String listener)
 322
 323 // send a mouseover message to all the alignment windows associated with the
 324 // given residue in the pdbfile (v2.7)
 325 public void mouseOverStructure(String pdbResNum, String chain, String pdbfile)
 326
 327 // bind a pdb file to a sequence in the given alignFrame - this will be searched
 328 // for sequences matching sequenceId. The PDB file in pdbFile is either the contents
 329 // of a PDB file or a URI that can be used to retrieve the file, and the pdbEntryString
 330 // is the user friendly name (or PDBID) shown in jalview's user interface.
 331 // returns true if binding was as success (v2.7)
 332 public boolean addPdbFile(AlignFrame alFrame,
 333     String sequenceId, String pdbEntryString, String pdbFile)
 334
 335 // adjust horizontal/vertical scroll in alf to the make
 336 // the given location the top left hand corner for given current view (v2.7)
 337 public void scrollViewToIn(AlignFrame alf, String topRow, String leftHandColumn)
 338
 339 // adjust horizontal scroll in alf to the make
 340 // the given location the left hand corner for given current view (v2.7)
 341 public void scrollViewToColumnIn(AlignFrame alf, String leftHandColumn)
 342
 343 // adjust horizontal/vertical scroll in alf to the make
 344 // the given location the top row for given current view (v2.7)
 345 public void scrollViewToRowIn(AlignFrame alf, String topRow)
 346
 347
 348 // return separator separated list of feature groups
 349 // on the current alignment
 350 public String getFeatureGroups()
 351
 352 // return separator separated list of feature groups on alf
 353 public String getFeatureGroupsOn(AlignFrame alf)
 354
 355 // return separator separated list of feature groups
 356 // either visible or hidden
 357 public String getFeatureGroupsOfState(boolean state)
 358
 359 // return separator separated list of feature groups
 360 // either visible or hidden on alf
 361 public String getFeatureGroupsOfStateOn(AlignFrame alf, boolean state)
 362
 363 // set the separator separated list of feature groups as
 364 // visible or hidden on the current alignment
 365 public void setFeatureGroupState(String groupList, boolean state)
 366
 367 // set the separator separated list of feature groups
 368 // as visible or hidden on alf
 369 public void setFeatureGroupStateOn(AlignFrame alf, String groupList, boolean state)
 370
 371 // helper functions
 372
 373 // Asynchronously retrieve next chunk of a large packet of data made available
 374 // for a JalviewLite event handler, or the empty string if no more data is available.
 375 // messageclass and viewId are keys used to retrieve a specific message related
 376 // to an event.
 377 // Use this in a javascript timer or GUI update thread to retrieve data without
 378 // blocking the JalviewLite applet. DO NOT USE IN THE CALLBACK THAT HANDLED THE EVENT
 379 // (v2.7)
 380 public String getJsMessage(String messageclass, String viewId)
 381
 382
 383 // convert list to a separator separated array
 384 public String arrayToSeparatorList(String[] list)
 385
 386 // get a string array from a list
 387 public String[] separatorListToArray(String list)
 388
 389 // get the current separator
 390 public String getSeparator()
 391
 392 // set the current separator
 393 public void setSeparator(String)
 394
 395 //// JalviewLite global state methods and fields
 396
 397 // return the build date as a string
 398 public static String getBuildDate()
 399
 400 // return the JalviewLite version as a string
 401 public static String getVersion()
 402
 403 // debug flag - controls output to standard out
 404 public static boolean debug
 405
 406 </pre>
 407
 408 </div>
 409
 410 <div id ="footer">
 411 <div id="innerFooter">
 412 <div id="copyright"><p>Published under <a href="http://creativecommons.org/licenses/by-sa/3.0/">CC-SA 3.0</a></p></div>
 413 <div id="cite">
 414 <p>
 415 If you use Jalview in your work, please cite this publication:
 416 </p>
 417 <br />
 418 <p>
 419 Waterhouse, A.M., Procter, J.B., Martin, D.M.A, Clamp, M. and Barton, G. J. (2009)
 420 "Jalview Version 2 - a multiple sequence alignment editor and analysis workbench"
 421 Bioinformatics 25 (9) 1189-1191 <a href="http://dx.doi.org/10.1093/bioinformatics/btp033">doi: 10.1093/bioinformatics/btp033</a>
 422 </p>
 423 </div>
 424 </div>
 425 </div>
 426 </body>
 427 </html>