/static/gmaj/docs/gmaj_install.html
HTML | 187 lines | 177 code | 10 blank | 0 comment | 0 complexity | d646400038dadc731a3b53d57b917f72 MD5 | raw file
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "http://www.w3.org/TR/html4/loose.dtd"> 3<html> 4<head> 5<title>Installing Gmaj</title> 6<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 7<meta http-equiv="Content-Style-Type" content="text/css"> 8<link rel="stylesheet" type="text/css" href="gmaj.css"> 9</head> 10<body> 11<p class=vvlarge> 12<h2>Installing Gmaj</h2> 13<p class=vvlarge> 14TABLE OF CONTENTS 15<p class=small> 16<ul class=notop> 17<li><a href="#intro">Introduction</a> 18<li><a href="#install">Installation</a> 19<li><a href="#data">Data Files</a> 20<li><a href="#page">Web Page</a> 21</ul> 22<p class=vlarge> 23 24<h3><a name="intro">Introduction</a></h3> 25<p> 26Gmaj can be run in two different modes: as a stand-alone 27application (for viewing local data files yourself) or as an 28applet over the world-wide web (to display your data on a server 29for viewing by others). Both forms of the program are 30distributed together, so the initial download and unpacking 31instructions are the same. Setting it up as an applet, however, 32requires some additional steps: ensuring that Gmaj and the data 33files you want to display are accessible to your web server, and 34building a web page to run the applet. 35<p> 36 37<h3><a name="install">Installation</a></h3> 38<p> 39Gmaj is available for download as a compressed zip archive, 40<code><a href="http://globin.bx.psu.edu/dist/gmaj/gmaj.zip" 41>gmaj.zip</a></code>. This was created with the Java jar tool, 42but the format is compatible with PKUnzip and many other unzip 43programs. Unzipping the archive will produce 44<code>gmaj.jar</code> (a jar file containing the program itself) 45and a <code>docs</code> subdirectory containing some 46documentation files in HTML format. If your unzipper program 47does not preserve the directory structure and complete file 48names from the archive, you may need to move and/or rename the 49documentation files manually in order for the "Help - Manual" 50function to work. Note that the <code>gmaj.jar</code> file does 51not need a second round of unzipping -- Java will access it 52"as is". If you are setting up Gmaj as an applet, be sure to 53unzip the archive in a directory/folder that will be accessible 54to your web server, e.g., a new <code>gmaj</code> directory 55somewhere in the server's document space. 56<p> 57If you are running Gmaj in stand-alone mode, you will also need 58to have Java installed on your computer. For applets, the 59server does not need Java but the end user does; you may want to 60mention this on your Gmaj web page. In both cases <b>Java 1.3 61or higher</b> is required, and for best compatibility 62<a href="http://java.com/en/download/manual.jsp">Sun's JRE</a> 63(or JDK) is recommended. 64<p> 65For stand-alone mode, that's all there is to the installation; 66you will specify different start-up parameters for Gmaj each time 67you run it (see <a href="gmaj_help.html" 68>Starting and Running Gmaj</a>). The remaining sections on this 69page apply only to applet setup. 70<p> 71 72<h3><a name="data">Data Files</a></h3> 73<p> 74In addition to the alignment data, Gmaj can display several 75kinds of annotations, including genes/exons, repeats, linkbars, 76color underlays, text highlights, and reconstruction scores for 77ancestral sequences, with a meta-data parameters file to tie 78them all together. For detailed descriptions of these files and 79their format requirements, please see <a href="gmaj_input.html" 80>Input Files for Gmaj</a>. 81<p> 82When setting up Gmaj as an applet, the data files must be 83accessible to your web server. Also, due to Java security 84restrictions, they must all be located on the same server as the 85<code>gmaj.jar</code> file, because an applet is normally only 86allowed to contact the same server it was loaded from. We find 87it convenient to group the files for each invocation (e.g., each 88genomic region) in a separate subdirectory of the 89<code>gmaj</code> directory. It is also possible to bundle them 90into a single zipped data file for each invocation, which eases 91both storage requirements and download time (discussed further 92in <a href="gmaj_input.html">Input Files for Gmaj</a>). 93<p> 94 95<h3><a name="page">Web Page</a></h3> 96<p> 97The last step in setting up the applet is to create a web page on 98your server that invokes it with the appropriate parameters for 99loading your data files. The applet normally appears as a labeled 100button that opens a Gmaj window when the user clicks on it; thus 101you can have several buttons on the same page, each set up to 102display a different set of data. The basic format of the HTML 103code looks like this: 104 105<blockquote> 106<pre> 107<applet code="edu.psu.bx.gmaj.MajApplet.class" 108 archive="gmaj.jar" 109 width="200" height="30"> 110<param name=paramfile value="/java/gmaj/alpha/demo.gmaj"> 111<param name=bundle value="/java/gmaj/alpha/demo.zip"> 112<param name=buttonlabel value="Alpha-globin"> 113<param name=nobutton value="false"> 114<param name=initzoom value="mouse 110000 147000"> 115<param name=posturl value="/cgi-bin/save-posted-file.pl"> 116<param name=urlpause value="100"> 117<param name=debug value="false"> 118<i>Your browser is not responding to the &lt;applet&gt; tag.</i> 119</applet> 120</pre> 121</blockquote> 122 123This particular fragment is based on the alpha-globin example 124from our server; naturally you need to replace the values with 125your own file URLs, button label, etc. A few things to note: 126<ul> 127<li> If the <code>gmaj.jar</code> file is not in the same 128 directory as your web page, you'll need to supply the path 129 to it in the <code>archive</code> attribute. 130<li> The <code>width</code> and <code>height</code> attributes 131 are for the button, not the Gmaj windows. 132<li> You can specify either or both of the first two 133 <code><param name=...</code> lines 134 (<code>paramfile</code> and <code>bundle</code>); the 135 others are optional. 136<li> If the <code>nobutton</code> parameter is set to 137 <code>"true"</code>, Gmaj will proceed to open its window 138 immediately instead of displaying a start button. 139<li> The <code>initzoom</code> parameter specifies an initial 140 zoom setting to be applied when the window opens. The user 141 can still invoke the Unzoom or Set Zoom features 142 interactively to see the entire sequence range. The 143 sequence name must match one of the names from the alignment 144 file(s), and the endpoints must include the offset (if any) 145 for that sequence from the parameters file. To specify the 146 reference sequence without a zoom region, use <code>-1</code> 147 for both endpoints. 148<li> The <code>posturl</code> parameter designates a URL on your 149 server where exported alignments should be sent. By default 150 the Export feature is not available in applet mode, because 151 applets generally can't write to the user's local disk due 152 to security restrictions. However, by specifying this 153 parameter you can enable the applet to send the exported data 154 to your server instead (typically a CGI script). The output 155 is sent via an HTTP POST request using the MIME protocol for 156 web forms; currently for applets the export file format is 157 always MAF, and the filename is always 158 <code>Gmaj_output.maf</code>. 159<pre class=smallfont> 160 Content-Type: multipart/form-data; boundary=______AaB03x 161 162 --______AaB03x 163 Content-Disposition: form-data; name=file_data; filename=Gmaj_output.maf 164 Content-Type: application/octet-stream 165 166 [MAF file contents, in plain ASCII with platform-dependent line breaks] 167 168 --______AaB03x-- 169</pre> 170<li> The <code>urlpause</code> parameter specifies how many 171 milliseconds the program should pause before retrieving each 172 file from a URL, in order to avoid overloading your server. 173<li> If the <code>debug</code> parameter is set to 174 <code>"true"</code>, Gmaj will print a few extra warning 175 messages in the browser's Java console if certain problems 176 occur. Normally you won't need this, as it is mainly for 177 development purposes. 178<li> To create several buttons, just repeat this entire block of 179 code (with new parameter values, of course). 180</ul> 181<p> 182 183<p class=vvlarge> 184<hr> 185<i>Cathy Riemer, June 2008</i> 186</body> 187</html>