Development

These are the guidelines for code development in the lsst_visualization/frontend repository.

Table Of Contents

• Branches
• LSST Frontend
  • Namespaces
    • LSST
    • LSST.UI
  • Files
    • box.js
    • chart.js
    • cmd.js
    • lsst.js
    • region.js
    • settings.js
    • state.js
    • ui.js
    • utility.js
    • viewer.js
• Terminal
• Toolbar

---

Branches

This section describes the structure of our GitHub branch system.

Development (default branch)

This is our main development branch. All finished issues and hotfixes will merged with this branch. This code will be visible on this web address.

THIS IS NOT A STABLE BRANCH. However, this is the most updated branch, and will have all newest features. The main use for this branch will be to test the new features and find bugs. All bugs, feature requests, ideas for design changes, or anything else should be reported here.

Stable

This branch is our most stable branch. This code will be visible on this web address. Being the stable branch does not mean it is bug free, or can't be changed. Any bugs or changes should be reported here.

Issues

Any branches directly related to an issue should be branched off from the development branch. These branches should be created with the following name scheme:
    i/Issue#_SmallDescription
    (ie i/79_DefFontSize)

Hotfixes

Any branches not directly related to an issue should be branched off from the development branch. These branches should be created with the following name scheme:
    h/Description
    (ie h/TerminalSyntaxError)

---

LSST Frontend

This section describes the code structure of our frontend code.

---

Namespaces

This section describes the namespaces used in the LSST frontend.

LSST

This is our top level namespace. It contains our global state variable, which keeps track of various pieces of information. See lsst.js for the definition of LSST.state.

LSST.UI

This namespace contains anything related to the user interface of the frontend. This includes boxes, viewers, charts, and regions.

---

Files

This section describes each files' purpose in the LSST frontend.

box.js

This file contains code related to our UI boxes.

The classes defined in this file are:

• LSST.UI.BoxText: Helper class to easily display (label, value) data.
• LSST.UI.BoxUI: Helper class that controls the HTML/CSS UI of each box.
• LSST.UI.Box: The main interface to a box. Inherits from LSST.UI.UIElement.

Box API:

• LSST.UI.Box()
  • Description: Creates a box and adds it to the main display.
  • Parameters:
    • options [Object]: Describes the box to create.
      • name [String]: The name of this box.
  • Return: The newly created box.
• LSST.UI.Box.clear()
  • Description: Clears the text from this box, and calls the onClear callbacks.
  • Parameters: None.
  • Return: None.
• LSST.UI.Box.destroy()
  • Description: Destroys this box and removes it from the web page.
  • Parameters: None.
  • Return: None.
• LSST.UI.Box.onClear()
  • Description: Adds a one-time callback function to be called when the box is cleared.
  • Parameters:
    • f (Function): The callback function.
  • Return: None.
• LSST.UI.Box.maximize()
  • Description: Maximizes this box.
  • Parameters: None.
  • Return: None.
• LSST.UI.Box.minimize()
  • Description: Minimizes this box.
  • Parameters: None.
  • Return: None.
• LSST.UI.Box.setText()
  • Description: Sets the text of this box.
  • Parameters:
    • textArray [Array]: An array of text entries to display. Each element is displayed on a new line, and can be of type LSST.UI.BoxText, String, or Number.
      There are also special strings, surrounded with colons (':'). The possible special strings are:
      • line-type (ie :line-solid:)
  • Return: None.
• LSST.UI.Box.Deserialize() (Static)
  • Description: Deserializes a byte stream (returned from LSST.UI.Box.Serialize) into a new box.
  • Parameters:
    • s [String]: The byte stream to deserialize.
  • Return: The newly created box.
• LSST.UI.Box.Serialize() (Static)
  • Description: Serializes a box to a byte stream.
  • Parameters:
    • box [LSST.UI.Box]: The box to serialize.
  • Return: The serialized byte stream.

---

chart.js

This file contains code related to our UI charts. The supported charts are: histograms.

The classes defined in this file are:

• LSST.UI.Histogram: The main interface to a histogram. Inherits from LSST.UI.UIElement.

Histogram API:

