Creating a JS9 Web Page

Adding JS9 to Your Web Page

The sample js9basics.html file shows how to add JS9 to a web page by assigning JS9 CSS classes to "div" elements. The js9multi.html web page goes further by showing how multiple instances of JS9 can be added using unique IDs.

To start, a few JavaScript and CSS files must be loaded into the web page. Ordinarily this is done in the page's header, which typically will look something like this:

  <head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=Edge;chrome=1" > 
  <meta name="viewport" content="width=device-width, initial-scale=1" >
  <link type="image/x-icon" rel="shortcut icon" href="./favicon.ico">
  <link type="text/css" rel="stylesheet" href="js9support.css">
  <link type="text/css" rel="stylesheet" href="js9.css">
  <script type="text/javascript" src="js9prefs.js"></script>
  <script type="text/javascript" src="js9support.min.js"></script>
  <script type="text/javascript" src="js9.min.js"></script>
  <script type="text/javascript" src="js9plugins.js"></script>
  </head>
The js9prefs.js file (and deprecated js9Prefs.json file) is optional. It contains a JS9Prefs object that holds various default settings for JS9, e.g. default colormap and scale for image display. Feel free to edit this file to set up your own site-specific parameters. See JS9 Site Preferences for a description of the available parameters.

Order is important: The js9prefs.js file must be loaded first. The js9support.min.js must be loaded before you load js9.min.js. You must load the plugin files after you load js9.min.js. You can simply copy the order of files as specified in the JS9 demo files.

You can, of course, arrange to have your web server gzip the javascript files, using browser-based capabilities to ungzip them automatically. The JS9 web site serves pre-compressed content, as described in the Apache Module mod_deflate page.

The text file js9support.txt is a list of the files contained in js9support.css, js9support.js, js9support.min,js, and js9plugins.js.

JS9 will not run without js9support.min.js. This file contains a number of required 3rd-party software modules, including jQuery, flot (for plotting), dhtmlwindow (for light windows), etc. It is separated from js9.min.js to optimize file caching.

JS9 will run without the js9plugins.js file, but with restricted functionality. In particular, the following core plugins are loaded from this file:

Note that the regions and mouse/touch core plugins are always loaded from within js9.min.js itself, since they are essential to almost all JS9 functionality.

In addition, the following contributed plugins are loaded from this file:

All of these files are contained in the plugins subdirectory, so you can load them individually, e.g.:

  <script type="text/javascript" src="js9support.min.js"></script>
  <script type="text/javascript" src="js9.min.js"></script>
  <script type="text/javascript" src="plugins/core/menubar.js"></script>
  <script type="text/javascript" src="plugins/core/info.js"></script>
will load only the menubar and info display plugins.

During startup, JS9 will try to load the js9worker.js file in order to create a worker process.

As of version 1.3, the cfitsio library is used to process FITS files in JS9. This support is built into js9support.js. If you are upgrading to version 1.3 from a previous version, simply remove the load of fitsy.js (or fitsy.min.js) from your web page to start using cfitsio.

Instances of JS9 are placed on a web page by assigning JS9 classes to ordinary "div" elements. The two important JS9 classes are:

Thus, for example, to place a menubar on top of a JS9 display, use:
  <div class="JS9Menubar">
  <div class="JS9">

You also can use these classes:

NB: all of these secondary windows can be displayed as light windows using the appropriate View menu options. Light windows can moved around on the page. Also note that if a window is declared statically in a page, it will not be made available in the View menu.

Placement of JS9 div elements should follow standard web page rules and constraints. This means that div elements can be placed in any order to create different graphical views. For example, the js9basics.html page places the menubar above the image display, in keeping with the traditional layout of DS9. The entire JS9 construct is placed in a data cell of a table, next to a data cell containing data URLs.

The JS9 display has a default width and height of 512x512. You can change this by adding data-width and data-height attributes to the div. For example, to create a display of size 256x256, use:

  <div class="JS9" data-width="256px" data-height="256px">
