2018-03-30 21:42:56 +00:00
# frontend-tutorial-framework
2017-12-14 10:03:30 +00:00
2018-03-30 21:42:56 +00:00
This is the Angular frontend of TFW.
2017-12-14 10:03:30 +00:00
2018-04-23 16:05:48 +00:00
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).
2017-12-14 10:03:30 +00:00
2018-05-11 09:33:50 +00:00
Another useful features are a bunch of pre-designed layouts and dynamic switching between them.
2018-04-23 16:05:48 +00:00
2018-05-11 09:33:50 +00:00
To learn more about the framework, see the [baseimage-tutorial-framework ](https://github.com/avatao-content/baseimage-tutorial-framework ) repo.
2018-04-23 16:05:48 +00:00
For more on creating, building and running TFW-based tutorials (not just the frontend) consult [test-tutorial-framework ](https://github.com/avatao-content/test-tutorial-framework ).
2018-04-23 11:37:24 +00:00
## 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.
2018-05-11 09:33:50 +00:00
These APIs are documented in the [baseimage-tutorial-framework ](https://github.com/avatao-content/baseimage-tutorial-framework ) repository as docstrings in the [lib/tfw/components ](https://github.com/avatao-content/baseimage-tutorial-framework/tree/master/lib/tfw/components ) directory (this is where the implementations of our pre-written event handlers live).
2018-04-23 16:05:48 +00:00
## 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.
2018-05-11 09:33:50 +00:00
The most notable setting available in this file is the enabling of different layouts, which allows the user and you to switch between them.
2018-04-23 16:05:48 +00:00
Layouts describe which components are visible and where they are on the screen.
2018-04-23 11:37:24 +00:00
### Terminal (webshell)
2018-05-11 09:33:50 +00:00
This is a full-fledged xterm terminal emulator which runs right in your browser and is based on xterm.js.
2018-04-23 16:05:48 +00:00
The emulator is connected to a `TerminalEventHandler` instance on the backend over websockets.
This event handler spawns a `bash` session and a `pty` (pseudoterminal).
2018-04-26 08:41:15 +00:00
It connects the master end of the `pty` to the emulator running in your browser and the slave end to `bash` .
2018-04-23 11:37:24 +00:00
2018-04-25 13:06:44 +00:00
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:
2018-04-26 08:41:15 +00:00
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` .
2018-04-23 11:37:24 +00:00
2018-04-23 16:05:48 +00:00
This enables you to pre-type or execute commands for the user and figure out what they are doing in the terminal.
2018-04-23 11:37:24 +00:00
### IDE (webIde)
This component is a simple text editor based on ACE.
2018-05-11 09:33:50 +00:00
It always shows all files in a given folder and allows you to switch between them using the tabs on top.
2018-04-23 16:05:48 +00:00
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.
2018-05-11 09:33:50 +00:00
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).
2018-04-23 16:05:48 +00:00
2018-05-04 12:31:00 +00:00
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` .
2018-05-11 09:33:50 +00:00
To configure which process the button should restart edit `ide.deployProcessName` .
2018-05-04 12:31:00 +00:00
2018-04-23 16:05:48 +00:00
### 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": ...
}
}
```
2018-04-23 11:37:24 +00:00
2018-04-23 16:05:48 +00:00
You can use the `MessageSender` class to send messages from the TFW server or event handlers written in Python.
2017-12-14 10:03:30 +00:00
2018-04-23 16:54:09 +00:00
### Web – customisable component
2017-12-14 10:03:30 +00:00
2018-04-25 12:46:46 +00:00
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:
2018-05-11 09:33:50 +00:00
Should you prefer to avoid Angular you can run your own webserver on the backend and use our dashboard's `iframe` ing 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.
2018-04-26 08:41:15 +00:00
2018-04-25 12:46:46 +00:00
Note that setting up a custom server is documented in the [test-tutorial-framework ](https://github.com/avatao-content/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 `iframe` ing).
2018-04-23 16:54:09 +00:00
### Dashboard
The dashboard is the component that composes all others and organises them into layouts.
2018-04-25 12:56:03 +00:00
Edit `src/app/config.ts` to change the layout settings.
2018-04-26 08:41:15 +00:00
Set `config.dashboard.currentLayout` to the layout you want to be displayed by default.
2018-04-25 12:56:03 +00:00
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`
2018-04-26 08:41:15 +00:00
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):
2018-04-23 16:54:09 +00:00
```
{
"key": "dashboard",
"data":
{
"command": "layout",
"layout": ...,
"hide_messages": ...
}
}
```
2018-04-26 08:41:15 +00:00
You can use the `hide_messages` key to hide the message component (sadly it currently takes up the space it would occupy).