Refine README.md

[![fsco.li/portal](./banner.png)](https://portal.fachschaft.cl.uni-heidelberg.de)

# Development

# Portal: this service can fit so many services in it!

## Setup

### with docker

Aren't you tired of having to remember shortlinks or URLs for all the services offered by the Fachschaft? Does it embarrass you to always ask about the agenda of a Fachschaftssitzung, because you never worked with a Taiga implementation? How was the shortlink to Sturacloud again? Are you overwhelmed by 19 (and counting, **fast**) different services offered by the Fachschaft, the Institute and the University?

**Well, that is a thing of the past!** That's why we created Portal, a service-aggregating meta-service for over-zealous students like us, the [fsco.li](fsco.li).

## What is Portal?

Portal is a service that aggregates all the services that the Fachschaft offers. It is a web application that is accessible via the URL [fsco.li/portal](https://portal.fachschaft.cl.uni-heidelberg.de). It is a service that is designed to be user-friendly and easy to use. It is a service that is designed to be accessible to all students, regardless of their technical background and cognitive abilities.

If you are a rather visual learner, we got you covered:

![This will make the purpose of portal clear once and for all.](info-4-devs/metaservice-badboy.png)

## What can you do with Portal?

Most importantly, you can access all the services that the Fachschaft offers in one place. Also, Portal offers

+ a neat LDAP integration

+ a Taiga (fsco.li/todo) integration

+ even a f*cking GitLab integration (we are so proud of this one)

+ an user-friendly interface

+ a responsive design (mostly)

# If you are a contributor...

## I want to setup portal on my local machine!

First you gotta clone this repository.

We advise you to do this with Gitlabs VS Code integration, but you can also use the terminal.

```sh

git clone https://gitlab.cl.uni-heidelberg.de/Fachschaft/portal.git

```

Then you have two options:

### ...with docker

To run a flask shell inside the container:

sudo docker exec -it portal-app-1 flask shell

```

### without docker

### ...without docker

```bash

# mkdir yourself into the portal directory

#### `/portal/static/js`: JavaScript files

Lol, that should actually ![have its own README](JS-README.md).

Lol, that should actually ![have its own README](info-4-devs/JS-README.md).

It contains all the JavaScript files that are responsible for the frontend interactions.

# Which JavaScript files does Portal need to run?

The important JavaScript files can be found in `/portal/static/js/`!

This is mostly Mithril.js.

## `/portal/static/js/components`

[TODO] furtherly explain the components

This is where the frontend components are located. The components are divided into two categories: `pages` and `pieces`. **Mithril.js** uses `pages` to render the main content of the website, while `pieces` are used to render smaller components that are used in multiple places. `pieces` then are embedded into `pages`.

This could help you around

+ [Mithril.js documentation](https://mithril.js.org/)

+ [Convert plain HTML to Mithril](https://arthurclemens.github.io/mithril-template-converter/index.html)

### `/portal/static/js/components/pages`

Generally, everything having its own tab in the Navbar is a `page`. They are the first components that are rendered when the website is loaded.

+ `Base.mjs`

+ `Fachschaftssitzung.mjs`

+ `FsServices.mjs`

+ `Login.mjs`

+ `Me.mjs`

+ `Start.mjs`

+ `UniServices.mjs`

+ `Unlock.mjs`

### `/portal/static/js/components/pieces`

These are the smaller components that are embedded in multiple places.

+ `AccountRequired.mjs`

+ `Agenda.mjs`

+ `BoxedButton.mjs`

+ `ButtonAndTextLink.mjs`

+ `Nav.mjs`

+ `NavPageLink.mjs`

+ `PasswordinVault.mjs`

+ `ServiceLink.mjs`

+ `Toast.mjs`

+ `UnlockRequired`

## `/portal/static/js/model`

### `/portal/static/js/model/Service.mjs`

This renders an individual service.

### `/portal/static/js/model/Services.mjs`

This renders the list of our services.

## `/portal/static/js/account.mjs`

Here, after the login, a session token is created and stored in the `LocalStorage`.

It also responsible for ensuring the validity and non-expiry of the session token.

Users get logged in and logged out here.

## `/portal/static/js/gitlab.mjs`

Arcane magic. We get our Fachschaftssitzung protocols here.

Also, there's some yapping about the Same Origin Policy, might be interesting, but misses a TL;DR.

## `/portal/static/js/portal.mjs`

This is the main file that initializes the Mithril.js app and sets up the routing.