From 6f93869dc0de1ea8e3c14062edf8f28e6ca158dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krist=C3=B3f=20T=C3=B3th?= Date: Mon, 23 Apr 2018 18:05:48 +0200 Subject: [PATCH] Continue documenting frontend components --- README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 48 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 1f465f9..40209f6 100644 --- a/README.md +++ b/README.md @@ -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...