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