Commit 394bec61 authored by Erlend Ydse's avatar Erlend Ydse
Browse files

Merge branch 'documentation' into 'master'

Documentation

See merge request !14
parents 69b2af61 b10ddd9c
## Structure
# Animal gallery
The App-component is the top component, and all global css classes are defined or imported in App.scss.
## Purpose
# React autogenerated stuff
This project is an assigment in a web development course at NTNU. The task
was to create a website where the user can browse collections of images, text
and audio by choosing from a set of categories.
## Choices
### Technology used
- Javascript
- React
- Syntactically Awesome Stylesheet (Sass)
- We chose to write styles with Sass (.scss) in order to improve readability and avoid having to repeat ourselves when defining CSS-classes. Sass is not considered a framework (it does not add any additional level of abstraction), but rather an extension language for making CSS simpler to write.
### Functionality
The following is a list of user-features which have been implemented in the project:
- [x] Play audio from a loaded audio-element
- [x] Choose a category for which image, audio and text to display
- [x] Interactable log (history) of previously chosen combinations of categories
- [x] Remembering the user's last chosen combination upon revisitting the page
- [x] For the chosen category for a specific media type, the user can browse through all entries of the chosen category.
- [x] Responsive design which lets the user access all functionality on the site -- even when using a narrow screen.
#### Browser storage
We chose to manually cache all fetched data in order to reduce network overhead. Audio could not be fetched easily, but this is cached by the browser by default:
![alt text](common/cached_audio.png "Audio being cached in browser")
Session storage is used for displaying the previous choices which has been made by the user while the tab has been open.
Local storage is used for remembering the user's last choice in order to display it at next visit.
#### Functional components vs class components
In order to be consistent, we chose to use <em>functional</em> components for things that are mainly being "displayed", and <em>class</em> components for more state- and logic-heavy components such as the Content-component. Syntax-wise, functional components look better and have less boilerplate code.
### Styling
#### Layout
We have placed the category picker and the history view in a sidepanel in order to give the main focus to the content itself. A sidepanel is also easy to adapt to a mobile screen. Since we were not allowed to fetch the content of all the compositions at once, we chose to use numbered pagination instead of tabs with the names of the compositions or thumbnails.
Here is an image showing the page's main layout:
![alt text](common/screenshot_1.PNG "Default layout")
#### Style sheets
We have used viewport height and width for the main layout in order to easily resize the page for different screens. Media rules are used to determine the layout on a mobile screen. When these are triggered, the art is arranged in a column to save space, and the side-panel is hidden behind a button.
| Narrow view | Narrow view (with panel extended) |
| :--------------------------------------------------: | :-----------------------------------------------------------------: |
| ![alt text](common/screenshot_2.PNG "Narrow layout") | ![alt text](common/screenshot_3.PNG "Narrow layout and side-panel") |
#### Structure
Structure-wise, we chose to have the styling definitions in their own files with the same name as the component they apply to. Global styles have lowercase names and use category-names in order to organize them properly.
### Component structure
The App-component is the top component and contains a header and the content itself.
The Content-component contains the art, a sidepanel for changing the categories and viewing the history of the last choices, and a paginator for navigating between the compositions.
The Sidepanel-component contains a Tabs-component for navigating between the category form and the history of the last choices. The forms for picking a category for each media type are represented by the CategoryPicker component in order to avoid repetition. History entries are represented by a component for the same reason.
### Testing
#### Component testing
As far as testing components go, we have mostly tested that the components render
without crashing, and we have used unit testing on the CategoryPicker component.
Some simple snapshot tests are also utilized to ensure that components do not
change in unexpected ways between versions. Snapshot tests are mostly considered
for the more simple components. Larger components (containing other smaller components)
were not as suitable for snapshot tests in this project, since we wanted as little coupling in the
codebase as possible.
If you would like to run these tests yourself, you can run
`npm test`
in the terminal (You should of course make sure that you have <em>npm</em> installed.) Make sure you are inside the proper directory "webutvikling-project-2":
<br>
You can also run tests individually by, for example, running:
`jest src.Content.test.js`
(Note that you have to specify the test's path and use <em>jest</em> instead of <em>npm</em>)
#### Browser testing
We've verified that the browser works as expected in the following browsers:
- Firefox
- Chrome
- Vivaldi
- Edge
- Safari
- Kiwi Browser (phone)
- Chrome for Android
- Firefox mobile
This covers the most commonly used evergreen browser engines (Gecko, Webkit, and Blink), so few users should experience problems.
#### Device testing
The website has been tested on the following devices:
Laptops and desktops:
- Lenovo Yoga 520 (14")
- Lenovo Yoga 530 (14")
- Brandless desktop (25")
Phones:
- Oneplus 6T (6.41")
- Motorola G7 Plus (6.2")
### Usage of Gitlab and Git
We've made and assigned issues for all the main requirements and features of the project. In order to connect branches and commits to these issues, we have referenced them in both commits and merge requests.
We've created a branch for each feature and hot-fix in order to maintain a good workflow, and we've used merge requests for reviewing branches before merging to master.
## **\*\*\*\***End of student documentation**\*\*\*\***
---
---
---
# React auto-generated documentation
This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment