Skip to content

Commit f908cc3

Browse files
ashirrwadmilancurcic
ashirrwad
and
milancurcic
authored
Contribution Guide (#37)
* Removed packages imported during dev stage. * Added Contribution Guide to the README * Proper code formating, changed security config img Co-authored-by: milancurcic <[email protected]>
1 parent 17abc35 commit f908cc3

File tree

3 files changed

+139
-5
lines changed

3 files changed

+139
-5
lines changed

‎DESIGN.md

+135
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# The Fortran Playground Design
2+
3+
This document describes the design of the software that implements the Fortran
4+
Playground.
5+
Currently covered is the design of the frontend component of the system.
6+
The design of the backend will be documented in a later update.
7+
8+
The playground consists of a frontend built using React which communicates with
9+
a Flask App responsible for executing user codes in a sandboxed environment
10+
using a Docker Container.
11+
12+
## Frontend
13+
14+
There are various components which handle different parts of the website.
15+
All the styling is done using React-Bootstrap components.
16+
17+
### Editor
18+
19+
We use an Ace Editor port for React called
20+
[React-Ace](https://github.com/securingsincity/react-ace).
21+
All information about Editor settings is stored under `frontend/src/Editor.js`.
22+
The editor settings are passed down as props to the react-ace component and
23+
offer various configuration options check
24+
[this page](https://securingsincity.github.io/react-ace/) to experiment with
25+
different parameters.
26+
For example, to change the theme import it from react-ace library:
27+
```
28+
import "ace-builds/src-noconflict/theme-github";
29+
```
30+
and change the theme prop inside `Editor.js`.
31+
32+
### Navbar
33+
34+
The navbar is configured under `frontend/src/Navbar.js`.
35+
It uses the default bootstrap navbar component.
36+
37+
### Tutorial
38+
39+
The content for tutorial is stored inside the tutorial.json file, which is
40+
generated by the backend from `tutorial.yml` file.
41+
A tutorial part consists of 3 sections- a title, content inside it and the code
42+
for the respective exercise.
43+
To add a new exercise append the three parameters inside the file at
44+
`src/backend/tutorial.yml`, e.g.:
45+
46+
```
47+
- title: Heading for exercise
48+
content: A breif explanation for the topic
49+
code: "Code for the exercise"
50+
```
51+
52+
Restart the server so it can compile the yaml into a JSON.
53+
The changes will be immediately reflected.
54+
To update the tutorial you can commit this JSON to the main repository via a
55+
pull request.
56+
57+
Please make sure that you configure the code properly with proper string
58+
formatting.
59+
This can be done by entering the code inside the editor first and copying the
60+
outputted "code" parameter inside the POST request.
61+
This also ensures your code works properly.
62+
63+
The tutorial is handled by the `TutorialCard` component insidde
64+
`src/TutorialCard.js` with respective props for Heading and Title.
65+
The change for code happens automatically by the `tutFunc` function inside
66+
`App.js` bounded by the switching buttons.
67+
68+
### InputBox
69+
70+
The InputBox is a separate component which has props passed down from `App.js`
71+
to effectively manage state for the input.
72+
73+
### App
74+
75+
The source file `frontend/src/App.js` houses all of our states and major
76+
functionalities (API Calls, Library Selection).
77+
78+
1. States:
79+
* Text: Code inside the editor.
80+
* Output: Output the is received from the backend after execution on container.
81+
* Input: User input for the code that is to be executed
82+
* Exercise: Current exercise the user is on
83+
There are also states which hold information on status for various toggleable
84+
elements on the site:
85+
* isLoading: Spinner until output is received from API
86+
* inputOn: Input box button toggle
87+
* showTutorial: Prompt for the quickstart tutorial
88+
* show: Pop up modal for library selection
89+
* stdlibOn: State that manages whether stdlib has been selected by user or not
90+
2. Buttons for the tutorial are managed by `goRight` and `goLeft` functions,
91+
they iterate on the tutorial.json using `exercise` state.
92+
3. API: POST Request to the backend server is done via `handleClick` function.
93+
The request contains 3 parameters code, the input for it and the libraries
94+
selected by the user.
95+
The response from this request is stored in the output state.
96+
4. Custom styling from buttons is stored under the style tag inside run-button
97+
class.
98+
5. The Output Section is inside the terminal class.
99+
All elements in this section are made via Bootstrap Cards.
100+
The Tutorial Card Component is also inside the terminal class.
101+
6. The Modal Pop up for library selection is also a part of this section.
102+
It holds the switches for libraries toggle.
103+
7. To add a new library in the frontend, add a new `<Form.Check>` component
104+
with appropriate props and create a new state for the library.
105+
For example:
106+
```
107+
const [packageOn, ispackageOn] = useState(false)
108+
```
109+
```
110+
<Form.Check
111+
type="switch"
112+
id="custom-switch"
113+
label="library-name"
114+
onChange{onLibSelect}
115+
checked={packageOn} />
116+
```
117+
Then create a new `onLibSelect` function as follows:
118+
```
119+
const onLibSelect = () => {
120+
setpackageOn(!packageOn);
121+
if(!packageOn){
122+
libs.push("library-name")
123+
}
124+
else{
125+
if(libs.includes("library-name")){
126+
libs = libs.filter(item => item !== "library-name")
127+
128+
}
129+
}
130+
```
131+
132+
### Styling
133+
134+
The styling for the app is defined in `frontend/src/App.css`.
135+
All styles are applied from a single CSS file.

‎README.md

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
# The Fortran Playground
22

33
This is an interactive Fortran playground in the browser.
4-
It's main purpose is for newcomers to easily get a taste for the language
4+
Its main purpose is for newcomers to easily get a taste for the language
55
and learn the essentials of Fortran programming.
66

77
Follow the instructions below if you want to run the Fortran Playground server
88
on your own computer.
9+
For the design of the software, see [this document](DESIGN.md).
910

1011
## Getting started
1112

@@ -96,7 +97,7 @@ curl \
9697
--request POST '127.0.0.1:5000/run' \
9798
--header 'Content-Type: application/json' \
9899
--data-raw '{
99-
"code": "program hello\r\n ! This is a comment line; it is ignored by the compiler\r\n print *, 'Hello, World!'\r\nend program hello\r\n",
100+
"code": "program hello\r\n print *, 'Hello, World!'\r\nend program hello\r\n",
100101
"programInput": "",
101102
"libs" : []
102103
}'
@@ -105,7 +106,7 @@ curl \
105106
If everything is set up correctly so far, you should get the following response:
106107

107108
```
108-
{"executed":" Hello World New Line\n Hello Mars\n"}
109+
{"executed":" Hello, World!\n"}
109110
```
110111

111112
### Set up the frontend server

‎frontend/src/Editor.js

-2
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,7 @@
11
import React from "react";
22
import AceEditor from "react-ace";
33

4-
import "ace-builds/src-noconflict/mode-java";
54
import "ace-builds/src-noconflict/mode-fortran";
6-
import "ace-builds/src-noconflict/theme-github";
75
import "ace-builds/src-noconflict/theme-monokai";
86
import "ace-builds/src-noconflict/ext-language_tools";
97

0 commit comments

Comments
 (0)