• LSST.UI.Histogram.destroy()
  • Description: Destroys this histogram and removes it from the web page.
  • Parameters: None.
  • Returns: None.
• LSST.UI.Histogram.FromJSONFile()
  • Description: Creates a histogram from a JSON file description.
  • Parameters:
    • file [String]: The filename of the JSON description.
  • Returns: The newly created histogram.
• LSST.UI.Histogram.FromJSONString()
  • Description: Creates a histogram from a JSON formatted string.
  • Parameters:
    • data [String]: The JSON formatted string describing this histogram.
  • Returns: The newly created histogram.
• LSST.UI.Histogram.FromObject()
  • Description: Creates a histogram from a object descriptor.
  • Parameters:
    • desc [Object]: An object describing the histogram.
      • title [String]: The title of the histogram (not required, defaults to "Histogram").
      • xAxis [String]: A label for the x-axis.
      • data [Object]: The data to display in the histogram. See this firefly histogram example on how to format.
  • Returns: The newly created histogram.

---

cmd.js

This file handles terminal initialization, and contains all command and viewer command functions.

All of the possible commands loaded by the terminal are defined in command.json. Each command's callback function must have the same name as the command name. Each command callback is a part of the cmds object, which maps command names to callback functions (for instance, cmds['average_pixel'] corresponds to the command 'average_pixel').

The viewer commands are commands that can be executed through the firefly viewer interface (namely those with region parameters). The variable viewerCommandParameterForms maps viewer command id's to the HTML form to display.

Communicating with the backend

To invoke a backend function, one must call executeBackendFunction:

• Parameters:
  • nameOfTask [String]: The name of the backend task to execute.
  • viewer [LSST.UI.Viewer]: A reference to the target viewer.
  • params [Anything]: The parameters to send to the backend task. Can either be a single value, or an object containing multiple properties, depends on the format of the backend task.
  • onFulfilled [Function]: A callback function to execute when the backend task is properly executed.
  • onRejected [Function]: A callback function to execute when the backend task failed to execute.

---

lsst.js

This file contains the API for our top level namespace, LSST, as well as utility JavaScript OOP functions.

API:

• LSST.extend
  • Description: Extends the LSST namespace into a sub-namespace.
  • Parameters:
    • namespace [String]: The namespace to add to LSST.
  • Returns: The namespace.
• LSST.inherits
  • Description: Makes a class inherit from a different class.
  • Parameters:
    • sub [Class]: The sub (child) class.
    • base [Class]: The base (parent) class.
  • Returns: None.

---

region.js

This file contains our region definitions and API.

The classes defined in this file are:

• LSST.UI.Region: A utility class for parsing variable region types.
• LSST.UI.Rect: Represents a rectangular region.
• LSST.UI.Circ: Represents a circular region.

Region API:

• LSST.UI.Rect()
  • Description: Creates a rectangular region.
  • Parameters:
    • x1 [Number]: The first x coordinate
    • y1 [Number]: The first y coordinate
    • x2 [Number]: The second x coordinate
    • y2 [Number]: The second y coordinate
  • Returns: The newly create rectangular region.
• LSST.UI.Circ()
  • Description: Creates a circular region.
  • Parameters:
    • originX [Number]: The x coordinate of the circle's origin.
    • originY [Number]: The y coordinate of the circle's origin.
    • radius [Number]: The radius of the circle.
  • Returns: The newly created circular region.
• LSST.UI.Rect.toString(), LSST.UI.Circ.toString()
  • Parameters: None.
  • Returns: The stringified version of this region.
• LSST.UI.Rect.toDS9(), LSST.UI.Circ.toDS9()
  • Parameters: None.
  • Returns: The DS9 style string of this region.
• LSST.UI.Rect.toBoxText(), LSST.UI.Circ.toBoxText()
  • Parameters: None.
  • Returns: An object style of this region, readable by the backend.
• LSST.UI.Rect.toCmdLineFormat(), LSST.UI.Circ.toCmdLineFormat()
  • Parameters: None.
  • Returns: An string style of this region, as if entered in the terminal.
