diff --git a/README.md b/README.md index 924797bb3cdbf867dad2976a02c0188c892dcbda..9b7e2e554adf2751eb74a7244a9a1bc3235d6972 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,46 @@ [](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: + + + + +## 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: @@ -12,7 +48,7 @@ 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 @@ -65,7 +101,7 @@ What did you expect? #### `/portal/static/js`: JavaScript files -Lol, that should actually . +Lol, that should actually . It contains all the JavaScript files that are responsible for the frontend interactions. diff --git a/info-4-devs/JS-README.md b/info-4-devs/JS-README.md new file mode 100644 index 0000000000000000000000000000000000000000..743caf1ce330d1737551a476418236d2ec5feabf --- /dev/null +++ b/info-4-devs/JS-README.md @@ -0,0 +1,73 @@ +# 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. + diff --git a/info-4-devs/metaservice-badboy.png b/info-4-devs/metaservice-badboy.png new file mode 100644 index 0000000000000000000000000000000000000000..310cc43c7b21680ce9fd3625ab75f3d911a46de8 Binary files /dev/null and b/info-4-devs/metaservice-badboy.png differ