JAL-3762 check for !args || args=="" before overwriting
[jalview.git] / examples / appletParameters.html
1 <!--
2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
4  * 
5  * This file is part of Jalview.
6  * 
7  * Jalview is free software: you can redistribute it and/or
8  * modify it under the terms of the GNU General Public License 
9  * as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
10  *  
11  * Jalview is distributed in the hope that it will be useful, but 
12  * WITHOUT ANY WARRANTY; without even the implied warranty 
13  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
14  * PURPOSE.  See the GNU General Public License for more details.
15  * 
16  * You should have received a copy of the GNU General Public License along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
17  * The Jalview Authors are detailed in the 'AUTHORS' file.
18 -->
19
20
21 <div id="view_decorated" name="view_decorated"  style="margin:8px; padding:10px; border: 2px solid red; text-align:center; display:none;"><b>Click <a href="index.html#appletParameters"> here</a> to view decorated page</b></div>
22
23 <!-- content start -->
24 <h2>JalviewLite Applet Parameter Documentation</h2>
25 <p>
26 The JalviewLite applet is configured through a series of applet parameters,
27 which are described <a href="#parameters"> below</a>. Once initialised,
28 the applet can be interacted with <em>via</em> its 
29 <a href="javascript:doSubmit('jalviewLiteJs')">Javascript API</a>. 
30 </p><p><strong>Issues arising from tightening of Java Security default settings</strong><br/>JalviewLite is provided as a signed applet with 'sandbox' permissions and wildcards that allow it to be run from any website. Unfortunately, earlier versions of Java may not be compatible with these settings. </p>
31     <p>For additional deployment notes, <a href="javascript:doSubmit('appletDeployment')">see Applet Deployment</a>.</p>
32             <p><h2>Applet Parameters</h2><br/>The applet takes the following initialisation parameters.</p>
33         <a name="parameters"></a>        <table width="97%" class="borderTable" align="center" >
34           <tr> 
35             <td width="103" height="23"><strong>&lt;param name=&quot;&quot;</strong></td>
36             <td width="80" ><strong>value=&quot;&quot;&gt;</strong></td>
37             <td width="100%"><strong>Description</strong></td>
38           </tr>
39           <tr>
40           <td>permissions</td>
41           <td>sandbox</td>
42           <td><strong>This parameter is necessary, and must have the value <em>sandbox</em> to allow the JalviewLite applet to run.</strong></td>
43           </tr>
44           <tr> 
45             <td>file</td>
46             <td>fileName</td>
47             <td>The file to open, must be on same server as the applet.</td>
48           </tr>
49               <tr>
50                 <td>file2</td>
51                 <td>fileName</td>
52                 <td>A second file to open and show linked in a Split Frame
53                   view. If one file is nucleotide and the other peptide, and at
54                   least one peptide sequence matches the translation of one of the
55                   nucleotide sequences, then gaps will be inserted into the
56                   sequences in this file to match the aligned columns for
57                   corresponding positions in the primary alignment file. This
58                   parameter is ignored if enableSplitFrame is set to false (<em>since
59                     2.9</em>).
60                 </td>
61               </tr>
62             <tr> 
63             <td>enableSplitFrame</td>
64             <td>true or false (default true)</td>
65             <td>Enable or disable the display of linked cDNA and Protein alignments in a split frame (<em>since 2.9</em>).</td>
66           </tr>
67           <tr> 
68             <td>sequence1,<br>
69               sequence2,<br>
70               sequence3</td>
71             <td>sequence in (preferably) PFAM or Fasta format</td>
72             <td>The alignment can be added as a series of sequences instead of 
73               from a file.</td>
74           </tr>
75           <tr> 
76             <td>tree</td>
77             <td>fileName</td>
78             <td>Tree file in Newick format</td>
79           </tr>
80           <tr> 
81             <td>features</td>
82             <td>fileName</td>
83             <td>Jalview Features file to be applied to the alignment</td>
84           </tr>
85           <tr> 
86             <td>annotations</td>
87             <td>fileName</td>
88             <td>Jalview Annotation file will be added to the alignment</td>
89           </tr>
90           <tr> 
91             <td>jnetfile</td>
92             <td>fileName</td>
93             <td>Secondary structure predictions from a <a
94             href="http://www.compbio.dundee.ac.uk/~www-jpred/">JPred</a> Concise 
95               file will be added to the first sequence in the alignment.<br/>
96               <em>jpredfile</em> can be used interchangeably with this parameter.</td>
97           </tr>
98           <tr> 
99             <td>PDBfile(x)</td>
100             <td><p>fileName seq1 seq2 seq3</p>
101               <p>or</p>
102               <p>fileName A=seq1 B=seq2 C=seq3</p></td>
103             <td>PDB file which is to be associated with a sequence, followed by 
104               space separated list of alignment sequence ids. PDB chains can be 
105               specifed to map to particular sequence by using A=SeqA notation</td>
106           </tr>
107           <tr> 
108             <td><p>PDBSeq<br>
109                 *Not needed post Jalview 2.3, use PDBFile instead</p></td>
110             <td>SequenceId</td>
111             <td>The sequence to associate a PDB file with. Note the value is case 
112               sensitive.</td>
113           </tr>
114           <tr> 
115             <td>defaultColour</td>
116             <td> <em>One of: </em><br>
117               Clustal, Blosum62, % Identity, Hydrophobic, Zappo, Taylor, Helix 
118               Propensity, Strand Propensity, Turn Propensity, Buried Index, Nucleotide, Purine/Pyrimidine, T-Coffee Scores, RNA Helices</td>
119             <td>Default is no colour.</td>
120           </tr>
121           <tr> 
122             <td>defaultColourNuc</td>
123             <td>A colour scheme (from the list above) to apply to Nucleotide alignments</td><td>This overrides defaultColour if it is specified.</td>
124           </tr>
125           <tr> 
126             <td>defaultColourProt</td>
127             <td>A colour scheme (from the list above) to apply to Peptide alignments</td><td>This overrides defaultColour if it is specified.</td>
128           </tr>
129           <tr> 
130             <td>userDefinedColour</td>
131             <td><p><em>Example:</em><br>
132                 D,E=red; K,R,H=0022FF; c=yellow</p></td>
133             <td>Define residue colours</td>
134           </tr>
135           <tr> 
136             <td height="35">showFullId</td>
137             <td>true <em>or</em> false</td>
138             <td>if true displays start and end residue at the end of sequence 
139               Id.</td>
140           </tr>
141           <tr> 
142             <td>showAnnotation</td>
143             <td>true <em>or</em> false</td>
144             <td>If true shows the annotation panel below the alignment.</td>
145           </tr>
146           <tr> 
147             <td>showConservation</td>
148             <td>true <em>or</em> false</td>
149             <td>Default is true.</td>
150           </tr>
151           <tr> 
152             <td>showQuality</td>
153             <td>true <em>or</em> false</td>
154             <td>Default is true.</td>
155           </tr>
156           <tr> 
157             <td>showConsensus</td>
158             <td>true <em>or</em> false</td>
159             <td>Default is true.</td>
160           </tr>
161           <tr> 
162             <td>showOccupancy</td>
163             <td>true <em>or</em> false</td>
164             <td>Default is true.</td>
165           </tr>
166           <tr> 
167             <td>sortBy</td>
168             <td> Id <em>, </em> Pairwise Identity<em>, or</em> Length</td>
169             <td> Sorts the alignment on startup</td>
170           </tr>
171           <tr> 
172             <td>RGB</td>
173             <td>colour as hex string</td>
174             <td>Background colour for applet button - purely cosmetic to blend 
175               in with your web page. For orange, enter the value FF6600</td>
176           </tr>
177           <tr> 
178             <td>embedded</td>
179             <td>true <em>or</em> false</td>
180             <td>The applet is embedded in the web page, the &quot;Start Jalview&quot; 
181               button is not displayed.</td>
182           </tr>
183           <tr> 
184             <td>windowWidth</td>
185             <td>value</td>
186             <td>frame width</td>
187           </tr>
188           <tr> 
189             <td>windowHeight</td>
190             <td>value</td>
191             <td>frame height</td>
192           </tr>
193           <tr> 
194             <td>label</td>
195             <td>label text</td>
196             <td>Change text for the Launch Jalview Button</td>
197           </tr>
198           <tr> 
199             <td>wrap</td>
200             <td>true <em>or</em> false</td>
201             <td>Opens new windows in wrapped mode</td>
202           </tr>
203           <tr> 
204             <td>linkLabel_1</td>
205             <td>EMBL-EBI Search</td>
206             <td rowspan="2"><p>Right click on sequence id to see list of available 
207                 links. Any new links MUST have $SEQUENCE_ID$ as part of the linkURL_n 
208                 value. For multiple links, increment the label and url name by 
209                 1. ie <br>
210                 &lt;param name=&quot;linkLabel_2&quot; ..., <br>
211                 &lt;param name=&quot;linkUrl_2&quot;....<br>
212               </p>
213               <p>Regular expressions may also be used (<em>since Jalview 2.4</em>) to process the ID string inserted into the URL:
214               <br>$SEQUENCE_ID=/&lt;regex to extract ID&gt;/=$<br><em>Use the debug flag to check parsing and make sure that special symbols are properly escaped (particularly when generating applet tags from CGI scripts). 
215               <br>Regex URL links are also applied to the description line (since Jalview 2.4.+).</em></p></td>
216           </tr>
217           <tr> 
218             <td> <p>
219             <br>
220                 linkUrl_1<br>
221               </p></td>
222             <td><p><br>
223                 http://www.ebi.ac.uk/ebisearch/<br/>search.ebi?db=allebi&query=$SEQUENCE_ID$</p>
224                                                 </td>
225           </tr>
226           <tr> 
227             <td>showFeatureSettings</td>
228             <td>true <em>or</em> false</td>
229             <td>Shows the feature settings window when starting the applet</td>
230           </tr>
231           <tr>
232             <td>showfeaturegroups</td>
233             <td><em>separator</em> separated list of feature groups</td>
234             <td>Display the features in the given groups on the alignment</td>
235           </tr>
236           <tr>
237             <td>hidefeaturegroups</td>
238             <td><em>separator</em> separated list of feature groups</td>
239             <td>Hide the features in the given groups on the alignment
240             (will be overridden by showfeaturegroups for group names
241             found in both lists)</td>
242           </tr>
243           <tr> 
244             <td>application_url</td>
245             <td><p><em>URL of dynamic JNLP servlet,</em></p>
246               <p>http://www.jalview.org/services/launchApp</p></td>
247             <td>Launches full application with original alignment, features and 
248               annotations files used in applet</td>
249           </tr>
250           <tr>
251           <td>separator</td>
252           <td><em>non-empty separator string</em><br>default: |</td>
253           <td>string used to separate fields in list parameters (such as <em>showfeaturegroups</em>)</td>
254           </tr>
255           <tr><td>debug</td>
256           <td>true</td>
257           <td>Instruct the applet to output additional debug messages to the java console</td>
258           </tr>
259           <tr><td>nojmol</td>
260           <td>false</td>
261           <td>When set, do not try to find Jmol classes. Set this to supress URL not found errors appearing 
262           in server logs when Jmol is not available.
263           </td>
264           </tr>
265           <tr><td>showbutton</td>
266           <td>true</td>
267           <td>Show the jalview button on the page. When false, JalviewLite will open immediately.</td>
268           </tr>
269           </tr>
270                   <tr><td>sortByTree</td>
271                   <td>true or false (default is false)</td>
272                   <td>automatically sort the associated alignment view by the tree when a new tree is opened.</td>
273                   </tr>
274                   <tr>
275                    <td>showTreeBootstraps</td><td>true or false (default is true)</td><td>show or hide branch bootstraps</td>
276                         </tr>
277         <tr><td>showTreeDistances</td><td>true or false (default is true)</td><td>show or hide branch lengths</td></tr>
278         <tr><td>showUnlinkedTreeNodes</td><td>true or false (default is false)</td><td>indicate if unassociated nodes should be highlighted in the tree view</td>
279         </tr>
280           <tr><td>heightScale</td>
281           <td>1.0 or greater</td>
282           <td>Adjust the height of each cell in the alignment grid relative to the height of a character in the alignment font. (<em>since 2.5.1</em>)</td>
283           </tr>
284           <tr><td>widthScale</td>
285           <td>1.0 or greater</td>
286           <td>Adjust the width of each cell in the alignment grid relative to the width of a character in the alignment font. (<em>since 2.5.1</em>)</td>
287           </tr>
288           <tr><td>scaleProteinAsCdna</td><td>true or false (default is false)</td>
289           <td>Set true to shown protein residues the same width as their encoding codons. 
290           For use with parameter file2 when showing a split frame of cDNA and protein. (<em>since 2.9</em>)</td></tr>
291           <tr><td>centrecolumnlabels</td>
292           <td>true or false (default is false)</td>
293           <td>When true, text labels associated with a column in the alignment will be shown centered with respect to the column. (<em>since 2.4</em>)</td>
294           <tr><td>showUnconserved</td>
295           <td>true or false (default is false)</td>
296           <td>When true, only gaps and symbols different to the consensus sequence for a column will be shown. Useful for visualizing alignments exhibiting low sequence variation, where it is important to highlight mutations. (<em>since 2.5</em>)</td>
297           </tr>
298           <tr><td>upperCase</td>
299           <td><em>bold</em> or other value</td>
300           <td>Indicate a text style to apply to uppercase sequence symbols. Currently, only <strong>bold</strong> is supported.</td>
301           </tr>
302           <tr><td>automaticScrolling</td>
303           <td>true or false (default is true)</td>
304           <td>When true, alignment panels will automatically scroll to show any regions of the alignment highlighted due to javascript events or when mousing over a position in an associated structure. (<em>since 2.6</em>)</td>
305           </tr>
306           
307           <tr><td>showGroupConsensus</td>
308           <td>true or false (default is false)</td>
309           <td>When true, shows consensus annotation row for any groups on the alignment. (<em>since 2.7</em>)</td>
310           </tr>
311           
312           <tr><td>showGroupConservation</td>
313           <td>true or false (default is false)</td>
314           <td>When true, shows amino-acid property conservation annotation row for any groups on the alignment. (<em>since 2.7</em>)</td>
315           </tr>
316           <tr><td>showConsensusHistogram</td>
317           <td>true or false (default is true)</td>
318           <td>When true, shows the percentage occurence of the consensus symbol for each column as a histogram above the consensus sequence row. (<em>since 2.7</em>)</td>
319           </tr>
320           <tr><td>showSequenceLogo</td>
321           <td>true or false (default is false)</td>
322           <td>When true, shows a sequence logo above the consensus sequence (overlaid above the Consensus Histogram, if visible, with symbols coloured using the alignment's default colourscheme). (<em>since 2.7</em>)</td>
323           </tr>
324           <tr><td>normaliseSequenceLogo</td>
325           <td>true or false (default is false)</td>
326           <td>When true, all sequence logos will be normalised (all symbol stacks add up to full height of annotation row), rather than being scaled according to the fraction of symbols identical to the consensus. (<em>since 2.8</em>)</td>
327           </tr>
328           <tr><td>oninit</td>
329           <td><em>after_init()</em></td>
330           <td>name of javascript function that will be called after the jalviewLite instance has completed its initialisation. (<em>since 2.7</em>)</td>
331           </tr>
332           <tr><td>relaxedidmatch</td>
333           <td><em>true or false (default is false)</em></td>
334           <td>When true, use stem based matching to identify sequences that match features imported from a GFF or Jalview sequence features file, and for associating PDB data (passed on PDBfile parguments) with sequences (based on a given destination sequence ID). (<em>since 2.7</em>)</td>
335           </tr>
336           <tr><td>alignpdbfiles</td>
337           <td><em>true or false (default is false)</em></td>
338           <td>When true, and jalviewLite is able to use jmol as a structure viewer, attempt to show a superposition of all structures loaded onto the alignment, superimposed using the aligned regions of corresponding sequences. [experimental] (<em>since 2.7</em>)</td>
339           </tr>
340           <tr><td>externalstructureviewer</td>
341           <td><em>true or false (default is false)</em></td>
342           <td>re-route jmol colouring commands, selection and mouseover events to an external viewer using javascript callbacks. [experimental] (<em>since 2.7</em>)</td>
343           
344           </tr>
345           <tr><td>annotationcolour_max</td>
346           <td>colour name or RGB hex triplet (default is red)</td>
347           <td>Default colour used for maximum value when shading by annotation. (<em>since 2.7</em>)</td>
348           </tr>
349           <tr><td>annotationcolour_min</td>
350           <td>colour name or RGB hex triplet (default is orange)</td>
351           <td>Default colour used for minimum value when shading by annotation. (<em>since 2.7</em>)</td>
352           </tr>
353           <tr><td>jalviewhelpurl</td>
354           <td>absolute or relative url or javascript function prefixed by <em>javascript:</em> (default is http://www.jalview.org/help.html)</td>
355           <td>Optional parameter allowing modification of the default Jalview Help URL normally opened when JalviewLite's 'Help' menu item is selected. (<em>since 2.7</em>)</td>
356           </tr>
357           <tr><td>resolvetocodebase</td>
358           <td>True or False (False)</td>
359           <td>Set to true to re-instate pre-JalviewLite 2.7 behaviour where relative URLs were prepended with the applet 'codebase' rather than the current document base URL before resolution. (<em>since 2.7</em>)</td>
360           </tr>
361           <tr><td>scoreFile</td>
362           <td>file</td>
363           <td>Multiple sequences aligment scores file. Currently is supported only the T-Coffee score_ascii file format</td>
364           </tr>
365                   </table>
366                   <!-- content end -->