Skip to content

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@supertom01
supertom01 committed Mar 18, 2023
1 parent 4c69c68 commit 58c75ca
Show file tree
Hide file tree
Showing 7 changed files with 108 additions and 30 deletions.
16 changes: 14 additions & 2 deletions docs/contact.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,15 @@
# Contact
At this moment the only thing that this module does is rendering the contact page, which is just a static HTML page.
Perhaps at a later moment, this could contain a contact form.
The website makes use of contact forms. With the help of these forms people can send directly a message to either the
entire Future Factory, or just individual teams.

When a message gets send from the home page, it is sent to all the teams, whereas when a message is send through a team
page it will only end up at that specific team.

In order to clean all the data and make it safe for processing we use the `ContactForm` object, using a Django
[Form](https://docs.djangoproject.com/en/4.1/topics/forms/).

The `SendMessage` view, located in `main_site/views.py` takes care of actually sending the email to the correct
destination. At first the form is populated with the data and it is checked. If safe, an email is created and send.
A message indicating that the mail was successfully send will be shown to the user.

In case the form contains any error, the user will be made aware of these errors. Asking them to fix it.
Binary file added docs/images/classdiagram.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/images/classdiagram.png
View file
Binary file not shown.
5 changes: 1 addition & 4 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,6 @@ allowing one to understand on how all of these components work together.
* [Facts](facts.md)
* [News Articles](news_articles.md)
* [Partners](partners.md)

<!-- Go further with updating each document from here. -->
* [Teams](teams.md)
* [Contact](contact.md)
* [Settings](settings.md)
Expand All @@ -28,8 +26,7 @@ Most entities have their own module (also known as [app](https://docs.djangoproj
within this project. This allows for a clear distribution between models, views and other stuff.

### Class Diagram
**TODO: Update the class diagram**
![Class Diagram](images/classdiagram.png)
![Class Diagram](images/classdiagram.jpg)

### Templates
Each page that one sees is built with the Django [template](https://docs.djangoproject.com/en/4.1/ref/templates/) system.
Expand Down
19 changes: 17 additions & 2 deletions docs/settings.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,25 @@ has been deployed. This page will explain these settings.
| Setting | Description |
|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `SECRET_KEY` | The secret key is taken from the environment variable `DJANGO_KEY` |
| `DEBUG` | Based on wether the DEBUG environment variable is set to `true`, we run in a debug mode. Otherwise we run in production mode |
| `DEBUG` | Based on whether the DEBUG environment variable is set to `true`, we run in a debug mode. Otherwise we run in production mode |
| `BETA` | Based on whether the BETA environment variable is set to `true`, the application runs in beta mode. |
| `ALLOWED_HOSTS` | The deployment server runs behind NGINX, which already does host checks. Hence we skip this on the Django side |
| `CSRF_TRUSTED_ORIGINS` | Only these hosts may receive POST requests |
| `DATABASES` | The databases are dynamically chosen based on the `DEBUG` variable. The production database assumes that there are environment variables available for the database name, user and password. The server is expected to be found on `future_factory_db` |
| `QUILL_CONFIGS` | The rich text editor configuration. For more information see its [documentation](https://django-quill-editor.readthedocs.io/en/latest/pages/change-toolbar-configs.html) |
| `STATIC_ROOT` | The location on the deployment server where the static files are stored (part of the code base like .js, .css files) |
| `MEDIA_ROOT` | The location on the server where the media files are stored (uploaded by a user) |
| `MEDIA_ROOT` | The location on the server where the media files are stored (uploaded by a user) |
| `EMAIL_*` | Email related settings, more details can be found in the [Django documentation](https://docs.djangoproject.com/en/4.1/topics/email/#send-mail) |

# Environment variables
For safety reasons all secrets are loaded with the help of environment variables. The following are in use:

| Value | Description |
|---------------------|----------------------------------------------------------|
| `DJANGO_KEY` | Used for the `SECRET_KEY` setting |
| `DEBUG` | Used to determine whether we are running in debug mode |
| `BETA` | Used to determine whether we are running in beta mode |
| `POSTGRES_NAME` | The name of the database used in production mode |
| `POSTGRES_USER` | The username to authenticate at the production database |
| `POSTGRES_PASSWORD` | The password for the production database |
| `EMAIL_PASSWORD` | The password to the email account used for sending email |
21 changes: 21 additions & 0 deletions docs/styling.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Styling
The front-end of this website has been written with the help of [Bootstrap](https://getbootstrap.com/),
[jQuery](https://jquery.com/) and [Themify Icons](https://themify.me/themify-icons). Furthermore, the website
is based of a template provided by DevCRUD (https://devcrud.com).

In order to update the generated `.css` and `.js` files [NodeJS](https://nodejs.org/en) in a combination with
[gulp.js](https://gulpjs.com/) is being used.

When working on the front-end you can find all the images, stylesheets and other files inside the
`/static/public_htnl/assets` folder. When you're done with editing, and you want to see the result locally follow the
following steps:
1. Open a terminal inside of `/static`.
2. If `node_modules` is not yet in this directory, run `npm install`
3. Run `npm start clean`, removing all the old production files.
4. Run `npm start build`, this will start compiling the (s)css, js, compressing images etc. This will take some time,
if you only want to update for example the css, you can do so by running `npm start css` and then `npm start scss`.

## Deployment
This is a note for the person that is responsible for deploying any updates. When asset files have been updated they
might not always be detected by the input-free `collectstatic` command from Django. So if you are missing any new assets
re-run the `python manage.py collectstatic` command by hand.
77 changes: 55 additions & 22 deletions docs/teams.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,19 +6,21 @@ description of their activities.
## Database model
Every team is saved in the database, hence there is a model available for it. Let's go over it:

| Attribute | Description |
|---------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| `name` | The name of this team |
| `contact_person` | The name of the main contact person for this team. Usually the communication or team manager |
| `contact_person_function` | The function of the contact person |
| `contact_person_phone` | The phone number of the contact person, make sure to actually fill out a valid number since people will be able to directily call this from the site |
| `contact_mail` | The mail-address to use when someone wants to contact the team. Often it looks like info@... |
| `website` | The teams website address |
| `banner_picture` | Each page on the website has a picture shown just below the navigation bar. This is the banner picture that will be shown at this team page |
| `logo` | The team's logo. Preferably a high quality PNG image with a transparent background |
| `slogan` | The slogan from the team |
| `team_picture` | This will be the first picture that is shown on the website, for consistency reasons this should be the team picture |
| `slug` | An auto generated field based on the team name. This field is used to generate the URL to the page of this team |
| Attribute | Description |
|---------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `name` | The name of this team |
| `contact_person` | The name of the main contact person for this team. Usually the communication or team manager |
| `contact_person_function` | The function of the contact person |
| `contact_person_phone` | The phone number of the contact person, make sure to actually fill out a valid number since people will be able to directily call this from the site |
| `contact_mail` | The mail-address to use when someone wants to contact the team. Often it looks like info@... |
| `website` | The teams website address |
| `front_page_picture` | The picture that is being shown on the front page inside of the hexagon. This picture should be square. |
| `banner_picture` | Each page on the website has a picture shown just below the navigation bar. This is the banner picture that will be shown at this team page, it will also show up as the picture behind the facts section of this team |
| `logo` | The team's logo. Preferably a high quality PNG image with a transparent background |
| `logo_svg` | The logo in SVG form of this team. This is used on the press page. |
| `main_color` | The accent color being used for headers on the team page, the hexagon overlays and icons on the contact form. |
| `slogan` | The slogan from the team |
| `slug` | An auto generated field based on the team name. This field is used to generate the URL to the page of this team |

### Text Sections
As described above, each team has its own page. These pages contain sections where text and images can be uploaded. In
Expand All @@ -35,13 +37,44 @@ has a title, body and possibly a picture.
These text sections have a pre-determined ordering. Each page is rendered with sections ordered based on their order of
creation. This should suffice, since the admin interface will correspond with final page render.

### TeamFact
Teams have small facts on their own pages. Each teams is enforced to have 3 or 4 of them on their page. Each fact comes
with an icon. These icons are [Themify Icons](https://themify.me/themify-icons) and can be chosen with a dropdown menu.
The database object itself looks like this:

| Attribute | Description |
|-----------|---------------------------------------------------------------|
| `icon` | A string representing a Themify Icon |
| `value` | The big font sized text |
| `context` | A smaller piece of text adding context to the number and icon |
| `team` | To which team does this fact belong? |

This object is inherited from the [Fact](facts.md) object.

### TeamAccount
In order to limit teams from editing each other's data each user account has to be connected to a team. Only then that
specific user account can access the team's details in the [administration](https://futurefactorytwente.nl/admin)
environment.

This model consists out of a one-to-one relation with a Django user and a foreign key with a team object.

## Views
Teams implement two types of views: [`DetailView`](https://docs.djangoproject.com/en/4.1/ref/class-based-views/generic-display/#detailview)
and the [`SendMessage`](contact.md) view.

The first one displays the team page. It therefore uses the team model and a contact form object for form validation.

The second view handles the submission of a new email.

## Templates
For the `DetailView` there is a `team.html` template, which shows all the information about a team. The
`team_thumbnail.html` template generates a single hexagon that can be found on the homepage.

## Creating a new team
When you create a new team in the database, everything should be set up automatically, and you should be good to go.
However, in order to slightly optimize loading times, the navigation bar is hard-coded. Hence, you will have to the new
team to the navigation bar by hand. The easiest way to do this is by going to the new team in the admin environment,
click on "view on site" and copying the URL from this page. It can then be placed into the navigation section located
in `templates/basis.html`. The link should look like this:

```html
<li><a href="/teams/team-name/">Team Name</a></li>
```
When one needs to add a new team, there are quite some steps to be taken.
1. Create a new user account
2. Create a new team in the database
3. Connect the specific account to the team (`TeamAccount`)
4. Figure out a new nice way to represent the teams on the home screen
* You will most likely have to update some CSS and perhaps some HTML
5. Furthermore, you'll want to have to update the FF logo throughout the entire website.

0 comments on commit 58c75ca

Please sign in to comment.