PageRenderTime 43ms CodeModel.GetById 33ms app.highlight 6ms RepoModel.GetById 2ms app.codeStats 0ms

/static/gmaj/docs/gmaj_install.html

https://bitbucket.org/cistrome/cistrome-harvard/
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&lt;applet code="edu.psu.bx.gmaj.MajApplet.class"
108        archive="gmaj.jar"
109        width="200" height="30"&gt;
110&lt;param name=paramfile   value="/java/gmaj/alpha/demo.gmaj"&gt;
111&lt;param name=bundle      value="/java/gmaj/alpha/demo.zip"&gt;
112&lt;param name=buttonlabel value="Alpha-globin"&gt;
113&lt;param name=nobutton    value="false"&gt;
114&lt;param name=initzoom    value="mouse 110000 147000"&gt;
115&lt;param name=posturl     value="/cgi-bin/save-posted-file.pl"&gt;
116&lt;param name=urlpause    value="100"&gt;
117&lt;param name=debug       value="false"&gt;
118&lt;i&gt;Your browser is not responding to the &amp;lt;applet&amp;gt; tag.&lt;/i&gt;
119&lt;/applet&gt;
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>&lt;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>