terminal.js¶

Gate One's bundled Terminal application JavaScript (source).

GateOne.Terminal.__new__(settings[, where])¶

Called when a user clicks on the Terminal Application in the New Workspace Workspace (or anything that happens to call __new__()).

Settings:	An object containing the settings that will control how the new terminal is created. Typically contains the application's 'info' data from the server.
Where:	An optional querySelector-like string or DOM node where the new Terminal should be placed. If not given a new workspace will be created to contain the Terminal.

GateOne.Terminal.hasVoiceExt()¶: This function returns true if an extension is detected that converts phone numbers into clickable links (e.g. Google Voice). Such browser extensions can have a severe negative performance impact while using terminals (every screen update requires a re-scan of the entire page!).

GateOne.Terminal.dbReady(db)¶: Sets GateOne.Terminal.dbReady = true so that we know when the 'terminal' database is available & ready (indexedDB databases are async).

GateOne.Terminal.createPrefsPanel()¶: Creates the terminal preferences and adds them to the global preferences panel.

GateOne.Terminal.enumerateCommandsAction(messageObj)¶: Attached to the 'terminal:commands_list' WebSocket action; stores messageObj['commands'] in GateOne.Terminal.commandsList.

GateOne.Terminal.enumerateFontsAction(messageObj)¶: Attached to the 'terminal:fonts_list' WebSocket action; updates the preferences panel with the list of fonts stored on the server and stores the list in GateOne.Terminal.fontsList.

GateOne.Terminal.enumerateColorsAction(messageObj)¶: Attached to the 'terminal:colors_list' WebSocket action; updates the preferences panel with the list of text color schemes stored on the server.

GateOne.Terminal.onResizeEvent()¶: Attached to the go:update_dimensions event; calls GateOne.Terminal.sendDimensions() for all terminals to ensure the new dimensions get applied.

GateOne.Terminal.reconnectEvent()¶: Attached to the go:connnection_established event; closes all open terminals so that GateOne.Terminal.reattachTerminalsAction() can do its thing.

GateOne.Terminal.connectionError()¶: This function gets attached to the "go:connection_error" event; closes all open terminals.

GateOne.Terminal.getOpenTerminals()¶: Requests a list of open terminals on the server via the 'terminal:get_terminals' WebSocket action. The server will respond with a 'terminal:terminals' WebSocket action message which calls GateOne.Terminal.reattachTerminalsAction().

GateOne.Terminal.sendString(chars[, term])¶

Like sendChars() but for programmatic use. chars will be sent to term on the server.

If term is not given the currently-selected terminal will be used.

GateOne.Terminal.killTerminal(term)¶: Tells the server got close the given term and kill the underlying process.

GateOne.Terminal.refresh(term)¶: Tells the Gate One server to send a screen refresh (using the diff method).

Note

This function is only here for debugging purposes. Under normal circumstances difference-based screen refreshes are initiated at the server.

GateOne.Terminal.fullRefresh(term)¶: Tells the Gate One server to send a full screen refresh to the client for the given term.

GateOne.Terminal.loadFont(font[, size])¶

Tells the server to perform a sync of the given font with the client. If font is not given, will load the font set in GateOne.prefs.font.

Optionally, a size may be chosen. It must be a valid CSS 'font-size' value such as '0.9em', '90%', '12pt', etc.

GateOne.Terminal.loadTextColors(colors)¶: Tells the server to perform a sync of the given colors (terminal text colors) with the client. If colors is not given, will load the colors set in GateOne.prefs.colors.

GateOne.Terminal.displayTermInfo(term)¶: Displays the given term's information as a psuedo tooltip that eventually fades away.

GateOne.Terminal.sendDimensions([term[, ctrl_l]])¶

Detects and sends the given term's dimensions (rows/columns) to the server.

If no term is given it will send the dimensions of the currently-selected terminal to the server which will be applied to all terminals.

GateOne.Terminal.setTitle(term, text)¶: Sets the visible title of term to text appropriately based on whether or not this is a popup terminal or just a regular one.

Note

This function does not set the 'title' or 'X11Title' attributes of the GateOne.Terminal.terminals[term] object. That is handled by GateOne.Terminal.setTitleAction().

GateOne.Terminal.setTitleAction(titleObj)¶: Sets the title of titleObj.term to titleObj.title.

