galaxy/static/gmaj/docs/gmaj_install.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
	"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Installing Gmaj</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="stylesheet" type="text/css" href="gmaj.css">
</head>
<body>
<p class=vvlarge>
<h2>Installing Gmaj</h2>
<p class=vvlarge>
TABLE OF CONTENTS
<p class=small>
<ul class=notop>
<li><a href="#intro">Introduction</a>
<li><a href="#install">Installation</a>
<li><a href="#data">Data Files</a>
<li><a href="#page">Web Page</a>
</ul>
<p class=vlarge>

<h3><a name="intro">Introduction</a></h3>
<p>
Gmaj can be run in two different modes: as a stand-alone
application (for viewing local data files yourself) or as an
applet over the world-wide web (to display your data on a server
for viewing by others).  Both forms of the program are
distributed together, so the initial download and unpacking
instructions are the same.  Setting it up as an applet, however,
requires some additional steps: ensuring that Gmaj and the data
files you want to display are accessible to your web server, and
building a web page to run the applet.
<p>

<h3><a name="install">Installation</a></h3>
<p>
Gmaj is available for download as a compressed zip archive,
<code><a href="http://globin.bx.psu.edu/dist/gmaj/gmaj.zip"
>gmaj.zip</a></code>.  This was created with the Java jar tool,
but the format is compatible with PKUnzip and many other unzip
programs.  Unzipping the archive will produce
<code>gmaj.jar</code> (a jar file containing the program itself)
and a <code>docs</code> subdirectory containing some
documentation files in HTML format.  If your unzipper program
does not preserve the directory structure and complete file
names from the archive, you may need to move and/or rename the
documentation files manually in order for the "Help - Manual"
function to work.  Note that the <code>gmaj.jar</code> file does
not need a second round of unzipping -- Java will access it
"as is".  If you are setting up Gmaj as an applet, be sure to
unzip the archive in a directory/folder that will be accessible
to your web server, e.g., a new <code>gmaj</code> directory
somewhere in the server's document space.
<p>
If you are running Gmaj in stand-alone mode, you will also need
to have Java installed on your computer.  For applets, the
server does not need Java but the end user does; you may want to
mention this on your Gmaj web page.  In both cases <b>Java 1.3
or higher</b> is required, and for best compatibility
<a href="http://java.com/en/download/manual.jsp">Sun's JRE</a>
(or JDK) is recommended.
<p>
For stand-alone mode, that's all there is to the installation;
you will specify different start-up parameters for Gmaj each time
you run it (see <a href="gmaj_help.html"
>Starting and Running Gmaj</a>).  The remaining sections on this
page apply only to applet setup.
<p>

<h3><a name="data">Data Files</a></h3>
<p>
In addition to the alignment data, Gmaj can display several
kinds of annotations, including genes/exons, repeats, linkbars,
color underlays, text highlights, and reconstruction scores for
ancestral sequences, with a meta-data parameters file to tie
them all together.  For detailed descriptions of these files and
their format requirements, please see <a href="gmaj_input.html"
>Input Files for Gmaj</a>.
<p>
When setting up Gmaj as an applet, the data files must be
accessible to your web server.  Also, due to Java security
restrictions, they must all be located on the same server as the
<code>gmaj.jar</code> file, because an applet is normally only
allowed to contact the same server it was loaded from.  We find
it convenient to group the files for each invocation (e.g., each
genomic region) in a separate subdirectory of the
<code>gmaj</code> directory.  It is also possible to bundle them
into a single zipped data file for each invocation, which eases
both storage requirements and download time (discussed further
in <a href="gmaj_input.html">Input Files for Gmaj</a>).
<p>

<h3><a name="page">Web Page</a></h3>
<p>
The last step in setting up the applet is to create a web page on
your server that invokes it with the appropriate parameters for
loading your data files.  The applet normally appears as a labeled
button that opens a Gmaj window when the user clicks on it; thus
you can have several buttons on the same page, each set up to
display a different set of data.  The basic format of the HTML
code looks like this:

<blockquote>
<pre>
&lt;applet code="edu.psu.bx.gmaj.MajApplet.class"
        archive="gmaj.jar"
        width="200" height="30"&gt;
&lt;param name=paramfile   value="/java/gmaj/alpha/demo.gmaj"&gt;
&lt;param name=bundle      value="/java/gmaj/alpha/demo.zip"&gt;
&lt;param name=buttonlabel value="Alpha-globin"&gt;
&lt;param name=nobutton    value="false"&gt;
&lt;param name=initzoom    value="mouse 110000 147000"&gt;
&lt;param name=posturl     value="/cgi-bin/save-posted-file.pl"&gt;
&lt;param name=urlpause    value="100"&gt;
&lt;param name=debug       value="false"&gt;
&lt;i&gt;Your browser is not responding to the &amp;lt;applet&amp;gt; tag.&lt;/i&gt;
&lt;/applet&gt;
</pre>
</blockquote>

This particular fragment is based on the alpha-globin example
from our server; naturally you need to replace the values with
your own file URLs, button label, etc.  A few things to note:
<ul>
<li>	If the <code>gmaj.jar</code> file is not in the same
	directory as your web page, you'll need to supply the path
	to it in the <code>archive</code> attribute.
<li>	The <code>width</code> and <code>height</code> attributes
	are for the button, not the Gmaj windows.
<li>	You can specify either or both of the first two
	<code>&lt;param name=...</code> lines
	(<code>paramfile</code> and <code>bundle</code>); the
	others are optional.
<li>	If the <code>nobutton</code> parameter is set to
	<code>"true"</code>, Gmaj will proceed to open its window
	immediately instead of displaying a start button.
<li>	The <code>initzoom</code> parameter specifies an initial
	zoom setting to be applied when the window opens.  The user
	can still invoke the Unzoom or Set Zoom features
	interactively to see the entire sequence range.  The
	sequence name must match one of the names from the alignment
	file(s), and the endpoints must include the offset (if any)
	for that sequence from the parameters file.  To specify the
	reference sequence without a zoom region, use <code>-1</code>
	for both endpoints.
<li>	The <code>posturl</code> parameter designates a URL on your
	server where exported alignments should be sent.  By default
	the Export feature is not available in applet mode, because
	applets generally can't write to the user's local disk due
	to security restrictions.  However, by specifying this
	parameter you can enable the applet to send the exported data
	to your server instead (typically a CGI script).  The output
	is sent via an HTTP POST request using the MIME protocol for
	web forms; currently for applets the export file format is
	always MAF, and the filename is always
	<code>Gmaj_output.maf</code>.
<pre class=smallfont>
  Content-Type: multipart/form-data; boundary=______AaB03x

  --______AaB03x
  Content-Disposition: form-data; name=file_data; filename=Gmaj_output.maf
  Content-Type: application/octet-stream

  [MAF file contents, in plain ASCII with platform-dependent line breaks]

  --______AaB03x--
</pre>
<li>	The <code>urlpause</code> parameter specifies how many
	milliseconds the program should pause before retrieving each
	file from a URL, in order to avoid overloading your server.
<li>	If the <code>debug</code> parameter is set to
	<code>"true"</code>, Gmaj will print a few extra warning
	messages in the browser's Java console if certain problems
	occur.  Normally you won't need this, as it is mainly for
	development purposes.
<li>	To create several buttons, just repeat this entire block of
	code (with new parameter values, of course).
</ul>
<p>

<p class=vvlarge>
<hr>
<i>Cathy Riemer, June 2008</i>
</body>
</html>