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