GateOne.Terminal.resizeAction(message)¶: Called when the server sends the terminal:resize WebSocket action. Sets the 'rows' and 'columns' values inside GateOne.Terminal.terminals[message.term] and sets the same values inside the Info & Tools panel.

GateOne.Terminal.paste(e)¶: This gets attached to Shift-Insert (KEY_INSERT) as a shortcut in order to support pasting.

GateOne.Terminal.writeScrollback(term, scrollback)¶: Writes the given scrollback buffer for the given term to localStorage.

GateOne.Terminal.applyScreen(screen[, term[, noUpdate]])¶

Uses screen (array of HTML-formatted lines) to update term.

If term is omitted localStorage[prefix+selectedTerminal] will be used.

If noUpdate is true the array that holds the current screen in GateOne.Terminal.terminals will not be updated (useful for temporary screen replacements).

Note

Lines in screen that are empty strings or null will be ignored (so it is safe to pass a full array with only a single updated line).

GateOne.Terminal.alignTerminal(term)¶: Uses a CSS3 transform to move the terminal <pre> element upwards just a bit so that the scrollback buffer isn't visislbe unless you actually scroll. This improves the terminal's overall appearance considerably because the bottoms of characters in the scollback buffer tend to look like graphical glitches.

GateOne.Terminal.termUpdateFromWorker(e)¶: This function gets assigned to the termUpdatesWorker.onmessage() event; Whenever the WebWorker completes processing of the incoming screen it posts the result to this function. It takes care of updating the terminal on the page, storing the scrollback buffer, and finally triggers the "terminal:term_updated" event passing the terminal number as the only argument.

GateOne.Terminal.loadWebWorkerAction(source)¶: Loads our Web Worker given it's source (which is sent to us over the WebSocket which is a clever workaround to the origin limitations of Web Workers =).

GateOne.Terminal.updateTerminalAction(termUpdateObj)¶: Takes the updated screen information from termUpdateObj and posts it to the 'term_ww.js' Web Worker to be processed.

Note

The Web Worker is important because it allows offloading of CPU-intensive tasks like linkification and text transforms so they don't block screen updates

GateOne.Terminal.notifyInactivity(term)¶: Notifies the user of inactivity in term.

GateOne.Terminal.notifyActivity(term)¶: Notifies the user of activity in term.

GateOne.Terminal.newPastearea()¶: Returns a 'pastearea' (textarea) element meant for placement above terminals for the purpose of enabling proper copy & paste.

GateOne.Terminal.newTerminal([term[, settings[, where]]])¶

Adds a new terminal to the grid and starts updates with the server.

If term is provided, the created terminal will use that number.

If settings (object) are provided the given parameters will be applied to the created terminal's parameters in GateOne.Terminal.terminals[term] as well as sent as part of the 'terminal:new_terminal' WebSocket action. This mechanism can be used to spawn terminals using different 'commands' that have been configured on the server. For example:

> // Creates a new terminal that spawns whatever command is set as 'login' in Gate One's settings:
> GateOne.Terminal.newTerminal(null, {'command': 'login'});

If where is provided, the new terminal element will be appended like so: where.appendChild(<new terminal element>); Otherwise the terminal will be added to the grid.

Terminal types are sent from the server via the 'terminal_types' action which sets up GateOne.terminalTypes. This variable is an associative array in the form of: {'term type': {'description': 'Description of terminal type', 'default': true/false, <other, yet-to-be-determined metadata>}}.

GateOne.Terminal.closeTerminal(term[, noCleanup[, message[, sendKill]]])¶

Arguments:

term (number) -- The terminal to close.
noCleanup (boolean) -- If true the terminal's metadata in localStorage/IndexedDB (i.e. scrollback buffer) will not be removed.
message (string) -- An optional message to display to the user after the terminal is close.
sendKill (boolean) -- If undefined or true, will tell the server to kill the process associated with the given term (i.e. close it for real).

Closes the given terminal (term) and tells the server to end its running process.

GateOne.Terminal.popupTerm([term])¶

Opens a dialog with a terminal contained within. If term is given the created terminal will use that number.

The options argument may contain the following:

global: If true the dialog will be appended to GateOne.node (e.g. #gateone) instead of the current workspace.

where: If provided the popup terminal will be placed within the given element.

If the terminal inside the dialog ends it will be closed automatically. If the user closes the dialog the terminal will be closed automatically as well.

If termSettings are provided they will be passed to GateOne.Terminal.newTerminal() when called.

GateOne.Terminal.setTerminal(term)¶

Sets the 'selectedTerminal' value in localStorage and sends the 'terminal:set_terminal' WebSocket action to the server to let it know which terminal is currently active.

This function triggers the 'terminal:set_terminal' event passing the terminal number as the only argument.

GateOne.Terminal.switchTerminal(term)¶: Calls GateOne.Terminal.setTerminal(*term*) then triggers the 'terminal:switch_terminal' event passing term as the only argument.

GateOne.Terminal.setActive([term])¶

Removes the '✈inactive' class from the given term.

If term is not given the currently-selected terminal will be used.

GateOne.Terminal.isActive()¶: Returns true if a terminal is the current application (selected by the user)

GateOne.Terminal.switchTerminalEvent(term)¶: This gets attached to the 'terminal:switch_terminal' event in GateOne.Terminal.init(); performs a number of actions whenever the user changes the current terminal.

GateOne.Terminal.switchWorkspaceEvent(workspace)¶: Called whenever Gate One switches to a new workspace; checks whether or not this workspace is home to a terminal and calls switchTerminalEvent() on said terminal (to make sure input is enabled and it is scrolled to the bottom).

GateOne.Terminal.workspaceClosedEvent(workspace)¶: Attached to the go:close_workspace event; closes any terminals that are attached to the given workspace.

GateOne.Terminal.swappedWorkspacesEvent(ws1, ws2)¶: Attached to the go:swapped_workspaces event; updates GateOne.Terminal.terminals with the correct workspace attributes if either contains terminals.

GateOne.Terminal.printScreen(term)¶: Prints just the screen (no scrollback) of the given term. If term is not provided the currently-selected terminal will be used.

GateOne.Terminal.hideIcons()¶: Hides the Terminal's toolbar icons (i.e. when another application is running).

GateOne.Terminal.showIcons()¶: Shows (unhides) the Terminal's toolbar icons (i.e. when another application is running).

GateOne.Terminal.bellAction(bellObj)¶: Attached to the 'terminal:bell' WebSocket action; plays a bell sound and pops up a message indiciating which terminal issued a bell.

GateOne.Terminal.playBell()¶: Plays the bell sound without any visual notification.

GateOne.Terminal.updateDimensions()¶: This gets attached to the "go:update_dimensions" event which gets called whenever the window is resized. It makes sure that all the terminal containers are of the correct dimensions.

GateOne.Terminal.enableScrollback([term])¶

Replaces the contents of the selected/active terminal scrollback buffer with the complete latest scrollback buffer from GateOne.Terminal.terminals[*term*].

If term is given, only ensable scrollback for that terminal.

GateOne.Terminal.toggleScrollback()¶: Enables or disables the scrollback buffer (to hide or show the scrollbars).

GateOne.Terminal.clearScrollback(term)¶: Empties the scrollback buffer for the given term in memory, in localStorage, and in the DOM.

GateOne.Terminal.clearScreen(term)¶: Clears the screen of the given term in memory and in the DOM.

Note

The next incoming screen update from the server will likely re-populate most if not all of the screen.

GateOne.Terminal.getLocations()¶: Sends the terminal:get_locations WebSocket action to the server. This will ultimately trigger the GateOne.Terminal.locationsAction() function.

GateOne.Terminal.locationsAction(locations)¶: Attached to the terminal:term_locations WebSocket action, triggers the terminal:term_locations event (in case someone wants to do something with that information).

GateOne.Terminal.relocateWorkspaceEvent(workspace, location)¶: Attached to the go:relocate_workspace event; calls GateOne.Terminal.relocateTerminal() if the given workspace has a terminal contained within it.

GateOne.Terminal.relocateTerminal(term, location)¶

Arguments:	term (number) -- The number of the terminal to move (e.g. 1). location (string) -- The 'location' where the terminal will be moved (e.g. 'window2').

Moves the given term to the given location (aka window) by sending the appropriate message to the Gate One server.

GateOne.Terminal.changeLocation(location[, settings])¶

Attached to the go:set_location event, removes all terminals from the current view and opens up all the terminals at the new location. If there are currently no terminals at location a new terminal will be opened automatically.

To neglect opening a new terminal automatically provide a settings object like so:

>>> GateOne.Terminal.changeLocation('window2', {'new_term': false}`);

GateOne.Terminal.reconnectTerminalAction(message)¶

Called when the server reports that the terminal number supplied via the terminal:new_terminal WebSocket action already exists.

This method also gets called when a terminal is moved from one 'location' to another.

GateOne.Terminal.moveTerminalAction(obj)¶: Attached to the terminal:term_moved WebSocket Action, closes the given term with a slightly different message than closeTerminal().

GateOne.Terminal.reattachTerminalsAction(terminals)¶

Called after we authenticate to the server, this function is attached to the terminal:terminals WebSocket action which is the server's way of notifying the client that there are existing terminals.

If we're reconnecting to an existing session, running terminals will be recreated/reattached.

If this is a new session (and we're not in embedded mode), a new terminal will be created.

GateOne.Terminal.recordPanePositions()¶: Records the position of each terminal in each GateOne.Visual.Pane() that exists on the page (so they can be resumed properly).

GateOne.Terminal.resumePanePosition(term)¶: Uses GateOne.Terminal.terminals[term].metadata.panePosition to create a new terminal in that exact spot. New :js:meth`GateOne.Visual.Pane` objects will be created as necessary to ensure the terminal winds up where it was previously.

GateOne.Terminal.setModeAction(modeObj)¶

Set the given terminal mode (e.g. application cursor mode aka appmode). modeObj is expected to be something like this:

{'mode': '1', 'term': '1', 'bool': true}

GateOne.Terminal.registerTextTransform(name, pattern, newString)¶

Adds a new or replaces an existing text transformation to GateOne.Terminal.textTransforms using pattern and newString with the given name. Example:

var pattern = /(\bIM\d{9,10}\b)/g,
    newString = "<a href='https://support.company.com/tracker?ticket=$1' target='new'>$1</a>";
GateOne.Terminal.registerTextTransform("ticketIDs", pattern, newString);

Would linkify text matching that pattern in the terminal.

For example, if you typed "Ticket number: IM123456789" into a terminal it would be transformed thusly:

"Ticket number: <a href='https://support.company.com/tracker?ticket=IM123456789' target='new'>IM123456789</a>"

Alternatively, a function may be provided instead of pattern. In this case, each line will be transformed like so:

line = pattern(line);

Note

name is only used for reference purposes in the textTransforms object (so it can be removed or replaced later).

Tip

To match the beginning of a line use '\n' instead of '^'. This is necessary because the entire screen is matched at once as opposed to line-by-line.

GateOne.Terminal.unregisterTextTransform(name)¶: Removes the given text transform from GateOne.Terminal.textTransforms.

GateOne.Terminal.resetTerminalAction(term)¶: Clears the screen and the scrollback buffer of the given term (in memory, localStorage, and in the DOM).

GateOne.Terminal.termEncodingAction(message)¶

Handles the 'terminal:encoding' WebSocket action that tells us the encoding that is set for a given terminal. The expected message format:

Arguments:	message.term (string) -- The terminal in question. message['encoding'] (string) -- The encoding to set on the given terminal.

Note

The encoding value here is only used for informational purposes. No encoding/decoding happens at the client.

GateOne.Terminal.termKeyboardModeAction(message)¶

Handles the 'terminal:keyboard_mode' WebSocket action that tells us the keyboard mode that is set for a given terminal. The expected message format:

Arguments:	message.term (string) -- The terminal in question. message['mode'] (string) -- The keyboard mode to set on the given terminal. E.g. 'default', 'sco', 'xterm', 'linux', etc

Note

The keyboard mode value is only used by the client. There's no server-side functionality related to keyboard modes other than the fact that it remembers the setting.

GateOne.Terminal.xtermEncode(number)¶

Encodes the given number into a single character using xterm's encoding scheme. e.g. to convert mouse coordinates for use in an escape sequence.

The xterm encoding scheme takes the ASCII value of (number + 32). So the number one would be ! (exclamation point), the number two would be " (double-quote), the number three would be # (hash), and so on.

Note

This encoding mechansim has the unfortunate limitation of only being able to encode up to the number 233.

GateOne.Terminal.highlight(text[, term])¶

Highlights all occurrences of the given text inside the given term by wrapping it in a span like so:

<span class="✈highlight">text</span>

If term is not provided the currently-selected terminal will be used.

GateOne.Terminal.unHighlight()¶: Undoes the results of GateOne.Terminal.highlight().

GateOne.Terminal.highlightTexts¶: An object that holds all the words the user wishes to stay persistently highlighted (even after screen updates and whatnot) across all terminals.

Note

Word highlighting that is specific to individual terminals is stored in GateOne.Terminal.terminals[term].

GateOne.Terminal.highlightDialog()¶: Opens a dialog where users can add/remove text they would like to be highlighted on a semi-permanent basis (e.g. even after a screen update).

GateOne.Terminal.showSuspended()¶: Displays a little widget in the terminal that indicates that output has been suspended.

GateOne.Terminal.scrollPageUp([term])¶: Scrolls the given term one page up. If term is not given the currently-selected terminal will be used.

GateOne.Terminal.scrollPageDown([term])¶: Scrolls the given term one page up. If term is not given the currently-selected terminal will be used.

GateOne.Terminal.chooser()¶: Pops up a dialog where the user can immediately switch to any terminal in any 'location'.

Note

If the terminal is in a different location the current location will be changed along with all terminals before the switch is made.

GateOne.Terminal.sharePermissions(term, permissions)¶

Sets the sharing permissions of the given term. The permissions must be an object that contains one or both of the following:

read: An array of users that will be given read-only access to the given term.

write: An array of users that will be given write access to the given term.

Note

read and write may be given as a string if only one user's permissions are being modified.

Example:

>>> GateOne.Terminal.sharePermissions(1, {'read': 'AUTHENTICATED', 'write': ["bob@company", "joe@company"]);

Note

If a user is granted write permission to a terminal they will automatically be granted read permission.

GateOne.Terminal.shareDialog(term)¶: Opens a dialog where the user can share a terminal or modify the permissions on a terminal that is already shared.

GateOne.Terminal.setShareID(term[, shareID])¶: Sets the share ID of the given term. If a shareID is not provided one will be generated automatically (by the server).

GateOne.Terminal.attachSharedTerminal(shareID[, password[, metadata]])¶

Opens the terminal associated with the given shareID.

If a password is given it will be used to attach to the shared terminal.

If metadata is given it will be passed to the server to be used for extra logging and providing additional details about who is connecting to shared terminals.

GateOne.Terminal.detachSharedTerminal(term)¶: Tells the server that we no longer wish to view the terminal associated with the given term (local terminal number).

GateOne.Terminal.listSharedTerminals()¶: Sens the terminal:list_shared_terminals WebSocket action to the server which will reply with the terminal:shared_terminals WebSocket action (if the user is allowed to list shared terminals).

GateOne.Terminal.sharedTerminalsAction(message)¶: Attached to the terminal:shared_terminals WebSocket action; stores the list of terminals that have been shared with the user in GateOne.Terminal.sharedTerminals and triggers the terminal:shared_terminals event.

GateOne.Terminal.sharedTerminalsDialog()¶: Opens up a dialog where the user can open terminals that have been shared with them.

GateOne.Terminal.shareInfo(term)¶: Displays a dialog that lists the current viewers (along with their permissions) of a given term.

GateOne.Terminal.shareWidget(term)¶: Adds a terminal sharing widget to the given term (number) that provides sharing controls and information (e.g. number of viewers).

GateOne.Terminal.sharedTermObj(term)¶: Returns the object matching the given term from GateOne.Terminal.sharedTerminals.

GateOne.Terminal.shareID(term)¶: Returns the share ID for the given term (if any).

GateOne.Terminal.shareBroadcastURL(term)¶: Returns the broadcast URL for the given term (if any).

GateOne.Terminal._trimmedScreen(screen)¶: Returns screen with all trailing empty lines removed.

GateOne.Terminal.lastLines([n[, term]])¶

Returns the last n non-blank (trimmed) line in the terminal. Useful for pattern matching.

If term is not given the localStorage[prefix+'selectedTerminal'] will be used.

GateOne.Terminal.startCapture(term)¶: Starts capturing terminal output for the given term. The GateOne.Terminal.stopCapture() function can be called to stop the capture and send the captured data to the client via the 'terminal:captured_data' WebSocket action. This WebSocket action gets attached to GateOne.Terminal.capturedData() which will call the 'terminal:captured_data' event passing the terminal number and the captured data as the only arguments.

GateOne.Terminal.stopCapture(term)¶: Stops capturing output on the given term.

GateOne.Terminal.capturedData(message)¶

Attached to the 'terminal:captured_data' WebSocket action; triggers the 'terminal:captured_data' event like so:

GateOne.Events.trigger('terminal:captured_data', term, data);