• LSST.UI.Rect.toCmdLineArrayFormat(), LSST.UI.Circ.toCmdLineArrayFormat()
  • Parameters: None.
  • Returns: An array style of this region, as if returned from the terminal.
• LSST.UI.Region.Parse, LSST.UI.Rect.Parse(), LSST.UI.Circ.Parse()
  • Parameters:
    • region [Array]: The array version of the region, to parse.
  • Returns: The region, as defined by the parameter.

---

settings.js

This file contains code related to the settings of anything.

---

state.js

This file defines the global state variable, LSST.state.

The LSST.state variable contains the following properties:

• boxes [LSST.UI.UIElementList]: A list of all of the boxes currently in use.
• viewers [LSST.UI.UIElementList]: A list of all of the viewers currently in use.
• uvControls [LSST.UI.UIElementList]: A list of all of the update viewer controls currently in use (one for each viewer).
• term [jQuery object]: A handle to the main terminal.
• defaults [Object]: The defaults, as used by the terminal.
  • viewer [String]: The ID of the default viewer.
  • box [String]: The ID of the default box.

---

ui.js

This file contains definitions for the basic UI elements.

The classes defined in this file are:

• LSST.UI.UIElement: The base class for all UI elements.
• LSST.UI.UIElementList: A specialized list class for UI elements.

UI API:

• LSST.UI.UIElement()
  • Descriptions: Creates a UI element.
  • Parameters:
    • options [Object]:
      • name [String]: The name of this UI element.
      • draggable [Object]: Defines specialized jQuery Draggable settings, not required.
      • resizable [Object]: Defines specialized jQuery Resizable settings, not required.
      • toolbar [Object]: Defines a LSST_TOOLBAR to create for this UI element.
        • desc [Object]: The description of the toolbar.
        • options [Object]: The options of the toolbar.
  • Returns: The newly created UI element.
• LSST.UI.UIElement._init()
  • Description: A common init function, to be called by all subclasses. Initializes this UI element.
  • Parameters:
    • options [Object]:
      • name [String]: The name of this UI element.
      • draggable [Object]: Defines specialized jQuery Draggable settings, not required.
      • resizable [Object]: Defines specialized jQuery Resizable settings, not required.
      • toolbar [Object]: Defines a LSST_TOOLBAR to create for this UI element.
        • desc [Object]: The description of the toolbar.
        • options [Object]: The options of the toolbar.
  • Returns: None.
• LSST.UI.UIElement.getName()
  • Parameters: None.
  • Returns: The name of this UI element.
• LSST.UI.UIElement.setFocus()
  • Parameters:
    • bFocus [Boolean]: Should this UI element have top level focus?
  • Returns: None.
• LSST.UI.UIElementList()
  • Description: Creates a new LSST.UI.UIElementList.
  • Parameters: None.
  • Returns: The newly create element list.
• LSST.UI.UIElementList.add()
  • Description: Adds a LSST.UI.UIElement to our list.
  • Parameters:
    • id [String]: The ID of the UI element to add.
    • obj [LSST.UI.UIElement]: The UI element to add.
  • Returns: None.
• LSST.UI.UIElementList.remove()
  • Description: Removes a LSST.UI.UIElement from our list.
  • Parameters:
    • id [String]: The ID of the UI element to remove.
  • Returns: None.
• LSST.UI.UIElementList.get()
  • Description: Gets a LSST.UI.UIElement from our list.
  • Parameters:
    • id [String]: The ID of the UI element to get.
  • Returns: The UI element.
• LSST.UI.UIElementList.exists()
  • Parameters:
    • id [String]: The ID of the UI element to find.
  • Returns: Does that ID exist in our list?
• LSST.UI.UIElementList.foreach()
  • Description: Runs a function for each element in our list.
  • Parameters:
    • f [Function]: The function to run; takes one parameter (the LSST.UI.UIElement).
  • Returns: None.

---

utility.js

---

viewer.js

The classes defined in this file are:

• LSST.UI.Viewer: The main interface for a viewer. Inherits from LSST.UI.UIElement.
• LSST.UI.UV_Control: Provides a utility to update a viewer with images retrieved by a remote server.

Viewer API:

