diff --git a/Rewritten-docs.md b/Rewritten-docs.md index 15646a4..b2c6392 100644 --- a/Rewritten-docs.md +++ b/Rewritten-docs.md @@ -1663,15 +1663,15 @@ Things like currently available workers or runtime environments are better to be However due to the lack of time automatic monitoring of the backend state will not be implemented in the early versions of this project but might be implemented in some of the next releases. -### Web-app +### The WebApp -The web application is one of the possible client applications of the ReCodEx -system. Creating a web application as a client has several advantages: +The web application ("WebApp") is one of the possible client applications of the ReCodEx +system. Creating a web application as the first client application has several advantages: - no installation or setup is required on the user's device -- works on all platforms including mobile platforms +- works on all platforms including mobile devices - when a new version is rolled out all the clients will use this version without -any need for installing an update manually +any need for manula instalation of the update One of the downsides is the large number of different web browsers (including the older versions of a specific browser) and their different interpretation @@ -1696,17 +1696,7 @@ approach is to render the page on the server as in the previous case but then execute user's actions asynchronously using the `XMLHttpRequest` JavaScript functionality. Which creates a HTTP request and transfers only the part of the website which will be updated. -- **client-side approach** - the opposite approach is to transfer the communication -with the API server and the rendering of the HTML completely from the server directly -to the client. The client runs the code (usually JavaScript) in his/her web browser -and the content of the website is generated based on the data received from the API -server. The script file is usually quite large but it can be cached and does not -have to be downloaded from the server again (until the cached file expires). -Only the data from the API server needs to be transfered over the Internet and -thus reduce the volume of payload on each request which leads to a much more -responsive user experience, especially on slower networks. Since the client-side -code has full control over the UI and a more sophisticated user interactions -with the UI can be achieved. +- **Single Page Application (SPA)** - the opposite approach is to transfer the communication with the API server and the rendering of the HTML completely from the server directly to the client. The client runs the code (usually JavaScript) in his/her web browser and the content of the website is generated based on the data received from the API server. The script file is usually quite large but it can be cached and does not have to be downloaded from the server again (until the cached file expires). Only the data from the API server needs to be transfered over the Internet and thus reduce the volume of payload on each request which leads to a much more responsive user experience, especially on slower networks. Since the client-side code has full control over the UI and a more sophisticated user interactions with the UI can be achieved. All of these approaches are used in production by the web developers and all of them are well documented and there are mature tools for creating websites @@ -1716,9 +1706,35 @@ We decided to use the third approach -- to create a fully client-side applicatio which would be familiar and intuitive for a user who is used to modern web applications. -@todo: please think about more stuff about api and web-app... thanks ;-) +#### Used technologies +We examined several frameworks which are commonly used to speed up the development of a web application. There are several open source options available with a large number of tools, tutorials, and libraries. From the many options there are two main frameworks worth considering: +- **Angular 2** - it is a new framework which was developed by Google. This framework is very complex and provides the developer with many tools which make creating a website very straigtforward. The code can be written in pure JavaScript (ES5) or using the TypeScript language which is then transpiled into JavaScript. Creating a web application in Angular 2 is based on creating and composing components. The previous version of Angular is not compatible with this new version. + +- **React and Redux** - [React](https://facebook.github.io/react) is a fast library for rendering of the user interface developed by Facebook. It is based on components composition as well. A React application is usually written in EcmaScript 6 and the JSX syntax for defining the component tree. This code is usually transpiled to JavaScript (ES5) using some kind of a transpiler like Babel. [Redux](http://redux.js.org/) is a library for managing the state of the application and it implements a modification of the so-called Flux architecture introduced by Facebook. React and Redux are being used for a longer time than Angular 2 and both are still actively developed. There are many open-source components and addons available for both React and Redux. + +We decided to use React and Redux over Angular 2 for several reasons: + +- there is a large community arround these libraries and there is a large number of tutorials, libraries, and other resources available online +- many of the web frontend developers are familiar with React and Redux and contributing to the project should be easy for them +- Angular 2 was still not finished at the time we started developing the web application +- we had previous experience with React and Redux and Angular 2 did not bring any significant improvements and features over React so it would not be worth learning the paradigms of a new framework + +#### User interface design + +There is no artist on the team so we had to come up with an idea how to create a visually appealing application with this handicap. User interfaces created by programmers are notoriously ugly and unintuitive. Luckily we found the [AdminLTE](https://almsaeedstudio.com/) theme by Abdullah Almsaeed which is built on top of the [Bootstrap framework](http://getbootstrap.com/) by Twitter. + +This is a great combination because there is an open-source implementation of the Bootstrap components for React and with the stylesheets from AdminLTE the application looks good and is distingushable form the many websites using the Bootstrap framework with very little work. + +#### WebApp architecture + +The whole project is written using the next generation of JavaScript referred to as *ECMAScript 6* (also known as *ES6*, *ES.next*, or *Harmony*). Since not all of the features introduced in this standard are implemented in today's modern web browsers (like classes and the spread operator) and hardly any are implemented in the older versions of the 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 documentation](#Installation). The whole bundling process takes place at deployment and is not repeated afterwards when running in production. + +##### State management + +@todo: Describe how Redux works +@todo: Describe where which part of the state is persisted (logged in user) and how # User documentation diff --git a/spell.json b/spell.json new file mode 100644 index 0000000..3931944 --- /dev/null +++ b/spell.json @@ -0,0 +1,28 @@ +{ + "language": "en", + "ignoreWordsList": [ + "ReCodEx" + ], + "mistakeTypeToStatus": { + "Spelling": "Error", + "Passive voice": "Hint", + "Complex Expression": "Disable", + "Hidden Verbs": "Information", + "Hyphen Required": "Disable", + "Redundant Expression": "Disable", + "Did you mean...": "Disable", + "Repeated Word": "Warning", + "Missing apostrophe": "Warning", + "Cliches": "Disable", + "Missing Word": "Disable", + "Make I uppercase": "Warning" + }, + "languageIDs": [ + "markdown", + "plaintext" + ], + "ignoreRegExp": [ + "/\\(.*\\.(jpg|jpeg|png|md|gif|JPG|JPEG|PNG|MD|GIF)\\)/g", + "/((http|https|ftp|git)\\S*)/g" + ] +} \ No newline at end of file