### Navigation

- index
- modules |
- next |
- previous |
- Gate One Documentation »
- Gate One Applications »
- Terminal »
- Terminal Developer Documentation »

# The Example Plugin

## JavaScript

example.js - The client-side portion of Gate One's Example plugin.

`GateOne.Terminal.Example.``generateAuthObject`(api_key, secret, upn)

  Returns a properly-constructed authentication object that can be used with Gate One's API authentication mode. The timestamp, signature, signature_method, and api_version values will be created automatically.

  Arguments:

  - api_key (string) -- The API key to use when generating the authentication object. Must match Gate One's api_keys setting (e.g. in server.conf).
  - secret (string) -- The secret attached to the given api_key.
  - upn (string) -- The userPrincipalName (aka UPN or username) you'll be authenticating.

  Note

  This will also attach an 'example_attibute' that will be automatically assigned to the 'user' dict on the server so it can be used for other purposes (e.g. authorization checks and inside of plugins).

`GateOne.Terminal.Example.``init`()

  The init() function of every JavaScript plugin gets called automatically after the WebSocket is connected is authenticated.

  The Example plugin's `init()` function sets up some internal variables, keyboard shortcuts (`Control-Alt-L` to open the load graph), and adds some buttons to the Info & Tools menu.

`GateOne.Terminal.Example.``stopGraph`(result)

  Clears the `GateOne.Terminal.Example.graphUpdateTimer`, removes the canvas element, and stops the smoothie graph streaming. result is unused.

`GateOne.Terminal.Example.``toggleLoadGraph`(term)

  Displays a real-time load graph of the given terminal (inside of it as a `GateOne.Visual.widget()`).

`GateOne.Terminal.Example.``topTop`(term)

  Displays the top three CPU-hogging processes on the server in real-time (updating every three seconds just like top).

`GateOne.Terminal.Example.``updateGraph`(output)

  Updates `GateOne.Terminal.Example.line1` through `line3` by parsing the output of the 'uptime' command.

`GateOne.Terminal.Example.``updateTop`(output)

  Updates the `GateOne.Terminal.Example.topTop()` output on the screen when we receive output from the Gate One server. Here's what the output should look like:

      PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
        1 root      20   0 24052 2132 1316 S  0.0  0.4   0:00.35 /sbin/init
        2 root      20   0     0    0    0 S  0.0  0.0   0:00.00 [kthreadd]
        3 root      20   0     0    0    0 S  0.0  0.0   0:00.08 [ksoftirqd/0]

`GateOne.Terminal.Terminal.Example.``stopTop`(result)

  Clears the `GateOne.Terminal.Example.topUpdateTimer` and removes the 'toptop' element. result is unused.

## Python

example.py - A plugin to demonstrate how to write a Python plugin for Gate One. Specifically, how to write your own web handlers, WebSocket actions, and take advantage of all the available hooks and built-in functions.

Tip

This plugin is heavily commented with useful information. Click on the `[source]` links to the right of any given class or function to see the actual code.

### Hooks

This Python plugin file implements the following hooks:

    hooks = {
        'Web': [(r"/example", ExampleHandler)],
        'WebSocket': {
            'example_action': example_websocket_action
        },
        'Escape': example_opt_esc_handler,
    }

### Docstrings

class `example.``ExampleHandler`(application, request, **kwargs)

  This is how you add a URL handler to Gate One... This example attaches itslef to https://<your Gate One server>/example in the 'Web' hook at the bottom of this file. It works just like any Tornado `RequestHandler`. See:

  http://www.tornadoweb.org/documentation/web.html

  ...for documentation on how to write a `tornado.web.RequestHandler` for the Tornado framework. Fairly boilerplate stuff.

  Note

  The only reason we use `gateone.BaseHandler` instead of a vanilla `tornado.web.RequestHandler` is so we have access to Gate One's `gateone.BaseHandler.get_current_user()` function.

  `get`(*args, **kwargs)

    Handle an HTTP GET request to this `RequestHandler`. Connect to:

    https://<your Gate One server>/example

    ...to try it out.

  `post`()

    Example Handler for an HTTP POST request. Doesn't actually do anything.

`example.``example_websocket_action`(self, message)

  This WebSocket action gets exposed to the client automatically by way of the 'WebSocket' hook at the bottom of this file. The way it works is like this:

  How The WebSocket Hook Works

  Whenever a message is received via the WebSocket Gate One will automatically decode it into a Python `dict` (only JSON-encoded messages are accepted). Any and all keys in that `dict` will be assumed to be 'actions' (just like `GateOne.Net.actions` but on the server) such as this one. If the incoming key matches a registered action that action will be called like so:

      key(value)
      # ...or just:
      key() # If the value is None ('null' in JavaScript)

  ...where key is the action and value is what will be passed to said action as an argument. Since Gate One will automatically decode the message as JSON the value will typically be passed to actions as a single `dict`. You can provide different kinds of arguments of course but be aware that their ordering is unpredictable so always be sure to either pass one argument to your function (assuming it is a `dict`) or 100% keyword arguments.

  The self argument here is automatically assigned by `TerminalApplication` using the `utils.bind` method.

  The typical naming convention for WebSocket actions is: `<plugin name>_`. Whether or not your action names match your function names is up to you. All that matters is that you line up an action (string) with a function in `hooks['WebSocket']` (see below).

  This WebSocket action duplicates the functionality of Gate One's built-in `gateone.TerminalWebSocket.pong()` function. You can see how it is called by the client (browser) inside of example.js (which is in this plugin's 'static' dir).

`example.``example_opt_esc_handler`(self, message, term=None, multiplex=None)

  Gate One includes a mechanism for plugins to send messages from terminal programs directly to plugins written in Python. It's called the "Special Optional Escape Sequence Handler" or SOESH for short. Here's how it works: Whenever a terminal program emits, "x1b]_;" it gets detected by Gate One's `Terminal` class (which lives in `terminal.py`) and it will execute whatever callback is registered for SOESH. Inside of Gate One this callback will always be `gateone.TerminalWebSocket.esc_opt_handler()`.

`example.``example_command_hook`(self, command, term=None)

  This demonstrates how to modify Gate One's configured 'command' before it is executed. It will replace any occurrance of %EXAMPLE% with 'foo'. So if 'command = "some_script.sh %EXAMPLE%"' in your server.conf it would be transformed to "some_script.sh foo" before being executed when a user opens a new terminal.

### Navigation

- index
- modules |
- next |
- previous |
- Gate One Documentation »
- Gate One Applications »
- Terminal »
- Terminal Developer Documentation »