• LSST.UI.Viewer()
  • Description: Creates a viewer interface and adds it to the main display.
  • Parameters:
    • options [Object]:
      • name [String]: The name of this viewer.
  • Returns: The newly created viewer.
• LSST.UI.Viewer.drawRegions()
  • Description: Draws regions on this viewer.
  • Parameters:
    • regions [Array]: An array of DS9 regions to draw on the viewer.
    • layerName [String]: The name of the layer to draw these regions on.
  • Returns: None.
• LSST.UI.Viewer.clear()
  • Description: Clears all of the regions on this viewer.
  • Parameters: None.
  • Returns: None.
• LSST.UI.Viewer.clearLayer()
  • Description: Clears a specific region layer on this viewer.
  • Parameters:
    • layerName [String]: The name of the layer to clear.
  • Returns: None.
• LSST.UI.Viewer.loadImage()
  • Description: Loads a new image into this viewer.
  • Parameters:
    • image [String]: The path to the new image.
  • Returns: None.
• LSST.UI.Viewer.addExtension()
  • Description: Adds a context extension to this viewer.
  • Parameters:
    • title [String]: The title of this extension.
    • type [String]: The extension type, see firefly documentation for valid types.
    • f [Function]: The function to execute on this extension.
  • Returns: None.
• LSST.UI.Viewer.onCursorMove()
  • Description: Sets a callback function to be called when the cursor is moved over this viewer.
  • Parameters:
    • c [Function]: The function to execute.
  • Returns: None.

UV Control API:

• LSST.UI.UV_Control()
  • Description: Creates a new update viewer controller and attaches a viewer to it.
  • Parameters:
    • viewer [LSST.UI.Viewer]: The viewer to attach this controller to.
    • imageRepository [String]: The location of the remote image repository.
    • bStartPaused [Boolean]: Should the controller initially start paused.
    • frequency [Number]: The initial frequency to poll the image repository, in milliseconds (defaults to 10000).
  • Returns: The newly create controller.
• LSST.UI.UV_Control.setFrequency()
  • Description: Sets a new frequency for this controller.
  • Parameters:
    • newFrequency [Number]: The new frequency to poll the image repository, in milliseconds.
• Returns: None.
• LSST.UI.UV_Control.loadNewImage()
  • Description: Loads the newest image into the viewer.
  • Parameters: None.
  • Returns: None.
• LSST.UI.UV_Control.resume()
  • Description: Resumes the automatic updates on the viewer.
  • Parameters: None.
  • Returns: None.
• LSST.UI.UV_Control.update()
  • Description: Polls the image repository for a new image. This function is automatically called, on a time interval defined by the frequency. Calling this from outside the timer will immediately poll the repository.
  • Parameters: None.
  • Returns: None.

---

Terminal

This section describes the code structure for our terminal (jQuery) plugin, defined in terminal/terminal.js.

The namespace of the utility classes and functions for the terminal are defined in LSST_TERMINAL.

LSST_TERMINAL API:

• LSST_TERMINAL.AutoCompleteArray()
  • Description: Creates an auto completeable array.
  • Parameters:
    • strings [Array]: An array of the possible auto completeable strings.
    • allowEmptyMatch [Boolean]: Does an empty string auto complete to something? (Defaults to false).
  • Returns: The newly created auto completable array.
• LSST_TERMINAL.AutoCompleteArray.autoComplete()
  • Description: Checks for matches from the input string.
  • Parameters:
    • input [String]: The string to check against our array.
  • Returns: An object defining the auto completed string.
    • auto [String]: The string to auto complete to. If the input matches more than one string, this is the farthest it the string auto completes to. Empty string if nothing found.
    • match [String]: The first auto complete match. Empty string if nothing found.
    • bWhole: Was there only one match? (ie auto == match)
• LSST_TERMINAL.AutoCompleteArray.insert()
  • Description: Inserts a new string into our array.
  • Parameters:
    • key [String]: The string to add.
  • Returns: None.
• LSST_TERMINAL.Command()
  • Description: Represents an executable command.
  • Parameters:
    • cmd [String]: The format of this command (ie "cmdName param1 param2").
    • callback [Function]: The function to call when this command is executed.
    • description [String]: A user friendly description of this command, not required.
    • helpLink [String]: A link to documentation for this command, not required.
  • Returns: The newly created command.
