From 9b88740549a06697599ff20f6dc765acf5d0deb9 Mon Sep 17 00:00:00 2001 From: Simon Rozsival Date: Wed, 26 Oct 2016 00:25:47 +0200 Subject: [PATCH] Updated Web application (markdown) --- Web-application.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/Web-application.md b/Web-application.md index bcdb656..5b8a6b0 100644 --- a/Web-application.md +++ b/Web-application.md @@ -2,8 +2,56 @@ ## Description +The *WebApp* is the default user interface of the ReCodEx project. It is a website which users access through their web browsers. +This user interface allows students to join *groups* corresponding to their school classes, submit new *solutions* and see the results as soon as the solution is evaluated by the backend. +Teachers can manage their *groups* by adding and removing *students*, assigning *exercises* and examining the *automatically evaluated solutions* of their students and their total score gained throughout the semester. + +The actions performed by the user are sent to the *API server* over the HTTPS protocol and the web application does not modify the database or access files on ther server directly and all the inputs sent +from the web application are additionally *validated* on the *API server*. + +The *WebApp* is written in *ECMAScript* (often refered to as JavaScript) and HTML5. The [React](https://facebook.github.io/react) library developed by Facebook is used to manage the user interface and the [Redux](http://redux.js.org/) framework +created by Dan Abramov is used to manage the application state. Both of these frameworks are industry standards used in production by many companies worldwide. Many other smaller libraries and components are used, notably the [Immutable.js](https://facebook.github.io/immutable-js) and [Format.js](http://formatjs.io/) by Yahoo via *redact-intl* integration library. + +### Multiplatform approach + +Since the runtime environment of *WebApp* is user's web browser it does not need any installation on enduser's device and does not require any particular platform or non-standard software installed on user's device. +This application is designed and implemented in a way which should be suitable for modern web browsers on both desktop and mobile devices. + ## Architecture +The whole project is written using the next generation of JavaScript refered to as *ECMAScript 6* (also known as *ES6*, *ES.next*, or *Harmony*). Since not all the features introduced in this standard are implemented in today's modern web browsers (like classes and spread operators) +and hardly any are implemented in older versions of web browsers which are currently still in use, the source code is transpiled into the older standard *ES5* using [Babel.js](https://babeljs.io/) transpiler and bundled into a single script file using the [webpack](https://webpack.github.io/) moudle bundler. The need for a transpiler also arises from the usage of the *JSX* syntax for declaring React components. To read more about these these tools and their usage please refer to the [installation section](#Installation). + +### Declarative UI components + +The *React* UI framework enforces the use of reusable components. These components receive input data through so called *props* and can hold it's own internal state. Components can instantiate each other with specific *props* and create a complex component tree throughout composition. + +React automatically re-renderes the components' subtrees whenever some *props* or component's inner *state* changes. To prevent unnecessary renderings and especially slow *DOM* manipulations React uses sophisticated diffing algorithms and minimizes the number of the underlying DOM manipulations like inserting or deleting DOM nodes. + +This allows the components to be written declaratively and makes them highly readable and truly reusable. + +#### Presentational and stateful components + +There are two basic types of React components - presentational and stateful components. + +- **Presentational components** are in fact pure functions which yield their output based solely on the input *props* and application's *context* (i.e. current language). These components are prefered and should be as simple as possible. + +- **Stateful components** are *connected* to the *redux store* and yield information based on the either the *props* and *context*, but also on the current state of the application. These components are more complicated and often make use of React's components' lifecycle methods. *Stateful components* are often refered to as *containers* and the source code files are placed in a separate directories called `src/containers` and `src/pages`. + + - There is no technical difference between *containers* and *pages*. *Pages* are used as "root" components for different pages and are registered in the app's router. + +### The Redux architecture and state management + +*Redux* is an architecture and a library of a predictible state container. The idea comes from the *Flux* architecture which was published by Facebook alongside *React*. This architecture introduces a so-called *unidirectional data flow*: + +- *User* creates **actions** which are then processed by the *dispatcher* +- **Dispatcher** processes *actions* and updates the application state stored in **stores** +- **Stores** which are updated according to the *actions* inform all *components* listening for changes +- **Components** display the new state to the user +- **User** decides on his/her next actions according to the updated information displayed by the *components* + +*Redux* simplifies this architecture by allowing only a single *store* and introducing a special pure function called *reducer* which deterministically transforms *old* state to a *new* state according to the given *action*. The *state* of app is represented by one plain javascript object - a tree - inside the *store*. *Reducer* is commonly a function composed by many simple functions which handle only a small subtree of the whole state. + ## Installation ## Configuration and usage \ No newline at end of file