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
  84 </head>
  85
  86
  87 <body>
  88
  89
  90 <div id="header">
  91 <div id="logo"><a href="/" title="Home"></a></div>
  92 <ul id="buttons">
  93 <li id="applet"><a href="applets.html" title="applet"></a></li>
  94 <li id="desktop"><a href="/webstart/jalview.jnlp" title="desktop"></a></li>
  95 </ul>
  96 </div>
  97
  98
  99 <div id ="nav">
 100 <div id="navInner">
 101
 102 <ul id="sddm">
 103         <li><a href="#">Home</a></li>
 104         <li><a href="#" onmouseover="mopen('m1')" onmouseout="mclosetime()">About</a>
 105                 <div id="m1" onmouseover="mcancelclosetime()" onmouseout="mclosetime()">
 106                 <a href="#">Documentation</a>
 107                 <a href="#">Publications</a>
 108                 <a href="#">Credits</a>
 109                 <a href="#">Screenshots</a>
 110                 </div>
 111         </li>
 112         <li><a href="#">FAQ</a></li>
 113         <li><a href="#" onmouseover="mopen('m3')" onmouseout="mclosetime()" class="community">Community</a>
 114                 <div id="m3" onmouseover="mcancelclosetime()" onmouseout="mclosetime()">
 115                 <a href="#">News Mailing List</a>
 116                 <a href="#">Discussion Mailing List</a>
 117                 <a href="#">Links</a>
 118                 <a href="#">Community News</a>
 119                 </div>
 120         </li>
 121         <li><a href="#" onmouseover="mopen('m4')" onmouseout="mclosetime()" class="development">Development</a>
 122                 <div id="m4" onmouseover="mcancelclosetime()" onmouseout="mclosetime()">
 123                 <a href="#">Release History</a>
 124                 <a href="#">Jalview Bug Tracker</a>
 125                 <a href="#">Jalview Git Web</a>
 126                 <a href="#">Development News</a>
 127                 </div>
 128         </li>
 129         <li><a href="#" onmouseover="mopen('m5')" onmouseout="mclosetime()" class="training">Training</a>
 130                 <div id="m5" onmouseover="mcancelclosetime()" onmouseout="mclosetime()">
 131                 <a href="#">Training Courses</a>
 132                 <a href="#">Training News</a>
 133                 </div>
 134         </li>
 135         <li><a href="#" class="download-right">Download</a></li>
 136 </ul>
 137 <div style="clear:both"></div>
 138 </div>
 139
 140 </div>
 141
 142
 143 <div id="pageWrap">
 144
 145 <div id="sideNav">
 146 <ul>
 147 <li><a href="applets.html">JalviewLite Examples</a></li>
 148 <li><a href="appletParameters.html">Applet Parameters</a></li>
 149 <li class="jvlite-nav-small"><a href="jalviewLiteJs.html">Javascript API</a></li>
 150 <li><a href="formComplete.html">in-page API demo</a></li>
 151 <li><a href="linkedapplets_ng.html">Two JalviewLites demo</a></li>
 152 <li><a href="embeddedWJmol.html">Jalview and Jmol demo</a></li>
 153 </ul>
 154 </div>
 155
 156 <div id="content" class="content">
 157                 <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>.
 158 </p>
 159                 <h3>Notes</h3>
 160                 <ul>
 161                 <li>Unfortunately Javascript - Java communication is not possible
 162                 using Internet Explorer or Opera on Macs. Please use Safari or
 163                 Firefox.</li>
 164                 <li>If more than one Jalview window is open, Jalview returns the
 165                 alignment in the active window, unless you provide an AlignFrame
 166                 object reference.</li>
 167                 <li>The alignment output format can be either Fasta, PFAM, Clustal,
 168                 MSF, PIR, or BLC.</li>
 169                 <li>When referring to the Jalview applet in javascript, you must
 170                 either give Jalview a name in the applet tag or use the document.applets index.</li>
 171                 <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.
 172                 </li>
 173                 </ul>
 174                 <a name="api">
 175                 <h1>JalviewLite's Javascript API</h1></a>
 176                 <p>The following public methods on the jalviewLite applet are available to be called from javascript:</p>
 177                 <pre>//get list of IDs of selected sequences
 178 public String getSelectedSequences()
 179
 180 // list of IDs of selected sequences terminated by sep or, if sep is null, '&#172;' (&amp;#172;)
 181 public String getSelectedSequences(sep)
 182
 183 // get list of selected sequences from specific alignFrame. (2.7)
 184 public String getSelectedSequencesFrom(AlignFrame alf)
 185 public String getSelectedSequencesFrom(AlignFrame alf, String sep)
 186
 187 // highlight a position in a specific sequence or a column in an alignment containing it
 188 // provide ID sequence to highlight, integer (range highlighting will be supported in future versions)
 189 // and flag indicating if position is an alignment column or given according to sequence numbering (2.7)
 190 public void highlight(String sequenceId, String position, String alignedPosition)
 191 public void highlightIn(AlignFrame alf, String sequenceId, String position, String alignedPosition)
 192
 193
 194 // select regions of the currrent alignment frame using a list of sequence ids and a list of
 195 // column numbers and ranges (with minus sign indicating start-end) (separated by default separator) (2.7)
 196 public void select(String sequenceIds, String columns)
 197 public void select(String sequenceIds, String columns, String sep)
 198 public void selectIn(AlignFrame alf, String sequenceIds, String columns)
 199 public void selectIn(AlignFrame alf, String sequenceIds, String columns, String sep)
 200
 201
 202 // get selected sequences as alignment as format with or without start-end suffix
 203 public String getSelectedSequencesAsAlignment(String format, boolean suffix)
 204
 205 // get selected sequences as alignment from given view as format with or without start-end suffix
 206 public String getSelectedSequencesAsAlignmentFrom(AlignFrame alf, String format, boolean suffix)
 207
 208 // get a separator separated list of sequence IDs reflecting the order of the current alignment (2.7)
 209 public String getAlignmentOrder();
 210 public String getAlignmentOrderFrom(AlignFrame alf);
 211 public String getAlignmentOrderFrom(AlignFrame alf, String sep);
 212
 213 // re-order the current alignment using the given list of sequence IDs separated by sep
 214 // undoName - is string to use when referring to ordering action in undo buffer
 215 // returns 'true' if alignment was actually reordered. empty string if alignment did not contain sequences.
 216 // (v2.7)
 217 public String orderBy(String order, String undoName)
 218 public String orderBy(String order, String undoName, String sep)
 219 String orderAlignmentBy(AlignFrame alf, String order, String undoName, String sep)
 220
 221
 222 // get alignment as format
 223 public String getAlignment(String format)
 224
 225 // get alignment as format with jalview
 226 // start-end sequence suffix appended
 227 public String getAlignment(String format, String suffix)
 228
 229 // get alignment displayed in alf as format
 230 public String getAlignmentFrom(AlignFrame alf, String format)
 231
 232 // get alignment displayed in alf as format
 233 // with jalview start-end sequence suffix appended
 234 public String getAlignmentFrom(AlignFrame alf, String format, String suffix)
 235
 236 // add the given features or annotation to the current alignment
 237 // if features are loaded, feature display is automatically enabled
 238 public void loadAnnotation(String annotation)
 239
 240 // add the given features or annotation to the given alignment view
 241 // if features are loaded, feature display is automatically enabled
 242 public void loadAnnotationFrom(AlignFrame alf, String annotation)
 243
 244 // parse the given string as a jalview or GFF features file and optionally enable feature display on the current alignment
 245 // (v2.8)
 246 public abstract void loadFeatures(String features, boolean autoenabledisplay)
 247
 248 // parse the given string as a jalview or GFF features file and optionally enable feature display on the given alignment
 249 // (v2.8)
 250 public abstract void loadFeaturesFrom(AlignFrame alf, String features, boolean autoenabledisplay)
 251
 252 // get the sequence features in the given format (Jalview or GFF)
 253 public String getFeatures(String format)
 254
 255 // get the sequence features in alf in the given format (Jalview or GFF)
 256 public String getFeaturesFrom(AlignFrame alf, String format)
 257
 258 // get current alignment's annotation as an annotation file
 259 public String getAnnotation()
 260
 261 // get alignment view alf's annotation as an annotation file
 262 public String getAnnotationFrom(AlignFrame alf)
 263
 264 // create a new view and return the alignFrame instance
 265 public AlignFrame newView()
 266
 267 // create a new view named name and return the alignFrame instance
 268 public AlignFrame newView(String name)
 269
 270 // create a new view on alf and return the alignFrame instance
 271 public AlignFrame newViewFrom(AlignFrame alf)
 272
 273 // create a new view named name on alf
 274 // and return the alignFrame instance
 275 public AlignFrame newViewFrom(AlignFrame alf, String name)
 276
 277 // load a new alignment
 278 // remember to store the AlignFrame object reference
 279 // if you want to manipulate the new alignment view.
 280 public AlignFrame loadAlignment(String text, String title)
 281
 282
 283 // register a javascript function to handle any alignment mouseover events
 284 // listener is name of javascript function  which will be called
 285 // with arguments [jalview.appletgui.AlignFrame,String(sequence id),
 286 // String(column in alignment), String(position in sequence)]
 287 // (v2.7)
 288 public void setMouseoverListener(String listener)
 289
 290 // register a javascript function to handle mouseover events for specific alignframe
 291 // (v2.7)
 292 public void setMouseoverListener(AlignFrame af, String listener)
 293
 294 // register a javascript function to handle alignment selection events.
 295 // Events are generated when the user completes a selection event, or when
 296 // the user deselects all selected regions.
 297 // listener is name of javascript function  that will be called with arguments
 298 //  [jalview.appletgui.AlignFrame, String(sequence set id),
 299 //   String(separator separated list of sequences which were selected),
 300 //   String(separator separated list of column ranges)]
 301 // (v2.7)
 302 public void setSelectionListener(String listener)
 303
 304 // register a selection listener for a specific alignment frame
 305 // (v2.7)
 306 public void setSelectionListener(AlignFrame af, String listener)
 307
 308 // register a javascript function to handle events normally routed
 309 // to a Jmol structure viewer.
 310 // listener is a javascript function called with several different types
 311 // of arguments, dependent on the type of structure callback event.
 312 // See jalview.javascript.MouseOverStructureListener for full details or
 313 // the embedded Jmol example.
 314 // modelSet - is a separator separated list of PDB file URIs that this viewer is handling (where position in list equals model number in Jmol).
 315 // (v2.7)
 316 public void setStructureListener(String listener, String modelSet)
 317
 318 // remove any callback using the given listener function and associated with
 319 // the given alignFrame (or null for all callbacks) (v2.7)
 320 public void removeJavascriptListener(AlignFrame af, String listener)
 321
 322 // send a mouseover message to all the alignment windows associated with the
 323 // given residue in the pdbfile (v2.7)
 324 public void mouseOverStructure(String pdbResNum, String chain, String pdbfile)
 325
 326 // bind a pdb file to a sequence in the given alignFrame - this will be searched
 327 // for sequences matching sequenceId. The PDB file in pdbFile is either the contents
 328 // of a PDB file or a URI that can be used to retrieve the file, and the pdbEntryString
 329 // is the user friendly name (or PDBID) shown in jalview's user interface.
 330 // returns true if binding was as success (v2.7)
 331 public boolean addPdbFile(AlignFrame alFrame,
 332     String sequenceId, String pdbEntryString, String pdbFile)
 333
 334 // adjust horizontal/vertical scroll in alf to the make
 335 // the given location the top left hand corner for given current view (v2.7)
 336 public void scrollViewToIn(AlignFrame alf, String topRow, String leftHandColumn)
 337
 338 // adjust horizontal scroll in alf to the make
 339 // the given location the left hand corner for given current view (v2.7)
 340 public void scrollViewToColumnIn(AlignFrame alf, String leftHandColumn)
 341
 342 // adjust horizontal/vertical scroll in alf to the make
 343 // the given location the top row for given current view (v2.7)
 344 public void scrollViewToRowIn(AlignFrame alf, String topRow)
 345
 346
 347 // return separator separated list of feature groups
 348 // on the current alignment
 349 public String getFeatureGroups()
 350
 351 // return separator separated list of feature groups on alf
 352 public String getFeatureGroupsOn(AlignFrame alf)
 353
 354 // return separator separated list of feature groups
 355 // either visible or hidden
 356 public String getFeatureGroupsOfState(boolean state)
 357
 358 // return separator separated list of feature groups
 359 // either visible or hidden on alf
 360 public String getFeatureGroupsOfStateOn(AlignFrame alf, boolean state)
 361
 362 // set the separator separated list of feature groups as
 363 // visible or hidden on the current alignment
 364 public void setFeatureGroupState(String groupList, boolean state)
 365
 366 // set the separator separated list of feature groups
 367 // as visible or hidden on alf
 368 public void setFeatureGroupStateOn(AlignFrame alf, String groupList, boolean state)
 369
 370 // helper functions
 371
 372 // Asynchronously retrieve next chunk of a large packet of data made available
 373 // for a JalviewLite event handler, or the empty string if no more data is available.
 374 // messageclass and viewId are keys used to retrieve a specific message related
 375 // to an event.
 376 // Use this in a javascript timer or GUI update thread to retrieve data without
 377 // blocking the JalviewLite applet. DO NOT USE IN THE CALLBACK THAT HANDLED THE EVENT
 378 // (v2.7)
 379 public String getJsMessage(String messageclass, String viewId)
 380
 381
 382 // convert list to a separator separated array
 383 public String arrayToSeparatorList(String[] list)
 384
 385 // get a string array from a list
 386 public String[] separatorListToArray(String list)
 387
 388 // get the current separator
 389 public String getSeparator()
 390
 391 // set the current separator
 392 public void setSeparator(String)
 393
 394 //// JalviewLite global state methods and fields
 395
 396 // return the build date as a string
 397 public static String getBuildDate()
 398
 399 // return the JalviewLite version as a string
 400 public static String getVersion()
 401
 402 // debug flag - controls output to standard out
 403 public static boolean debug
 404
 405 </pre>
 406
 407 </div>
 408
 409 <div id ="footer">
 410 <div id="innerFooter">
 411 <div id="copyright"><p>Published under <a href="http://creativecommons.org/licenses/by-sa/3.0/">CC-SA 3.0</a></p></div>
 412 <div id="cite">
 413 <p>
 414 If you use Jalview in your work, please cite this publication:
 415 </p>
 416 <br />
 417 <p>
 418 Waterhouse, A.M., Procter, J.B., Martin, D.M.A, Clamp, M. and Barton, G. J. (2009)
 419 "Jalview Version 2 - a multiple sequence alignment editor and analysis workbench"
 420 Bioinformatics 25 (9) 1189-1191 <a href="http://dx.doi.org/10.1093/bioinformatics/btp033">doi: 10.1093/bioinformatics/btp033</a>
 421 </p>
 422 </div>
 423 </div>
 424 </div>
 425
 426 <script type="text/javascript">
 427     var gaJsHost = (("https:" == document.location.protocol) ?
 428  "https://ssl." : "http://www.");
 429     document.write(unescape("%3Cscript src=\'" + gaJsHost +
 430  "google-analytics.com/ga.js\' type=\'text/javascript\'%3E%3C/script%3E"));
 431 </script>
 432 <script type="text/javascript">
 433 try{
 434     var pageTracker = _gat._getTracker("'UA-9060947-1'");
 435     pageTracker._trackPageview();
 436 } catch(err) {}
 437 </script></body>
 438 </html>