1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
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
6 * This file is part of Jalview.
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.
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.
17 * You should have received a copy of the GNU General Public License along with Jalview. If not, see <http://www.gnu.org/licenses/>.
20 <TITLE>Javascript API</TITLE>
21 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
23 <link href="css/reset.css" rel="stylesheet" type="text/css" />
24 <link href="css/style.css" rel="stylesheet" type="text/css" />
27 <link rel="stylesheet" type="text/css" href="css/ie6.css" />
31 <link rel="stylesheet" type="text/css" href="css/ie7.css" />
35 <script type="text/javascript">
48 if(ddmenuitem) ddmenuitem.style.visibility = 'hidden';
50 // get new layer and show it
51 ddmenuitem = document.getElementById(id);
52 ddmenuitem.style.visibility = 'visible';
58 if(ddmenuitem) ddmenuitem.style.visibility = 'hidden';
64 closetimer = window.setTimeout(mclose, timeout);
68 function mcancelclosetime()
72 window.clearTimeout(closetimer);
77 // close layer when click-out
78 document.onclick = mclose;
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);})();
94 <div id="logo"><a href="http://www.jalview.org" title="Home"></a></div>
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>
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>
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>
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>
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>
137 <li><a href="http://www.jalview.org/download" class="download-right">Download</a></li>
139 <div style="clear:both"></div>
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 JalviewLite applets</a></li>
158 <div id="content" class="content">
161 <!-- content start -->
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>.
168 <li>Unfortunately Javascript - Java communication is not possible
169 using Internet Explorer or Opera on Macs. Please use Safari or
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.
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()
187 // list of IDs of selected sequences terminated by sep or, if sep is null, '¬' (&#172;)
188 public String getSelectedSequences(sep)
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)
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)
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)
209 // get selected sequences as alignment as format with or without start-end suffix
210 public String getSelectedSequencesAsAlignment(String format, boolean suffix)
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)
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);
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.
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)
229 // get alignment as format
230 public String getAlignment(String format)
232 // get alignment as format with jalview
233 // start-end sequence suffix appended
234 public String getAlignment(String format, String suffix)
236 // get alignment displayed in alf as format
237 public String getAlignmentFrom(AlignFrame alf, String format)
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)
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)
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)
251 // parse the given string as a jalview or GFF features file and optionally enable feature display on the current alignment
253 public abstract void loadFeatures(String features, boolean autoenabledisplay)
255 // parse the given string as a jalview or GFF features file and optionally enable feature display on the given alignment
257 public abstract void loadFeaturesFrom(AlignFrame alf, String features, boolean autoenabledisplay)
259 // get the sequence features in the given format (Jalview or GFF)
260 public String getFeatures(String format)
262 // get the sequence features in alf in the given format (Jalview or GFF)
263 public String getFeaturesFrom(AlignFrame alf, String format)
265 // get current alignment's annotation as an annotation file
266 public String getAnnotation()
268 // get alignment view alf's annotation as an annotation file
269 public String getAnnotationFrom(AlignFrame alf)
271 // create a new view and return the alignFrame instance
272 public AlignFrame newView()
274 // create a new view named name and return the alignFrame instance
275 public AlignFrame newView(String name)
277 // create a new view on alf and return the alignFrame instance
278 public AlignFrame newViewFrom(AlignFrame alf)
280 // create a new view named name on alf
281 // and return the alignFrame instance
282 public AlignFrame newViewFrom(AlignFrame alf, String name)
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)
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)]
295 public void setMouseoverListener(String listener)
297 // register a javascript function to handle mouseover events for specific alignframe
299 public void setMouseoverListener(AlignFrame af, String listener)
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)]
309 public void setSelectionListener(String listener)
311 // register a selection listener for a specific alignment frame
313 public void setSelectionListener(AlignFrame af, String listener)
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).
323 public void setStructureListener(String listener, String modelSet)
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)
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)
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)
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)
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)
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)
354 // return separator separated list of feature groups
355 // on the current alignment
356 public String getFeatureGroups()
358 // return separator separated list of feature groups on alf
359 public String getFeatureGroupsOn(AlignFrame alf)
361 // return separator separated list of feature groups
362 // either visible or hidden
363 public String getFeatureGroupsOfState(boolean state)
365 // return separator separated list of feature groups
366 // either visible or hidden on alf
367 public String getFeatureGroupsOfStateOn(AlignFrame alf, boolean state)
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)
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)
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
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
386 public String getJsMessage(String messageclass, String viewId)
389 // convert list to a separator separated array
390 public String arrayToSeparatorList(String[] list)
392 // get a string array from a list
393 public String[] separatorListToArray(String list)
395 // get the current separator
396 public String getSeparator()
398 // set the current separator
399 public void setSeparator(String)
401 //// JalviewLite global state methods and fields
403 // return the build date as a string
404 public static String getBuildDate()
406 // return the JalviewLite version as a string
407 public static String getVersion()
409 // debug flag - controls output to standard out
410 public static boolean debug
418 </div> <!-- end content div -->
420 </div> <!-- content -->
421 </div> <!-- pagewrap -->
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>
427 If you use Jalview in your work, please cite this publication:
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>