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