mrtoth
/
frontend-tutorial-framework
mirror of https://github.com/avatao-content/frontend-tutorial-framework
1
0
Fork 0
Code Issues Releases Wiki Activity

Continue documenting frontend components

This commit is contained in:
Kristóf Tóth 2018-04-23 18:05:48 +02:00
parent 33ebefd767
commit 6f93869dc0
1 changed files with 48 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
README.md
View File

@ -2,9 +2,13 @@
This is the Angular frontend of TFW.
The main feature it exposes is the `src/app/services/websocket.service.ts` service – providing an RxJS based communication API with the framework backend – and several pre-implemented components for you to use based on it.
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).
To learn more about the framework see the `baseimage-tutorial-framework` repo. For more on creating and running TFW-based tutorials (not just the frontend) consult `test-tutorial-framework`.
Another useful feature is a bunch of pre-designed layouts and dynamic switching between them.
To learn more about the framework see the [baseimage-tutorial-framework](https://github.com/avatao-content/baseimage-tutorial-framework) repo.
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).
## Components
@ -13,24 +17,58 @@ In this section we are going to explore the various pre-made components this pro
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](https://github.com/avatao-content/baseimage-tutorial-framework/tree/master/lib/tfw/components) directory (this is where the event handler implementations 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 the user and you can switch between.
Layouts describe which components are visible and where they are on the screen.
### Terminal (webshell)
A full-fledged xterm terminal emulator based on xterm.js running right in your browser.
The emulator is connected to a `TerminalEventHandler` instance running on the backend over websockets.
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 the browser and the slave end to `bash`.
This event handler spawns a `bash` session and a `pty` (pseudoterminal).
It connects the master end of the `pty` to the emulator running in the browser and the slave end to `bash`.
This essentially provides a shell running in the browser.
You can write to it and read what commands were executed in `bash` using the API exposed by the `TerminalEventHandler` instance.
This essentially provides a fully functional terminal session in the browser.
You can write to it (and thus execute commands) and read what commands were executed in `bash` using the API exposed by the `TerminalEventHandler` instance.
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 those files 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.
It connects to an `IdeEventHandler` instance on the backend which handles the reading/writing of files and the selection of directories as well.
## Running standalone with yarn
It is also capable of dynamically displaying any changes made to these files from the terminal or any other process (this means that you always see a live view of the files).
Simply execute `yarn start` in the project root.
This will automatically set up proxying of the port `4200` to `8888` (the port this webapp is served on to the port TFW listens on).
### 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
in progress...