Configuring JS9 Site Preferences

JS9 supports a site configuration file that is read after the JavaScript variables are loaded but before JavaScript code is compiled and executed. This file allow you to tailor JS9 to meet the needs of your site without having to modify the js9.js file directly.

To support site configuration, load the JS9 json preference file file (referred to here as js9prefs.json, but it can be named anything, of course) into your web page before loading other JS9 javascript:

  <script type="text/javascript" src="js9prefs-local.js"></script>
  <script type="text/javascript" src="js9support.min.js"></script>
  <script type="text/javascript" src="js9.min.js"></script>
  ...

NB: the JS9 Node.js helper still utilizes the js9Prefs.json file. Please ensure that the properties defined in these two files are consistent.

The following example shows the current js9prefs.js file:

var JS9Prefs = {
    "globalOpts": {
        "helperType":       "nodejs",
        "helperPort":       2718,
        "helperCGI":        "./cgi-bin/js9/js9Helper.cgi",
        "debug":            0,
        "loadProxy":        true,
        "workDir":          "./tmp",
        "workDirQuota":     100,
        "dataPath":         "$HOME/Desktop:$HOME/data",
        "analysisPlugins":  "./analysis-plugins",
        "analysisWrappers": "./analysis-wrappers"
    },
    "imageOpts": {
	"colormap":         "grey",
	"scale":            "linear"
    }
}

This preference file can be used to override the default parameter settings for JS9. A look through the beginning of JS9 code will show a number of Javascript objects containing these default parameters. They all have names ending in Opts, i.e. JS9.imageOpts, JS9.analysisOpts, etc. A description of some of these objects is given below:

  1. JS9.globalOpts: this JavaScript object contains global information, including parameters concerned with the back-end services used by JS9. Many of the most useful JS9 configuration parameters are contained in this object, including mouse/touch/keyboard actions, click to focus, catalog properties, image/table default dimensions/binning, and a host of other properties.

  2. JS9.imageOpts: This JavaScript object contains initial values for parameters associated with individual images, such as: contrast, bias, whether to invert the colormap, colormap, scale, WCS system , WCS units, whether to display value/position, and whether to list regions when they change (listonchange).

  3. JS9.Regions.opts: This JavaScript object contains default values for individual regions, including the initial size of various regions, initial inner and outer radii for annuli, initial angle, etc. You can set or override properties for this object by adding them to the regionOpts object in the js9prefs.js file.

  4. JS9.menuButtonOptsArr: this JavaScript array of objects allows you to change and re-arrange which menu options are provided. If you prefix the name of a menu option with '#', that option is disabled.

  5. Module: a global JavaScript object with attributes that Emscripten-generated code calls at various points in its execution. You can set or override properties for this object by adding them to the emscriptenOpts object in the js9prefs.js file. One important case occurs when you have installed the astroemw.wasm binary file in a location other than the JS9 install directory. You would then use Emscripten's wasmBinaryFile property to specify a path to this file, relative to the JS9 install directory. For example, if the JS9 install directory and the resources directory are at the same level in the directory hierarchy:

    var JS9Prefs = {
      "emscriptenOpts": {
         "wasmBinaryFile": "../resources/js/astroemw.wasm"
      },
      # other preferences ...
    }
    
    See Emscripten's Module Object documentation for more information, and please let us know if you have problems.
In addition to the above-mentioned objects, the preference file can be used to set some internal variables. The JS9.DEBUG parameter is an example, as shown in the default preference file. Ordinarily, users need not be concerned with these variables.

When a property (e.g. scale) is added to one of the top-level objects in the JS9Prefs object (e.g. imageOpts), it generally replaces the existing value on the specified JS9 option. In the previous example, both the default colormap and default scale will be replaced by the values specified in the prefs file. Arrays and objects are also completely replaced. This, in this example, after specifying a new keyboardActions object, the entire keyboardActions object in JS9.globalOpts will be replaced by a new object containing two actions only:

var JS9Prefs = {
    "globalOpts": {
        "keyboardActions": {
            z: "zoom in",
            x: "zoom out",
      },
    }
}
In this case, however, you probably wanted to merge the new keyboard actions into the existing actions object. To perform object merging instead of replacing, add the special config object:
var JS9Prefs = {
    "config": {
        "objects": "merge"
    },
    "globalOpts": {
        "keyboardActions": {
            z: "zoom in",
            x: "zoom out",
        },
    }
}
This will result in a deep (recursive) copy being performed to merge the two new keyboardActions properties with the existing properties.
Last updated: May 8, 2021