frontend-tutorial-framework

This is the Angular frontend of TFW.

The main exposed features are our pre-implemented components based on the src/app/services/websocket.service.ts service. This service provides an RxJS based communication API to the framework backend (TFW server and event handlers).

Another useful features are a bunch of pre-designed layouts and dynamic switching between them.

To learn more about the framework, see the baseimage-tutorial-framework repo. For more on creating, building and running TFW-based tutorials (not just the frontend) consult test-tutorial-framework.

Components

In this section we are going to explore the various pre-made components this project offers.

Generally these components connect to a TFW event handler running on the backend. Communication is handled via simpe APIs exposed by these event handlers – over TFW messages.

These APIs are documented in the baseimage-tutorial-framework repository as docstrings in the lib/tfw/components directory (this is where the implementations of our pre-written event handlers live).

Configuration

Most of the time it is not necessary to edit the source code of our components as you can easily customise their behaviour through the src/app/config.ts config file.

The most notable setting available in this file is the enabling of different layouts, which allows the user and you to switch between them. Layouts describe which components are visible and where they are on the screen.

Terminal (webshell)

This is a full-fledged xterm terminal emulator which runs right in your browser and is based on xterm.js. The emulator is connected to a TerminalEventHandler instance on the backend over websockets.

This event handler spawns a bash session and a pty (pseudoterminal). It connects the master end of the pty to the emulator running in your browser and the slave end to bash.

This essentially provides a fully functional terminal session for your users in the browser (a convenient alternative for an SSH session).

This terminal is fully under your control: You can write to it (and thus execute commands) and read what commands were executed by the user using the API exposed by the TerminalEventHandler.

This enables you to pre-type or execute commands for the user and figure out what they are doing in the terminal.

IDE (webIde)

This component is a simple text editor based on ACE. It always shows all files in a given folder and allows you to switch between them using the tabs on top. The IDE automatically saves any changes made to the files (the interval is configurable).

It connects to an IdeEventHandler instance on the backend which handles the reading/writing of files and the selection of directories as well.

It is also capable of dynamically displaying any changes made to these files from the terminal or from another process (this means that you always see a live view of the files).

This component provides an optional 'Deploy' button, which can be configured to restart a process in supervisord. You can enable this button by editig the ide.showDeployButton key of config.ts. To configure which process the button should restart edit ide.deployProcessName.

Messages

This is a simple chat-like component you can use to instruct, help and guide your users. It displays messages sent to the frontend with the key message.

The message format used:

{ 
    "key": "message",
    "data":
    {
        "originator": ...,
        "timestamp": ...,
        "message": ...
    }
}

You can use the MessageSender class to send messages from the TFW server or event handlers written in Python.

Web – customisable component

In some of our layouts there is space allocated for a custom webservice or Angular component. This allows you to embed your own website in the TFW frontend.

There are two ways to do this:

Should you prefer to avoid Angular you can run your own webserver on the backend and use our dashboard's iframeing capabilities to include it. To enable this feature you have to edit src/app/config.ts and to set config.dashboard.iframeUrl to the route your server is listening on.

Note that setting up a custom server is documented in the test-tutorial-framework repo.

Alternatively you can create your own Angular component(s) in src/app/web. Just rewrite WebComponent as you please or even nest more components into it if needed. Note that you must set config.dashboard.iframeUrl to an empty string('') to enable the displaying of WebComponent (this also disables iframeing).

Dashboard

The dashboard is the component that composes all others and organises them into layouts.

Edit src/app/config.ts to change the layout settings.

Set config.dashboard.currentLayout to the layout you want to be displayed by default.

You can specify the layouts you allow in config.dashboard.enabledLayouts (the user can switch between them using a sidebar). This list must include the value of currentLayout.

Available layouts– with self explaining names:

• terminal-ide-web
• terminal-ide-vertical
• erminal-ide-horizontal
• terminal-only
• terminal-web
• ide-web-vertical
• ide-only
• web-only

The dashboard also exposes a frontend API to dynamically change layouts any time using a message format as such (note that the layout you switch to must be enabled):

{ 
    "key": "dashboard",
    "data":
    {
        "command": "layout",
        "layout": ...,
        "hide_messages": ...
    }
}

You can use the hide_messages key to hide the message component (sadly it currently takes up the space it would occupy).