• LSST_TERMINAL.Command.execute()
  • Description: Executes this command.
  • Parameters:
    • input [String]: The input from the user (to parse and pass to the callback).
    • multiStart [String]: The start character for a subcommand.
    • multiEnd [String]: The end character for a subcommand.
  • Returns: None.
• LSST_TERMINAL.CommandHistory()
  • Description: Represents a buffer for a command history.
  • Parameters:
    • maxEntries [Number]: The maximum number of entries to store.
  • Returns: The newly created command history object.
• LSST_TERMINAL.CommandHistory.saveHistory()
  • Description: Saves our history to the local storage.
  • Parameters: None.
  • Returns: None.
• LSST_TERMINAL.CommandHistory.addCommand()
  • Description: Adds a command to our history.
  • Parameters:
    • cmd [String]: The user input for this command.
    • helpText [String]: The help text displayed to the user when the command was executed.
  • Returns: None.
• LSST_TERMINAL.CommandHistory.get()
  • Description: Gets a command from our history, at the current index.
  • Parameters: None.
  • Returns: An object of the command and help text.
    • cmd [String]: The user input. null if out of bounds.
    • help [String]: The help text. null if out of bounds.
• LSST_TERMINAL.CommandHistory.up()
  • Description: Moves the current index up (towards the beginning of our history).
  • Parameters: None.
  • Returns: None.
• LSST_TERMINAL.CommandHistory.down()
  • Description: Moves the current index up (towards the end of our history).
  • Parameters: None.
  • Returns: None.
• LSST_TERMINAL.CommandHistory.clear()
  • Description: Clears our history.
  • Parameters: None.
  • Returns: None.
• LSST_TERMINAL.InputElem()
  • Description: A interface for an input buffer.
  • Parameters:
    • dom [HTML DOM]: The HTML of this input.
    • clearString [String]: The string to set when the input is cleared (defaults to "").
  • Returns: The newly created input element.
• LSST_TERMINAL.InputElem.clear()
  • Description: Clears this input element.
  • Parameters: None.
  • Returns: None.
• LSST_TERMINAL.InputElem.set()
  • Description: Sets the text of this input element.
  • Parameters:
    • text [String]: A string representing the text of this input element.
  • Returns: None.
• LSST_TERMINAL.InputElem.append()
  • Description: Appends a string into this input element.
  • Parameters:
    • text [String]: A string to append to the text of this input element.
  • Returns: None.
• LSST_TERMINAL.InputElem.text()
  • Parameters: None.
  • Returns: The current text of this input element.
• LSST_TERMINAL.TextContainer()
  • Description: An interface for a container for multiple text elements.
  • Parameters:
    • text [HTML DOM]: The DOM for this container.
  • Returns: The newly created text container.
• LSST_TERMINAL.TextContainer.clear()
  • Description: Removes all of the text elements in this container.
  • Parameters: None.
  • Returns: None.
• LSST_TERMINAL.TextContainer.append()
  • Description: Removes all of the text elements in this container.
  • Parameters:
    • app [String]: The text to add to this container.
    • htmlClass [String]: The HTML class of this text element, not required.
  • Returns: None.
• LSST_TERMINAL.TextElem()
  • Description: An interface for a single text element.
  • Parameters:
    • dom [HTML DOM]: The DOM of this text element.
    • clearString [String]: The string to set when the input is cleared (defaults to "").
  • Returns: The newly created text element.
• LSST_TERMINAL.TextElem.clear()
  • Description: Clears the text of this text element.
  • Parameters: None.
  • Returns: None.
• LSST_TERMINAL.TextElem.set()
  • Description: Sets the text of this text element.
  • Parameters:
    • text [String]: The text to set inside this text element.
  • Returns: None.
• LSST_TERMINAL.TextElem.append()
  • Description: Appends text to this text element.
  • Parameters:
    • app [String]: The text to append to this text element.
  • Returns: None.
