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