Skip to content

Commit

Permalink
Merge pull request #31 from RoboTeamTwente/documentation
Browse files Browse the repository at this point in the history 
Documentation update
  • Loading branch information
@supertom01
supertom01 authored Mar 18, 2023
2 parents a17f881 + 58c75ca commit 197fb50
Show file tree
Hide file tree
Showing 24 changed files with 290 additions and 149 deletions.
39 changes: 39 additions & 0 deletions docs/_layouts/default.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
<!DOCTYPE html>
<html lang="{{ site.lang | default: "en-US" }}">
<head>
<meta charset='utf-8'>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="{{ '/assets/css/style.css?v=' | append: site.github.build_revision | relative_url }}">
{% include head-custom.html %}

{% seo %}
</head>

<body>

<header>
<div class="container">
<a id="a-title" href="{{ '/' | relative_url }}">
<h1>{{ site.title | default: site.github.repository_name }}</h1>
</a>
<h2>{{ site.description | default: site.github.project_tagline }}</h2>

<section id="downloads">
{% if site.show_downloads %}
<a href="{{ site.github.zip_url }}" class="btn">Download as .zip</a>
<a href="{{ site.github.tar_url }}" class="btn">Download as .tar.gz</a>
{% endif %}
<a href="{{ site.github.repository_url }}" class="btn btn-github"><span class="icon"></span>View on GitHub</a>
<a href="https://futurefactorytwente.nl" class="btn">Visit website</a>
</section>
</div>
</header>

<div class="container">
<section id="main_content">
{{ content }}
</section>
</div>
</body>
</html>
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.
38 changes: 22 additions & 16 deletions docs/events.md
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,27 @@
# Events
An event is something that happened (or will happen) at the Future Factory. Events are small articles where we share
what happened and what was achieved during such event or activity.
An event is some form of activity that starts on a given time and date.