• LSST_TERMINAL.TextElem.text()
  • Parameters: None.
  • Returns: The text of this text element.
• LSST_TERMINAL.Utility.Alphabetize()
  • Parameters:
    • array [Array]: The input array.
  • Returns: Returns an alphabetized version of the input array.
• LSST_TERMINAL.Utility.ArrayToString()
  • Parameters:
    • array [Array]: The input array.
  • Returns: The stringified version of the input array, with spaces in between each element.
• LSST_TERMINAL.Utility.GetValue()
  • Parameters:
    • value [Object]: The input value.
    • def [Object]: The default value.
  • Returns: The default if the input is null or undefined, the input otherwise.
• LSST_TERMINAL.Utility.HighlightString()
  • Parameters:
    • string [String]: The string to highlight.
  • Returns: A span containing the highlighted string.
• LSST_TERMINAL.Utility.HighlightStringAtIndex()
  • Parameters:
    • string [String]: The string to highlight.
    • index [Number]: The index of the word to highlight within the string.
  • Returns: A span containing the partially highlighted string.
• LSST_TERMINAL.Utility.ReplaceStringWithVariables()
  • Parameters:
    • string [String]: The input string.
    • variables [Object]: A dictionary mapping variable names to their values.
  • Returns: The modified string with variables replaced with their values.
• LSST_TERMINAL.Utility.SplitStringByWS()
  • Parameters:
    • str [String]: The string to split.
  • Returns: An array containing each word in the input string.
• LSST_TERMINAL.Utility.SplitStringByParameter()
  • Parameters:
    • str [String]: The string to split.
    • multiStart [String]: The start character for a subcommand.
    • multiEnd [String]: The end character for a subcommand.
  • Returns: An array containing each parameter in the input string.
• LSST_TERMINAL.Utility.StringSimilarity()
  • Parameters:
    • str1 [String]: The first string.
    • str2 [String]: The second string.
  • Returns: Returns the similarity between the strings.

Terminal Creation:

To create a terminal, call lsst_term and a valid jQuery object and pass in an object containing the description of the terminal. The description can contain the following properties:

• commands: A dictionary describing the commands.
  • Key [String]: The format of the command.
  • Value [Object]:
    • description [String]: A user friendly description of the command.
    • doc_link [String]: A link to documentation for this command.
• subCommands [Array]: The format of parameters that require more than a single word. Not required.
• autoCompleteParams [Dictionary]: Parameters that can be auto completed. Not required.
  • Key [String]: The parameter name.
  • Value [Array]: Default strings that this parameter can auto complete too. Can be updated through terminal API.
• paramsWithHint [Dictionary]: Hints for certain parameters to be displayed to the user. Not required.
  • Key [String]: The parameter name.
  • Value [String]: The hint string.
• properties [Object]: Properties of the terminal. Not required.
  • width [String]: The width of the terminal.
  • height [String]: The height of the terminal.
  • helpLink [String]: A link to documentation.
  • prefix [String]: The prefix string displayed in the terminal.
  • fontSize [String]: The base font size for the terminal.
• defaults [Dictionary]: Default parameters will be auto completed from a blank string.
  • Key [String]: The parameter name.
  • Value [String]: The default value.

Public Terminal Commands:

To execute a command, call lsst_term on a created terminal, passing in the function name and necessary parameters.

Public Functions:

• echo
  • Description: Echos a string to the user.
  • Parameter [String]: A string to echo on the terminal.
• setVariable
  • Description: Sets a terminal variable.
  • Parameter [Object]:
    • name [String]: The name of the variable.
    • value [String]: The variable's value.
• deleteParameterAuto
  • Description: Deletes an auto complete value for a parameter.
  • Parameter [Object]:
    • param [String]: The name of the parameter.
    • value [String]: The value to remove.
• minimze
  • Description: Minimizes the terminal.
  • Parameter: None.
• maximize
  • Description: Maximizes the terminal.
  • Parameter: None.
• setDefault
  • Description: Sets the default value for a parameter.
  • Parameter [Object]:
    • param [String]: The name of the parameter.
    • value [String]: The new default value.

---

Toolbar

This section describes the code structure for our toolbar plugin.