Add chapter explaining components

This commit is contained in:
Kristóf Tóth 2018-12-01 16:39:05 +01:00
parent f84d87a47d
commit 96982dfdcf
3 changed files with 65 additions and 2 deletions

62
content/a_tour_of_tfw.tex Normal file
View File

@ -0,0 +1,62 @@
\chapter{A Tour of TFW}
The purpose of this chapter is to further detail the built-in components
provided by the framework.
As previously mentioned, these components are implemented as event handlers
running in the \texttt{solvable} Docker container and frontend
components written in Angular.
For instance the built-in code editor requires a frontend component and an event
handler to function properly, while the frontend component responsible for
drawing out and managing other components implement no
event handler.
In the Tutorial Framework most of the built-ins define APIs, which are TFW messages
that can be used to interact with them.
For example, to inject a command into the terminal one would use a message like this:
\begin{lstlisting}[captionpos=b,caption={An API Message Capable of Writing in the Terminal}]
{
"key": "shell",
"data":
{
"command": "write",
"value": "echo 'Hello TFW World!'\n"
}
}
\end{lstlisting}
Notice the \texttt{``\\n''} at the end of the command.
By including a newline character, we are also capable of executing commands in the
user's terminal.
Were this newline omitted, the command would only be written to the terminal
(but not automatically executed) for users to inspect and potentially execute themselves.
Some components emit or broadcast messages on specific events, for instance the
\texttt{FSMManagingEventHandler} broadcasts the following message on state transitions:
\begin{lstlisting}[captionpos=b,caption={An FSM Update message}]
{
"key": "fsm_update",
"data" :
{
"current_state": ...string...,
"valid_transitions": ...[array of {"trigger": ...string...} objects]...,
"in_accepted_state": ...boolean...,
"last_event": ...
object like
{
"from_state": ...string...,
"to_state": ...string...,
"trigger": ...string...,
"timestamp": ...unix timestamp...
}
...
}
}
\end{lstlisting}
As you can see this message contains loads of useful information regarding what is
exactly happening in the tutorial at a given point and can be used by client code
to make informed decisions based on this knowledge.
It is not the purpose of this text to provide a complete API documentation, so in the
following I am only going to explain possibilities provided by given components rather
than showcasing actual, real-life API messages.
\section{Messages component}

View File

@ -10,7 +10,7 @@ two Docker images:
whether the user completed the tutorial or not) whether the user completed the tutorial or not)
\end{itemize} \end{itemize}
During most of this capter I am going to be discussing the \texttt{solvable} Docker image, During most of this capter I am going to be discussing the \texttt{solvable} Docker image,
with the exception of section \ref{solutioncheck}, where I will dive into how the with the exception of section~\ref{solutioncheck}, where I will dive into how the
\texttt{controller} image is implemented. \texttt{controller} image is implemented.
The most important feature of the framework is it's messaging system. The most important feature of the framework is it's messaging system.
@ -355,7 +355,7 @@ field is designed for).
In this case the TFW server will only forward privileged messages that In this case the TFW server will only forward privileged messages that
have a valid signature. have a valid signature.
\subsection{Solution checking} \subsection{Solution checking}\label{solutioncheck}
Traditionally most challenges on the Avatao platform implement a Docker image called Traditionally most challenges on the Avatao platform implement a Docker image called
\texttt{controller}, which is responsible for detecting the successful \texttt{controller}, which is responsible for detecting the successful

View File

@ -43,6 +43,7 @@
\include{content/abstract} \include{content/abstract}
\include{content/introduction} \include{content/introduction}
\include{content/architecture} \include{content/architecture}
\include{content/a_tour_of_tfw}
\listoffigures \listoffigures
\lstlistoflistings{} \lstlistoflistings{}