## Database model
Every event is saved in the database, lets take a look at the model that is used.
## Models
There is a single [model](https://docs.djangoproject.com/en/4.1/topics/db/models/) available in this app, which
represents a model.

| Attribute | Description |
|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `title` | The title of this event or article |
| `summary` | A short piece of text that is only shown on the home page and on the news list page |
| `description` | The article itself. Also this field is a `QuillField`, allowing for rich-text. |
| `image` | The image is used as a cover image and shown next to the article |
| `visible` | When you temporarily want to hide this article, but not permenantly remove it, you can set this to `False`. Note: Direct links to this article will keep working |
| `event_date` | The start date of this event |
| Attribute | Description |
|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `title` | The title of this event |
| `summary` | A short piece of text that is only shown on the home page and on the events list page |
| `description` | The main text description this event. Also this field is a `QuillField`, which provides the user a rich-text editor |
| `image` | The image is used as a cover image and shown with this event. |
| `visible` | When you temporarily want to hide this event, but not permanently remove it, you can set this to `False`. Note: Direct links to this article will keep working |
| `date` | The start date and time of this event |
| `location` | Where this event is supposed to take place |

Next to default functions this model has a property named `description_html`. This strips of the new paragraphs after
someone has pressed on enter in the rich-text editor, causing a lot of unnecessary white space.
## Views
For events, both the [`DetailView`](https://docs.djangoproject.com/en/4.1/ref/class-based-views/generic-display/#detailview)
and the [`ListView`](https://docs.djangoproject.com/en/4.1/ref/class-based-views/generic-display/#listview) have been
implemented. The list view sorts the events based on their start date / time. A
[paginator](https://docs.djangoproject.com/en/4.1/topics/pagination/) makes sure that every page has a maximum of eight
events on display at the same time.

## Page rendering
When events are displayed in a list, they are first filtered based on their visibility. Then sorted on the event date.
## Templates
Next to your basic detail and list view templates an event also has a `event_thumbnail.html` template. This template
generates a single event item. This template is both used in the ListView as on the main page.
15 changes: 15 additions & 0 deletions docs/facts.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Facts
A fact is a HTML component that contains a big icon and two short pieces of text. They both appear on the main page and
each team page.

## Models
There are two models that work with facts, the first one named `Fact` represents a single one.

| Attribute | Description |
|:----------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `icon` | An icon is one of the many [Themify Icons](https://themify.me/themify-icons). Icons can be picked from a dropdown menu. Hence all the available choices are generated within the code |
| `value` | This is the big number indicating this fact (maximum of 10 characters) |
| `context` | Some text that is able to give some context to this number (maximum of 50 characters) |

Another model that uses facts is a `TeamFact` which inherits the previously described `Fact` model, adding a team to it.
This model is located in the [teams](teams.md) app.
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.
Binary file added docs/images/hexagons.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.
57 changes: 39 additions & 18 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Future Factory Website Documentation
Over here you can find the documentation for the Future Factory website.

The website is written in Python using the [Django](https://www.djangoproject.com/) framework. At the moment RoboTeam
Twente is the lead maintainer on this website and is also responsible for hosting it. However, this should not discourage
other people from wanting to help and work on this site.
The website is written in Python using the [Django](https://www.djangoproject.com/) framework. At the moment
[Tom Meulenkamp](https://github.com/supertom01/) from RoboTeam Twente is the lead maintainer on this website and is also
responsible for hosting it. However, this should not discourage other people from wanting to help and work on this site.

The code structure attempts to make it easy to search through and is written in a way that should not be too complex for
someone with some experience with the Django framework.
Expand All @@ -12,32 +12,53 @@ Although the code has some documentation incorporated into it, this documentatio
allowing one to understand on how all of these components work together.

## Table of Contents
* [Teams](teams.md)
* [Events](events.md)
* [Facts](facts.md)
* [News Articles](news_articles.md)
* [Partners](partners.md)
* [Teams](teams.md)
* [Contact](contact.md)
* [Settings](settings.md)
* [Styling](styling.md)

## General Information
Most entities have their own module (also known as app) within this project. This allows for a clear distribution
between models, views and other stuff.
Most entities have their own module (also known as [app](https://docs.djangoproject.com/en/4.1/ref/applications/))
within this project. This allows for a clear distribution between models, views and other stuff.

### Class Diagram
![Class Diagram](images/classdiagram.png)
![Class Diagram](images/classdiagram.jpg)

### Navigation bar highlighting
When you're somewhere on the website, your current location is highlighted in the navigation bar. This is done with the
help of the context variable, `current`, that is passed on by each view. The constant strings that are assigned to it
are hardcoded. An example from the TeamView looks like this:
### Templates
Each page that one sees is built with the Django [template](https://docs.djangoproject.com/en/4.1/ref/templates/) system.
Every page extends the `basis.html` template that can be found in `/templates`. This template handles the basis HTML
structure such as meta tags, favicons, the navigation bar and the footer. Each template then
[inherits](https://docs.djangoproject.com/en/4.1/ref/templates/language/#template-inheritance) this basic template and
is able to fill out the following blocks:

```python
def get_context_data(self, **kwargs):
context = super(self).get_context_data(**kwargs)
context['current'] = "teams"
return context
```
* description
* Contains a short description about this specific page. This will be shown in the Google search results.
* title
* The title of the current page.
* head
* Additional HTML that should go into the head, for example additional stylesheets.
* Also, these blocks usually contain additional CSS, for example to override the default background picture in the
header.
* nav_bar
* By default the navigation bar only contains the logo and home button. Any additional buttons should be added with
the following HTML:
```html
<li class="nav-item">
<a class="nav-link" href="_link_location_">Nav item</a>
</li>
```
* content
* The actual contents of this page. This will mainly contain `<section>` elements.
* scripts
* Any JavaScript that should be loaded into the page, this will be placed after the `</body>` tag.

At this moment one can choose between the following constants: `home`, `teams`, `events`, `partners` & `contact`
#### Error pages
If a page cannot be found or the server raises an uncaught exception, the user will see an error message. The templates
for these pages can be found in `/templates` and are named according to their HTTP error codes.

### Automated image compression
Images are automatically compressed, allowing for quick load times and an overall responsive website. This compression
Expand Down
22 changes: 22 additions & 0 deletions docs/news_articles.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# News Articles
A news article is usually some form of article describing a past activity that is related with the Future Factory.

## Models
A single model is used by news articles, the `NewsArticle` model.

| Attribute | Description |
|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `title` | The title of this news article |
| `summary` | A short piece of text that is only shown on the home page and on the news article list page |
| `description` | The main text of this article. Also this field is a `QuillField`, allowing for the end user to add rich-text. |
| `image` | The image is used as a cover image and shown next to the article |
| `visible` | When you temporarily want to hide this article, but not permanently remove it, you can set this to `False`. Note: Direct links to this article will keep working |
| `date` | The start date of this event |

## Views
Just like [events](events.md), news articles implement a Detail and a ListView.

## Templates
The detail view relies on the `news_article.html` template, whereas the list view utilizes the `news.html` template.
Since news articles are used on multiple places a `news_article_thumbnail.html` is able to generate a single news
article. This component is used in both the main page and the list view.
48 changes: 46 additions & 2 deletions docs/partners.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,47 @@
# Partners
At this moment partners are not actively being kept track of in the database. The only thing that this module does is
rendering the partner page, which is just a static HTML page.
Partners are not actively being stored in the database. New partners can be added by modifying the `main.html` and
`partners.scss` files. Let's start out with the structure of the HTML.

## HTML Structure
All the partners are located within the following `div` located in `/main_site/templates/main.html`:
```html
<div id="partner-hexagons"></div>
```

Each partner has their own hexagon, possibly varying in size. However, each hexagon element has the following structure:
```html
<a id="_partner_" class="hexagon _size_ _args_" href="_partner_website_" style="background-color: _hexagon_color_" title="_partner_">
<img src="_partner_svg_logo_" alt="_partner_ logo">
</a>
```
The hexagons are available in three sizes: `small`, `medium`, `large`. The size is added as a class, in the example
above, it is called \_size\_. The medium size has an additional option, the values for this option are either `left` or
`right`. These values indicate whether the third hexagon sticks out either left or right.

Ones filled out, the hexagon should still be positioned correctly within the div, this is done with (S)CSS.

## SCSS Structure
The correct SCSS file can be found at `/static/public_html/assets/scss/partners.scss`. The positioning of the individual
hexagons are located at the bottom of the file. Since they are each positioned relative in the container we have to
define the `top` and `left` coordinates of our div, resulting in a rule looking like:
```scss
&#_partner_ {
top: ;
left: ;
}
```

The offsets have to be calculated by hand. In order to achieve this we can use the known width and height of all the
sizes of hexagons. These can all the accessed as css variables like:
```css
var(--hexagon_size_dimension)
```
where size should be `small`, `medium`, or `big` and dimension should be `height` or `width`.

To help with the positioning the relative dimensions of each hexagon type are shown in the picture below

![Hexagon dimensions](images/hexagons.jpg)

When adding hexagons at the outer edges, be aware of the fact that the width and/or height of the total container will
change. You have to compensate for this by updating the `--hexagon_small_width` and `--hexagon_margin` variables on the
top of the .scss file. Additionally, you will have to update the width and height of the `partner-hexagons` container.
Loading

0 comments on commit 197fb50

Please sign in to comment.