Frontend - softDsim/softDsim GitHub Wiki
The Node Package Manager is required for installing and building the frontend project. It handles the installation of all main libraries and requirements. During the development phase, the command
npm i
inside the root frontend folder is required to install all packages and requirements. Once all packages and requirements are installed, the command
npm start
can be used to start the frontend project in development mode. During this phase, all changes made in any file will lead to a rerender of said file. To deploy the project on a server, the command
npm build
is required. All these commands can be found inside the file package.json.
The .env file represents secret variables that are used throughout the project. It is located in the project’s root folder. In this particular case, only one variable is required:
REACT_APP_DJANGO_HOST
This variable represents the available endpoint for all API requests that are used throughout the application.
The following section describes which libraries are used in the frontend and for which purpose.
To install libraries use:
npm i <library-name> –legacy-peer-deps
The parameter –legacy-peer-deps is necessary, because of incompatibilities of react version 18 and the library react-beautiful-dnd.
React is used as the main frontend library. It is a component-based library to build user interfaces.React uses JSX.
React is used as the main frontend library. It is a component-based library to build user interfaces.React uses JSX.
Chakra UI is a modular and accessible component library that gives you building blocks you need to build a react application. It includes predefined components, has its own design system and is easily adjustable.
React Router Dom is a library which extends react and adds routing to the react application. It is a fully featured client-side routing library. The application uses React Router Dom V6.
https://reactrouter.com/docs/en/v6
React Icons allows the use of popular icons of different ui libraries like material design, heroicons, font awesome and so on.
https://react-icons.github.io/react-icons
React Beautiful DnD is an accessible drag and drop library for lists by Atlassian. It is used in the Scenario Studio to add drag and drop functionality.
https://github.com/atlassian/react-beautiful-dnd
React Apex Charts is a modern charting library. It helps to create interactive visualizations.
https://www.npmjs.com/package/react-apexcharts
Immer is a library to handle complex states in react. The state of the Scenario Studio is a complex nested data structure which is not easy to partially update. That is where immer is used. It simplifies updating the immutable state of the Scenario Studio.
https://immerjs.github.io/immer/
Dotenv is a module that loads environment variables from a .env file into the environment and makes it accessible in the code.
https://github.com/motdotla/dotenv
├───App.jsx
├───components
│ ├───Navbar.jsx
│ ├───MarkdownDisplay.jsx
│ └───…
├───context
│ ├───AuthProvider.jsx
│ └───UserContext.jsx
├───images
├───pages
│ ├───ScenarioStudio.jsx
│ ├───ScenarioOverview.jsx
│ ├───Simulation.jsx
│ └───…
└───utils
App.jsx
The App.jsx file is part of the src folder located in the react project. It is the core component of the application and specifies how a user view is rendered. The function App() returns a standard background colour for the application and the actual content of a page. In this particular case, it furthermore contains a navbar and a footer for each page that is displayed. Their implementation will be further explained in chapter 5. Additionally, the is always used to check a user’s permissions for each interaction as some pages can only be viewed as an admin or staff member. The is responsible for displaying the requested pages.
Components
The components folder contains every component that is used in this application. To enhance the scalability of the project, they are atomic and generic and thus can be used in new pages as well. To enhance the folder structure, there are separate folders for the Scenario Studio and the Simulation, as they contain many underlying components. A technical description of the implementation can be found in chapter 5.
Context
The files that are stored in the context folder provide global functionalities. Currently, there are AuthProvider.jsx and UserContext.jsx. For example, the AuthProvider.jsx is used to check the user’s permissions at any time and, therefore, display only the permitted pages. Consequently, a user of the role ‘student’ cannot view the User Management.
Images
The image folder contains every graphic that is used on the application. Currently, the folder consists of the landing page graphic, the logo, a help page image and old logos. New images can be added by copying them into this folder and referencing them in the source code.
Pages
Similar to components, the pages folder contains every page that is used for this project. Often, pages contain components to enhance the interaction of possibilities. Each page must include a return() statement that will be rendered by the App.jsx. Additionally, there always has to be an export at the end of each page. This is used to import a page to the Routing.jsx file, which is called through App.jsx. A specification of each page can be found in chapter 4.
Utils
The utils folder currently only contains the file utils.js. As the name indicates, it is used to provide minor global functionalities. For example, the constant role that contains all the different permission classes that are displayed in the User Management. In this file, constants and functions can be implemented and used to make utility functions available for multiple pages.
Requirement: A staff member must be able to create and download a list of user accounts with respective auto-generated passwords for the web application.
Description: This page provides a staff member with the necessary tools to create a list of accounts for the web application. The staff member can change different parameters to create a variety of users and download them afterwards.
Functionality and Components: The page contains four input fields representing all available parameters in the user creating method: Prefix, count, password length and starting index. The user can then send these values to the project backend where all users are created and returned. These return values are then revised into a csv format and can be downloaded. During all stages, the inputs, and functions are checked for errors, which will be presented to the staff member when occurred.
Requirement: An application which handles user data is required to provide an in- depth privacy policy.
Description: This page provides the privacy policy and contact information of the controller.
Functionality and Components: This page uses simple heading, text and grid elements to display the entire privacy policy.
Requirement: Users should be able to access a quick help section, containing the most relevant info about the usage of the web application.
Description: This page provides texts and images to explain functions to the user.
Functionality and Components: The page is built by simple tabs from the ChakraUI framework and contains the fitting text and images for each help section.
Requirement: The web application should contain a page that provides an imprint for legal purposes.
Description: This page provides the imprint texts and contact information of the provider.
Functionality and Components: This page uses simple heading, text and grid elements to display the entire privacy policy.
Requirement: The web application should provide a starting page for non-logged in users or first time visitors.
Description: The landing page (path:”.../”) provides a welcome page that enables the user or visitor to login.
Functionality and Components: This page simply contains a welcome container with some text and a login button. Pressing the login button redirects the user to the login page that is described in the following paragraph.
Requirement: A user should be able to verify himself and access all parts of the web application.
Description: This page provides a user id input, a password input, a privacy policy checkbox, a link to the privacy policy page, a link to the forgot password page and a login button.
Functionality and Components: The input fields are provided by ChakraUI and contain different verification function calls to catch false inputs. Only with validated inputs and after checking the checkbox, a login is possible. When clicking the login button, the entered values are sent to the backend api to verify the user. If the verification was successful, a session id is returned and saved as a cookie. This session id will be used as a verification token during further use of the web application. All errors are handled by a verification state and displayed in the login section.
Requirement: During an earlier stage of the development of the web app, it was required for every visitor to be able to register oneself using a valid fra-uas-domain. Throughout the course of the project, this requirement changed into giving the respective lecturer/professor/admin the possibility to create multiple users (students) at once.
Description: This page provides a user id input, two password inputs (the second one for confirmation), a privacy policy checkbox, a link to the privacy policy page and a register button.
Functionality and Components: Takes the user id input and password input and validates them. The password validation checks for at least 6 characters and at least one number. The repeated password input must be equal to the first password input. When clicking the register button, a function is called to make a POST-call to the project backend, registering the user. If the registration fails, an error message will be displayed. A simple state handles whether the password should be visible during entering or hidden. This state can be changed by a button next to the password input field.
Requirement: When a user forgets his password, he should be able to reset his password and create a new one.
Description: This page provides a simple user id input to send a reset password page to the application backend. During this stage of development, the endpoint, and functionality is not available, and thus this page cannot provide its core functionality yet.
Functionality and Components: This page uses a simple input element provided by ChakraUI and provides states for error handling to use during further development.
Requirement: A user should be provided with a simple overview of all playable simulations.
Description: Here the user can see all playable simulations and his highest score for each simulation. A staff member can also delete simulations here using the trash can icon.
Functionality and Components: This page gets all playable simulations from the application backend and lists them as individual elements. A click on a simulation will redirect the user to the simulation page, where the user can play the full scenario. When deleting a simulation as a staff member, a warning message will pop up and will ask the user if he really wants to delete the scenario. Clicking on yes will delete the scenario using a backend api call.
Requirement: Building an editor which is easy to use and flexible to create complex scenarios.
Description: The page is split into two separate parts. The major part is the editor, where a user can drag and drop components. The minor part is the tab menu where the user can switch between the component and the inspector tab. The component tab contains all components the user can choose from and which can be dragged to the editor. The inspector tab provides information about the selected component and is specific for each component type and contains data for each individual component.
Functionality and Components: Main state of the scenario studio is the editorList. The editorList contains all components which are dragged to the editor with their information. When the user clicks the “Save Template”-Button the editorList will be sent to the backend and a scenario will be generated. To edit the complex editorList state the function onDragEnd is quite complex to allow all the different types of components and nesting. The scenario studio page also handles the selection of the components.
Requirement: This page resembles the main part of the application and provides a playable simulation. It should feature a dashboard and an action tab to ensure a user friendly interaction.
Description: This Page is split into two main parts, with the left side representing information about the current run and the right side offering all possible user input depending on the point of time during the game. Those feature questions, a model selection, simulation fragments, events and a result page.
Functionality and Components: The split between these two main containers is achieved using inline styling and various ChakraUI components. On the left side an additional library is the React Apex Charts, which renders information during the simulation. The right side, representing the user input, is achieved mainly by using basic ChakraUI elements that exchange data between themselves and the Simulation.jsx parent component. Additionally the Simulation.jsx page handles all API calls and data models and states required for playing the simulation. An explanation of each component used in the simulation can be found in chapter 5. Used components are found in the component sub folder Simulation and the import section.
Requirement: A staff member should be able to see all registered user accounts and manage them.
Description: This page provides a list of all registered user accounts and management actions: delete, role change. The staff member can also register a single user using the add user button.
Functionality and Components: This page uses simple heading, text and grid elements to display the entire privacy policy.
Description: This component handles the following user inputs during the simulation: Bugfix, Unit Test, Integration Test, Meeting, Training, Team Event, Salary, Overtime.
Input: Simulation values from a simulation fragment, which contain the desired actions.
Functionality: When given a specific action, the component renders the requested action.
Description: This component holds the design for some actions in Action.jsx and renders them accordingly.
Input: Title, secondary title, icon and a tooltip. Additionally other components can be rendered inside.
Functionality: Renders action with provided values and HTML-Tags.
Description: Renders the drop down menus for Salary and Overtime.
Input: The desired type for rendering, either “salary” or “overtime” and the available selection options.
Functionality: Renders the desired type and returns a default object without user input and on user input returns the selected values.
Description: Simple switch form with heading.
Input: Only a heading value is required.
Functionality: Return the selected state from switch, either true or false.
Description: Simple switch form but represented by a button.
Input: No input required.
Functionality: Selection is represented by the button style: gray for false and blue for true. Clicking the button also fires an event, giving the input to it’s parent component.
Description: Renders single and multiple choice questions.
Input: A question collection containing the type (single/multiple choice) and an array of possible answers.
Functionality: During the initial rendering process, a list of answers is generated containing all answers with false as the selected state. The state can be changed by user input. During both instances, the entire array answer objects is sent to the parent component.
Description: Renders a single answer in Question.jsx
Input: Radio button or Checkbox with answer string.
Functionality: Renders the stack of possible answers.
Description: Renders a single skilltype in SkilltypeContainer.jsx.
Input: Skilltype name, skill type current count, the count change.
Functionality: Displays a single skilltype with an image, heading, values and buttons. Return the buttons input from user (adding or removing skilltype count).
Description: Renders all skilltype elements in a closable container.
Input: List of available skill types.
Functionality: Contains an ActionElement.jsx to display the skill type image, text and tooltip. On click the container opens and reveals all available skill types and renders them using Skilltype.jsx.
Description: Renders the text from an Event during a simulation.
Input: Markdown text from an Event.
Functionality: Uses the MarkdownDisplay.jsx to nicely render the provided text from an Event.
Description: Renders all provided result values with an icon at the end of an simulation.
Input: Result parameters during the Result response in a simulation.
Functionality: Renders a result point using the ResultElement.jsx element.
Description: Renders a single result score with an image.
Input: Title, description text and icon.
Functionality: Uses the text and image prop to render a result element.
Description: Renders a modal providing the input of an user id and a password to create a user. Additionally provides a closing button, description modal and register button.
Input: No Input required.
Functionality: Takes the user id input and password input and validates them. The password validation checks for at least 6 characters and at least one number. The repeated password input must be equal to the first password input. When clicking the register button, a function is called to make a POST-call to the project backend, registering the user. If the registration fails, an error message will be displayed. A simple state handles whether the password should be visible during entering or hidden. This state can be changed by a button next to the password input field.
Description: Represents the bottom section of the web application, containing the project name and links to all legal pages.
Input: No Input required.
Functionality: Contains a simple text element for the project name and link elements for the legal pages.
Description: Renders string in the markdown format nicely.
Input: Markdown string.
Functionality: Uses the react-simpplemde-editor library to display markdown text with html elements given a uniform style template.
Description: Renders the model selection during a simulation.
Input: Array of available models (strings).
Functionality: Uses a simple button element to render the given model name and an icon. The icons are chosen by the model type (waterfall, scru, kanban).
Description: Represents the top section of the web application, containing the logo, links and option button.
Input: No Input required.
Functionality: The logo is taken a and image element with the source coming from the image folder. The menu items, all being clickable link elements, lead to different pages, handled in Routing.jsx. Some menu items are hidden if the user does not have the required authentication to even view the page that a link leads to. The option button on the right side is a menu element containing the logout button/text can call the logout function to logout the user.
Description: The catch all component, when a user tries to access an unhandled route.
Input: No Input required.
Functionality: Shows the user a simple image using an image element and provides a button that links back to the starting page.
Description: Renders a stack of available radio button choices.
Input: No Input required.
Functionality: Uses the RadioGroup and Radio element from ChakraUI to render a simple single choice selection.
Description: Simple component to scroll the user view back to top of the page.
Input: No Input required.
Functionality: Uses the default window.ScrollTo function to get the users view back to top.
Description: The component allows the user to drag different components from the tab to the scenario studio editor.
Input:Final component list which contains data for each component type. Component types are: BASE, FRAGMENT, MODELSELECTION, QUESTIONS and EVENT.
Functionality: An unordered list rendering ComponentTabItems which contain the data for the different components. The unordered list is wrapped by a Droppable to allow dragging the components from this list.
Description: A component which can be dragged from the component tab.
Input: Id, title, content and icon are passed through this component to the ComponentListElement. The index is used for the Draggable to know its position in the list when dragged.
Functionality: A wrapper around the ComponentListElement to provide drag functionality.
Description: Represents the presentational layer of a ComponentTabItem. Displays title, icon and content for a component the user can choose from.
Input: Title, content and icon which are rendered.
Functionality: No further functionality. Just displaying data.
Description: Represents a basic component in the editor. Can be dragged around and display title, content and icon.
Input: HandleSelect function to get selected. The index is used for the Draggable to know its position in the list when dragged. The component contains the data like title and icon, and isSelected evaluates an expression, if the component is currently selected.
Functionality: No further functionality. Just displaying data and being able to get dragged around.
Description: Represents a component in the editor which has a sublist which can contain subcomponents like actions or questions
Input: HandleSelect function to get selected. An id and a title. The component data like displayName and so on. The droppableType describes if a question or an action can be attached as a sublist item. IsSelected evaluates an expression, if the component is currently selected.
Functionality: Displays the data like title, content and icon and has a EditorSubListComponent which can be extended by dropping elements inside this list. The EditorSubListComponent can be expanded and collapsed.
Description: Represents the presentational layer of a ComponentTabItem. Displays title, icon and content for a component the user can choose from.
Input: Title, content and icon which are rendered.
Functionality: No further functionality. Just displaying data.
Description: Represents the presentational layer of a ComponentTabItem. Displays title, icon and content for a component the user can choose from.
Input: Title, content and icon which are rendered.
Functionality: No further functionality. Just displaying data.
Description: Input form to specify base information of a scenario in the scenario studio.
Input: Component base data which is needed to fill values when the user already entered data. Update editor list is needed to save the data in the state of the scenario studio and finally set selected object is needed to check if the component is selected and to display a blue border.
Functionality: Input form for the user to set the scenario name, the story, the duration, budget, easy tasks, medium tasks and hard tasks.
Description: Input form for actions where you can specify for example the minimum and maximum amount of meetings and so on. Renders conditionally for different types of actions
Input: Action data which is needed to fill values when the user already entered data. Update editor list is needed to save the data in the state of the scenario studio and finally set selected object is needed to check if the component is selected and to display a blue border.
Functionality: Input form to set upper and lower limit for specific actions.
Description: Input form to specify event information of a scenario in the scenario studio.
Input: Event data which is needed to fill values when the user already entered data. Update editor list is needed to save the data in the state of the scenario studio and finally set selected object is needed to check if the component is selected and to display a blue border.
Functionality: User is able to set options for the event name and the story. Furthermore she is able to set a conditional trigger when the event should appear in the simulation. Then she can specify the impact which is optional. An event can have an impact on budget, duration, number of easy tasks, number of medium tasks, number of hard tasks, stress, motivation and familiarity.
Description: Input form to specify fragment information of a scenario in the scenario studio.
Input: Fragment data which is needed to fill values when the user already entered data. Update editor list is needed to save the data in the state of the scenario studio and set selected object is needed to check if the component is selected and to display a blue border. Furthermore there is the final action list which is a list of all actions the user can choose from.
Functionality: User input form with drag functionality for actions which can be chosen from a list.
Description: User input form to select a management model in the scenario studio.
Input: Model selection data which is needed to fill values when the user already entered data. Update editor list is needed to save the data in the state of the scenario studio and finally set selected object is needed to check if the component is selected and to display a blue border.
Functionality: Specifying name for component, a story and the models which should be displayed in the simulation.
Description: User input for a questions component in the scenario studio.
Input: Questions data which is needed to fill values when the user already entered data. Update editor list is needed to save the data in the state of the scenario studio and set selected object is needed to check if the component is selected and to display a blue border. Furthermore there is the final question list which is a list of all question types the user can choose from.
Functionality: Specify Questions name, a story and choose between single and multiple questions of a drag list.
Description: User input for a single question. Question can be of type single or multiple choice.
Input: Question data which is needed to fill values when the user already entered data. Update editor list is needed to save the data in the state of the scenario studio and set selected object is needed to check if the component is selected and to display a blue border.
Functionality: Add a question and up to six answers. The answers can have points.
Description: Represents the presentational layer of an answer. Displays answer string and points.
Input: Points and answer string.
Functionality: Displaying data and getting user input for string and points.
Description: Represents a textarea which can contain markdown and which can expand to a rich editor.
Input: Data of the component which uses the markdown editor and update editor list to change scenario studio state.
Functionality: Displaying and inputting markdown.
Description: Renders drag list for actions or questions.
Input: A droppable id, an item list to specify which elements to render in the list, the type of those elements and a headline. Optionally an addActions function.
Functionality: Displays draggable items.
Description: Display a single element inside an inspector item selector.
Input: Title, content and icon which are rendered.
Functionality: No further functionality. Just displaying data.
Description: Inspector empty is displayed if there is no form available for a selected component in the scenario studio.
Input: Title to show type of component.
Functionality: No further functionality. Just displaying data.
Description: Specific button which is reused to delete components in the scenario studio editor. Opens modal to confirm deletion.
Input: Component data, especially component type is needed to find component which should be deleted. Update editor list to update the state of the scenario studio and set selected object to set it to null, because after deletion there is no component selected.
Functionality: No further functionality then deleting a component on click on the button.