The data-width and data-height attributes can be applied to the other JS9 divs (which can be especially useful for the menubar). Thus, for example, if you shorten the width of the Js9 display, you might also want to shorten the width of the menubar:
  <div class="JS9Menubar" data-width="256px" data-height="48px">

Multiple instances of JS9 can be added to a single web page. This is done by giving each JS9 div element a unique ID. In order to tie otherwise separate JS9 components together, the IDs should be specified as follows:

An example of how to define multiple instances of JS9 is found in the js9multi.html file. Two DS9 instances are defined, having IDs of "JS9" (the default) and "myJS9". When "myJS9" is the display ID, "myJS9-Menubar" specifies the associated menu bar and "myJS9Console" specifies the associated console.

The ID is not required if there is only one JS9 instance on the page, since it defaults to "JS9". However, if your site needs to communicate with clients using the js9 script for external communication, you can differentiate between clients loading the same JS9-enabled web page by supplying a unique ID when the JS9 page is served.

The js9.css file contains CSS directives for various parts of JS9. These can be modified (or overwritten) as needed, subject to ordinary CSS rules. In general, we recommend overwriting CSS rules by loading a site-specific CSS file after the js9.css file. This makes updating much easier.

One CSS directive worth noting is the JS9Button class, which defines the look and feel of the buttons found on the Menubar, inside plugins, etc. The JS9Button class currently is set to the JS9ClassicButton class, which mimics Mac OSX buttons in shape and color. An alternative is the JS9FlatButton class displays a flat blue button that highlights when the mouse hovers and darkens when clicked. A lightblue background is often used with this class of button. JS9 also defines a JS9BorderButton which has a blue colored border and a white background. The JS9 Menubar supports two data properties to make it easier to change the button and background:

The JS9 Size Demo displays different button styles.

One Menubar to Rule Them All

By default, each menubar controls one JS9 display. You can, however, create a menubar that controls multiple displays, so that a given menu selection is applied to each display. This is done by creating a menubar div with two special characteristics: For example, to control two JS9 displays:
  <div class="JS9Menubar" id="SUPERMENU_" data-displays="JS9,myJS9"></div>
As shown, the data-displays attribute is a comma-separated list of JS9 display ids to control with this super-menu.

A super-menu acts like an ordinary menu, except that it will control all of the JS9 displays in the list. Thus, you can change multiple colormaps at once, run analysis on all displays, etc.

You still can define a menubar for each display in order to control them individually. Since the actions of an ordinary menu and a super-menu can be mixed for a given JS9 display, the displays will not always be perfectly synchronized. In such a case, the super-menu's selected values will be tied to the first display in the data-displays list. For example, if the first display listed is at zoom 2 and the second is at zoom 4, the Zoom menu will show a current zoom value of 2.

Finally, note that regions created with a super-menu are not tied to one another across displays. We will tie together events across displays in a future release.

Adding Server-side Analysis Tasks to Your Web Page

Server-side JS9 analysis tasks can be executed using the Analysis menu, but they also can be executed directly from the web page using HTML elements (buttons, forms, etc.) To do this, a web page author simply creates the web interface and calls either JS9.RunAnalysis() (for buttons, menus, etc.) or JS9.SubmitAnalysis() (for forms). These are described in the Local Tasks web page.

Adding Local Analysis Tasks to Your Web Page

JS9 also supports the ability to perform local analysis, i.e., analysis tasks defined and executed right on your web page, rather than being executed by a back-end server. This is accomplished by offering access to the image data and region information via a public JS9 API. See the Local Tasks for more information.

Adding JS9 Display Windows Dynamically

JS9 display windows can be created dynamically using the JS9 Public API call JS9.LoadWindow(). You can create a light window to hold a new JS9 display on the same page or you can create an entirely separate pop-up window. See the JS9 Public API for more information.

Adding Data Files to a Web Page

Data file links are added to a web page by supplying URLs that call the JS9.Load() routine. You also can load images automatically when the web page loads using the JS9.Preload() routine. See: Adding Data Files To a Web Page for more information.

Last updated: April 16, 2017