-## Documentation
+## Introduction
-- **[Technical Documentation](./docs/technical/README.md)**
-- [Work Methodology](./docs/work-methodology.md)
-- [Useful Commands](./docs/useful-commands.md)
-- [Technologies used on Samf4 🤖](./docs/technical/Samf4Tech.md)
-- [Project Specific Commands](./docs/docker-project-specific-commands.md)
-- [Useful Docker aliases](./docs/docker-project-specific-commands.md)
-- [🌐 API documentation](./docs/api-docs.md)
+Samfundet4 is the latest and greatest iteration of samfundet.no. It's built using Django and React.
+
+
+## Documentation Overview
+
+> [!TIP]
+> If you're new, start by going through the [Introduction to Samfundet4](./docs/introduction.md) guide.
-## Installation
+### Frontend
-We have a script that handles all installation for you. To run the script, a Github Personal Access Token (PAT) is required.
-You can make one here https://github.com/settings/tokens/new. Tick scopes `repo`, `read:org` and `admin:public_key`),
-then store the token somewhere safe (Github will never show it again).
+- [Creating react components (conventions)](./docs/technical/frontend/components.md)
+- [Forms and schemas](./docs/technical/frontend/forms.md)
+ - [*Deprecated: SamfForm*](./docs/technical/frontend/samfform.md)
+- [Cypress Setup Documentation](./docs/technical/frontend/cypress.md)
+- [Data fetching and State management](./docs/technical/frontend/data-fetching.md)
-Copy these commands (press button on the right-hand side of the block)
-and run from the directory you would clone the project.
+### Backend
-```sh
-# Interactive
-read -s -p "Github PAT token: " TOKEN ; X_INTERACTIVE=y /bin/bash -c "$(curl -fsSL https://$TOKEN@raw.githubusercontent.com/Samfundet/Samfundet4/master/{bash_utils.sh,install.sh})" && . ~/.bash_profile && cd Samfundet4; unset TOKEN; unset X_INTERACTIVE;
-```
+- [🌐 API documentation](./docs/api-docs.md)
+- [Billig (payment system)](./docs/technical/backend/billig.md)
+- [Seed scripts](./docs/technical/backend/seed.md)
+- [Role system](./docs/technical/backend/rolesystem.md)
+
+### Other
+
+- [Automatic Interview Scheduling](./docs/intervew-scheduling.md)
+
+### Workflow
-
+
+
+Windows
+
+
+
+## Adding it to GitHub
+
+Copy the contents of the `id_rsa.pub` file and go to the [SSH and GPG keys](https://github.com/settings/keys) GitHub
+settings page. Click the green "New SSH key" button, paste the file contents in the big text box, and click "Add SSH
+key".
+
+> [!WARNING]
+> Ensure you copy the right file. `id_rsa` is a private key, never meant to be shared with anyone, unlike `id_rsa.pub`.
+
+## Configuring Git
+
+You can configure Git both locally and globally. Locally meaning your configuration only applies to a specific
+directory (i.e. project), or globally for all directories. Local configuration overrides global configuration.
+
+## Further reading
+
+Want to git gud to become a git god?
diff --git a/docs/install/install-script.md b/docs/install/install-script.md
new file mode 100644
index 000000000..f6297fb1c
--- /dev/null
+++ b/docs/install/install-script.md
@@ -0,0 +1,44 @@
+[**← Back: Getting started**](../introduction.md)
+
+> [!WARNING]
+> This script has not been maintained in a while and may not work.
+
+# Install script
+
+We have a script that handles all installation for you. To run the script, a Github Personal Access Token (PAT) is
+required.
+You can make one here https://github.com/settings/tokens/new. Tick scopes `repo`, `read:org` and `admin:public_key`),
+then store the token somewhere safe (Github will never show it again).
+
+Copy these commands (press button on the right-hand side of the block)
+and run from the directory you would clone the project.
+
+```sh
+# Interactive
+read -s -p "Github PAT token: " TOKEN ; X_INTERACTIVE=y /bin/bash -c "$(curl -fsSL https://$TOKEN@raw.githubusercontent.com/Samfundet/Samfundet4/master/{bash_utils.sh,install.sh})" && . ~/.bash_profile && cd Samfundet4; unset TOKEN; unset X_INTERACTIVE;
+```
+
+Linux/MacOS/WSL
+ +In your terminal, run `ssh-keygen` + +This will generate two files: `~/.ssh/id_rsa` and `~/.ssh/id_rsa.pub`. +
+
+
+Non-interactive (show/hide)
+ +```sh +# Non-interactive +read -s -p "Github PAT token: " TOKEN ; X_INTERACTIVE=n /bin/bash -c "$(curl -fsSL https://$TOKEN@raw.githubusercontent.com/Samfundet/Samfundet4/master/{bash_utils.sh,install.sh})" && . ~/.bash_profile && cd Samfundet4; unset TOKEN; unset X_INTERACTIVE; +``` + + +
+
diff --git a/docs/install/linux-docker.md b/docs/install/linux-docker.md
new file mode 100644
index 000000000..0cdd96296
--- /dev/null
+++ b/docs/install/linux-docker.md
@@ -0,0 +1,14 @@
+[**← Back: Getting started**](../introduction.md)
+
+> [!WARNING]
+> This guide is not complete! Feel free to submit a PR to improve it :-)
+
+# Installing on Linux (Docker)
+
+## Post-install
+
+Now that you've got the project up and running, check out the post-install instructions:
+
+Flags explained (show/hide)
+ +> - X_INTERACTIVE (y/n): determines how many prompts you receive before performing an action. + > curl: +> - -f: fail fast +> - -s: silent, no progress-meter +> - -S: show error on fail +> - -L: follow redirect + ++→ Next: Post-install +
diff --git a/docs/install/linux-native.md b/docs/install/linux-native.md new file mode 100644 index 000000000..272d30990 --- /dev/null +++ b/docs/install/linux-native.md @@ -0,0 +1,14 @@ +[**← Back: Getting started**](../introduction.md) + +> [!WARNING] +> This guide is not complete! Feel free to submit a PR to improve it :-) + +# Installing on Linux (Native) + +## Post-install + +Now that you've got the project up and running, check out the post-install instructions: + ++→ Next: Post-install +
diff --git a/docs/install/mac-docker.md b/docs/install/mac-docker.md new file mode 100644 index 000000000..51d814545 --- /dev/null +++ b/docs/install/mac-docker.md @@ -0,0 +1,60 @@ +[**← Back: Getting started**](../introduction.md) + +# Installing on MacOS (Docker) + +## Requirements + +* [Homebrew](https://docs.brew.sh/Installation) +* [colima](https://github.com/abiosoft/colima?tab=readme-ov-file#getting-started) + or [Docker Desktop](https://www.docker.com/products/docker-desktop/) + * colima can be more performant than Docker Desktop, but is less easy to use + +## Installing + +First clone the Samfundet4 repository. + +```bash +git clone git@github.com:Samfundet/Samfundet4.git +``` + +If you use colima, run `colima start` to start the engine. + +## Environment files + +Both the `frontend` and `backend` directories contain a `.docker.example.env` file. Copy these files to `.docker.env` +and adjust any values as needed. You may for example want to change the default Django superuser username and +password (`DJANGO_SUPERUSER_USERNAME` and `DJANGO_SUPERUSER_USERNAME`). + +## Building + +This builds all the Samfundet4 containers: + +```bash +cd Samfundet4 +docker compose build + +# You can also choose to build only specific containers if you want: +docker compose build frontend backend +``` + +## Running + +This will start the `backend` and `frontend` containers: + +```bash +docker compose up backend frontend +``` + +## Dependency issues? + +Editors/IDEs typically don't have access to installed dependencies which lie inside Docker containers. This means you +may have to install dependencies locally too, in order for your editor/IDE to resolve them. See +the [Editor configuration](../introduction.md#editor-configuration) guide for more information. + +## Post-install + +Now that you've got the project up and running, check out the post-install instructions: + ++→ Next: Post-install +
diff --git a/docs/install/mac-native.md b/docs/install/mac-native.md new file mode 100644 index 000000000..256f79059 --- /dev/null +++ b/docs/install/mac-native.md @@ -0,0 +1,73 @@ +[**← Back: Getting started**](../introduction.md) + +# Installing on MacOS (Native) + +## Requirements + +* [Homebrew](https://docs.brew.sh/Installation) + * MacOS package manager +* [Poetry](https://python-poetry.org/docs/) + * Backend dependency manager +* [yarn](https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable) + * Frontend dependency manager +* [pyenv](https://github.com/pyenv/pyenv) + * Python version manager. Lets you easily install the same Python version that Samfundet4 expects. + +## Installing + +First clone the Samfundet4 repository. + +```bash +git clone git@github.com:Samfundet/Samfundet4.git +``` + +Install the frontend dependencies + +```bash +cd Samfundet4/frontend +yarn +``` + +Install the backend dependencies + +```bash +cd ../backend +poetry install +``` + +Then apply migrations and run seed script (the seed script adds test data to our database) + +```bash +poetry run python3 manage.py migrate +poetry run python3 manage.py seed +``` + +## Environment files + +Both the `backend` and `frontend` directories have an `.env.example` file. In each directory, copy this file to `.env` +and adjust any values as needed. You may for example want to change the default Django superuser username and +password (`DJANGO_SUPERUSER_USERNAME` and `DJANGO_SUPERUSER_USERNAME`). + +## Running + +Start backend: + +```bash +cd backend +poetry run python3 manage.py runserver +``` + +Start frontend: + +```bash +cd frontend +yarn start +``` + +## Post-install + +Now that you've got the project up and running, check out the post-install instructions: + ++→ Next: Post-install +
diff --git a/docs/install/post-install.md b/docs/install/post-install.md new file mode 100644 index 000000000..c20b51c15 --- /dev/null +++ b/docs/install/post-install.md @@ -0,0 +1,36 @@ +[**← Back: Getting started**](../introduction.md) + +# Post-install + +You've now (hopefully) successfully installed and started the Samfundet4 project! What now? + +We recommend spending some time ensuring your editor/IDE is properly configured. This is of course a very subjective +topic, but we give some pointers in the [Editor configuration](../introduction.md#editor-configuration) section. + +After you've set up your editor/IDE, we recommend diving in head-first and just picking +an [issue](https://github.com/Samfundet/Samfundet4/issues) you'd like to solve. Be sure to have +the [Documentation Overview](../README.md) open and ready for *when* you get stuck :-) If you find that some parts of +the documentation are lacking, don't be afraid to create a PR to fix it! + +## Resetting the database + +You'll likely encounter a situation where you'd like to "reset" the database, by deleting all its data and seeding it +again. It's quite easy to do this, the first step is to stop the backend server. Then in the `backend/database` +directory, delete either the `db.sqlite3` if you're running native (or WSL), or the `docker.db.sqlite3` file if you're +running in Docker. + +Then simply start the backend server again. This will automatically create the database file and seed it automatically. + +## Resetting migrations + +If you've done some work in backend and changed/created any models, you'll also have created migration files. You'll +occasionally encounter a situation where you and another developer have both commited migrations with the same number. +Typically the other developer will have gotten their migration file merged to master, resulting in a number conflict in +your branch. + +The easiest way to fix this is to simply delete the migration file you have created, and running the `makemigrations` +command again: + +* Docker: `docker compose exec backend bash` + * Then run the same Poetry command as in the line below +* Native: `poetry run python3 manage.py makemigrations` diff --git a/docs/install/windows-docker.md b/docs/install/windows-docker.md new file mode 100644 index 000000000..aa44d4c91 --- /dev/null +++ b/docs/install/windows-docker.md @@ -0,0 +1,30 @@ +[**← Back: Getting started**](../introduction.md) + +> [!WARNING] +> This guide is not complete! Feel free to submit a PR to improve it :-) + +# Installing on Windows (Docker in WSL) + +## Install WSL + +To run the project in WSL, you obviousy first need WSL. +Follow [this guide](https://learn.microsoft.com/en-us/windows/wsl/install) by Microsoft. The main step is running the +following in an administrator PowerShell or command prompt: + +```shell +wsl --install +``` + +From this point on, any commands you are instructed to run, are meant to be run inside WSL unless otherwise specified. + +## Install Docker + +Next, install docker. Follow [this guide](https://docs.docker.com/desktop/install/windows-install/). + +## Post-install + +Now that you've got the project up and running, check out the post-install instructions: + ++→ Next: Post-install +
diff --git a/docs/install/windows-wsl.md b/docs/install/windows-wsl.md new file mode 100644 index 000000000..20a69c3e5 --- /dev/null +++ b/docs/install/windows-wsl.md @@ -0,0 +1,32 @@ +[**← Back: Getting started**](../introduction.md) + +# Installing on Windows (WSL) + +> [!WARNING] +> When cloning the project, please ensure you do **not** do it inside OneDrive. Working with the project inside OneDrive +> will be incredibly slow in all aspects. + +## Introduction + +The Windows Subsystem of Linux (WSL) lets you run programs which traditionally only run in Linux. + +## Install WSL + +To run the project in WSL, you obviousy first need WSL. +Follow [this guide](https://learn.microsoft.com/en-us/windows/wsl/install) by Microsoft. The main step is running the +following in an administrator PowerShell or command prompt: + +```shell +wsl --install +``` + +This should install WSL with the Ubuntu distribution. + +## Next steps + +Since you now have a working Linux environment, the remaining steps of setting up the project are identical with the +Linux guide, so click the link below to continue the process. + ++→ Next: Installing on Linux (Native) +
diff --git a/docs/intervew-scheduling.md b/docs/intervew-scheduling.md new file mode 100644 index 000000000..4b5db06a0 --- /dev/null +++ b/docs/intervew-scheduling.md @@ -0,0 +1,68 @@ +[**← Back: Documentation Overview**](../README.md#documentation-overview) + +> [!NOTE] +> This document is a work in progress. + +# Automatic Interview Scheduling + +The aim of this document is to describe the Automatic Interview Scheduling system of Samfundet4. + +It's hard to describe concisely how the system works, so this document contains a few different user stories, describing +how each user role would interact with the system. This will hopefully help you get a better understanding of how the +system works. There's probably going to be a bit of unnecessary rambling in this document, feel free to submit a PR to +fix that:) + +First off, this system is **not** meant to be fully automatic, but semi-automatic. We don't want there to be a lot of +magic happening in the background which nobody understands, and we don't want a system that makes changes without user +interaction. Having a system that automatically schedules interviews without any supervision sounds like a recipe for +disaster. + +The goal is to help recruitment admins save time, by +automatically scheduling interviews, something which notoriously takes a long time to do manually. There are so many +edge cases in scheduling interviews, so it's important that the system is intuitive and easy to use. + +The system must also allow each gang to use the scheduling algorithm of their choosing. + +## Admin's perspective + +1. Navigate to my gang's recruitment overview page and click on a position. +2. Hit the "Automatically schedule interviews" button. +3. We are shown a dialog (or page), with a list of interviews the algorithm has suggested. + 1. Each interview suggestion shows the date, time, and partaking interviewers + 2. We are able to manually edit these interviews if we wish. This will allow us to manually edit the date, time, + location and partaking interviewers. +4. We click the submit button, which saves the interviews and sends out emails to affected applicants and interviewers, + notifying them of the upcoming interview. + 1. The email must not contain sensitive information, it should only contain the name of the gang/section/position + the applicant has applied for, as well as the date, time, and location of the interview. + +## Interviewer's perspective + +## User's perspective + +## Algorithms + +Owner refers to either the Gang or Section which owns the position. + +### Samfundet + +1. Fetch all unscheduled interviews for this position. +2. Fetch all rooms booked by Owner (if any) +3. Fetch unavailability data for all interviewers and applicants +4. For each unscheduled interview, do: + 1. + +### UKA/ISFiT + +1. + +### ISFiT + +1. + +## Race conditions and conflict + +The scheduling algorithms described above are very prone to race conditions and conflict if running them at the same +time, which isn't unthinkable since we want to allow multiple people to work on the recruitment system simultaneously. +We solve this by only allowing the interview scheduling to be run by a single process. To run the scheduler, we send a +request to add scheduling for a given position to the queue. The process fetches tasks from the queue and executes them. diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 000000000..6f763d5d0 --- /dev/null +++ b/docs/introduction.md @@ -0,0 +1,36 @@ +[**← Back: Documentation Overview**](../README.md#documentation-overview) + +# Introduction to Samfundet4 + +Welcome to Samfundet4! This guide will introduce you to the technologies used in the project, and guide you through +installing the project on your machine. + +## Technologies + +Samfundet4 is built using [Django](https://www.djangoproject.com/) and [React](https://react.dev/). Django is a Python +framework, which we use as our backend. React is a library for building frontend applications, and we use it with +the [TypeScript](https://www.typescriptlang.org/) language. + +For a more in-depth introduction to all the technologies we use, check out this +document: [Technologies used in Samfundet4](./technical/Samf4Tech.md) + +## Installation + +There are multiple ways of running this project, all with their own pros and cons. Running with +Docker is likely the easiest, but will require some initial setup and tweaking depending on your system. + +Below is a set of install guides for the various methods of installing and running the project, depending on your OS. If +you're not sure which to pick, just ask someone in MG::Web! + +- Linux: [Docker](./install/linux-docker.md) – [Native](./install/linux-native.md) +- MacOS: [Docker](./install/mac-docker.md) – [Native](./install/mac-native.md) +- Windows: [Docker](./install/windows-docker.md) – [WSL](./install/windows-wsl.md) +- [Install script](./install/install-script.md) +- [Post-install instructions](./install/post-install.md) + +## Editor configuration + +* [JetBrains (WebStorm, PyCharm, etc...)](./editors/jetbrains.md) +* [VS Code](./editors/vscode.md) +* [Vim/Neovim](./editors/vim.md) +* [Emacs](./editors/emacs.md) diff --git a/docs/technical/README.md b/docs/technical/README.md deleted file mode 100644 index 75f09d871..000000000 --- a/docs/technical/README.md +++ /dev/null @@ -1,22 +0,0 @@ - -[👈 back](/README.md) - -# Samfundet4 - Technical Documentation - -
-
-### Frontend
-
-- [Creating react components (conventions)](/docs/technical/frontend/components.md)
-- [Forms and schemas](/docs/technical/frontend/forms.md)
-- [Cypress Setup Documentation](/docs/technical/frontend/cypress.md)
-- [Data fetching](./frontend/data-fetching.md)
-
-### Backend
-
-- [Billig (payment system)](/docs/technical/backend/billig.md)
-- [Seed scripts](/docs/technical/backend/seed.md)
-- [Role System](/docs/technical/backend/rolesystem.md)
-
-### Pipelines & Deployment
-- [Pipeline (mypy, biome, tsc, ...)](/docs/technical/pipeline.md)
diff --git a/docs/technical/Samf4Tech.md b/docs/technical/Samf4Tech.md
index defd33130..ecbf8ec2d 100644
--- a/docs/technical/Samf4Tech.md
+++ b/docs/technical/Samf4Tech.md
@@ -1,6 +1,6 @@
-[👈 back](/README.md)
+[**← Back: Introduction to Samfundet4**](../introduction.md)
-# Technologies used on Samfundet4
+# Technologies used in Samfundet4
This text aims to both sum up the main technologies used to develop on Samfundet4 and to get a person with minimal webdev experience up to speed on the most important concepts. There is a lot this text does not cover, which might be found in other docs linked to in the [README](/README.md).
diff --git a/docs/technical/backend/billig.md b/docs/technical/backend/billig.md
index 321743951..7b431350f 100644
--- a/docs/technical/backend/billig.md
+++ b/docs/technical/backend/billig.md
@@ -1,4 +1,4 @@
-[👈 back](/docs/technical/README.md)
+[**← Back: Documentation Overview**](../../../README.md#documentation-overview)
# Billig Integration
diff --git a/docs/technical/backend/rolesystem.md b/docs/technical/backend/rolesystem.md
index 833e73633..b16bc93ec 100644
--- a/docs/technical/backend/rolesystem.md
+++ b/docs/technical/backend/rolesystem.md
@@ -1,4 +1,6 @@
-# Role System
+[**← Back: Documentation Overview**](../../../README.md#documentation-overview)
+
+# Role system
The role system in Samfundet4 builds on the Django "authentication backend" concept. Our system adds
a [custom auth backend](https://docs.djangoproject.com/en/5.0/topics/auth/customizing/). The goal of the system is to
diff --git a/docs/technical/backend/seed.md b/docs/technical/backend/seed.md
index 23c084427..6cc980cd5 100644
--- a/docs/technical/backend/seed.md
+++ b/docs/technical/backend/seed.md
@@ -1,4 +1,4 @@
-[👈 back](/docs/technical/README.md)
+[**← Back: Documentation Overview**](../../../README.md#documentation-overview)
# Seeding
diff --git a/docs/technical/frontend/components.md b/docs/technical/frontend/components.md
index 16edd34ff..25590da5b 100644
--- a/docs/technical/frontend/components.md
+++ b/docs/technical/frontend/components.md
@@ -1,4 +1,4 @@
-[👈 back](/docs/technical/README.md)
+[**← Back: Documentation Overview**](../../../README.md#documentation-overview)
# Components
diff --git a/docs/technical/frontend/cypress.md b/docs/technical/frontend/cypress.md
index fcdc7e0f2..bfb8842ed 100644
--- a/docs/technical/frontend/cypress.md
+++ b/docs/technical/frontend/cypress.md
@@ -1,3 +1,5 @@
+[**← Back: Documentation Overview**](../../../README.md#documentation-overview)
+
# Cypress Setup Documentation
This document outlines the steps for setting up Cypress in your project. Cypress is an end-to-end testing framework designed to make it easy to write and run tests for web applications. This guide will cover how to set up Cypress both in a Docker container and locally on your machine.
diff --git a/docs/technical/frontend/data-fetching.md b/docs/technical/frontend/data-fetching.md
index ebb5b9245..20c1ccce6 100644
--- a/docs/technical/frontend/data-fetching.md
+++ b/docs/technical/frontend/data-fetching.md
@@ -1,19 +1,130 @@
-# Data fetching
+[**← Back: Documentation Overview**](../../../README.md#documentation-overview)
-We use the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) (built into browsers) to fetch data.
-The `fetch` function is quite simple to use. It returns
-a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that resolves to
-the response of the request.
+# Data fetching and State management
+
+We use the [Axios HTTP client](https://axios-http.com/docs/intro) to fetch data. It's quite simple to use, returning a
+[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) resolving to the
+response of the request.
We use [React Query](https://tanstack.com/query/v3) for state management. State management in React is notoriously hard
to get 100% right and safe, which is why using a library such as RQ is a good idea. It saves us from a lot of potential
common bugs and headaches with managing state all by ourselves.
-If you're not convinced, read this [great article](https://tkdodo.eu/blog/why-you-want-react-query) by TkDodo on Why You
-~~Want~~ Need React Query. It explores a lot of common pitfalls/bugs. At the time of me writing this, these
+If you're not convinced, read this [great article](https://tkdodo.eu/blog/why-you-want-react-query) by TkDodo on *Why
+You ~~Want~~ Need React Query*. It explores a lot of common pitfalls/bugs. At the time of me writing this, these
pitfalls/bugs are found absolutely everywhere we do data fetching in Samfundet4. Hopefully over time, we will replace
these instances with safe state management using RQ.
## Getting started
+So how do these two libraries hang together in our project? Well, we typically start by writing a very simple function
+which only contains an Axios call to send a request and return the data from the response. We do this
+in `frontend/src/api.ts`. Then in our components and pages and
+whatnot, we use React Query to be responsible for actually calling this function when needed.
+
+To get started, in our component/page, call the `useQuery` hook like so, providing a query key and the query function:
+
+```ts
+const { data, isLoading, isError } = useQuery({
+ queryKey: ['informationpages'],
+ queryFn: getInformationPages,
+});
+```
+
+The project has a single global *Query Client*. This acts kind of like a global request and response cache. It contains
+all the data fetched by the `useQuery` hook. You can think of it as a simple Key-Value store. In the above example, the
+data fetched by the `getInformationPages` function is stored by the Query Client using the query key. The query key
+therefore needs to be unique for the data we're fetching.
+
+## Query key factory
+
+Since it's extremely important that the query keys are unique, we employ a "query key factory" to generate them for us.
+The factories are all defined in one place ([queryKeys.ts](../../../frontend/src/queryKeys.ts)), which should eliminate
+the possibility of key collisions. Here are some examples of how to use the factories:
+
+```ts
+// Get all information pages
+const { data } = useQuery({
+ queryKey: infoPageKeys.all,
+ queryFn: getInformationPages,
+});
+```
+
+```ts
+// Get specific user
+const { data } = useQuery({
+ queryKey: userKeys.detail(userId),
+ queryFn: () => getUser(userId),
+});
+```
+
+```ts
+// Get information pages with filter
+const { data } = useQuery({
+ queryKey: infoPageKeys.list([search, page]),
+ queryFn: () => getInformationPages(search, page),
+});
+```
+
+## Invalidating data
+
+Sometimes we need to invalidate data which has been fetched. An example case is when we create and save a new object, an
+information page for instance, we want to clear our "information pages" cache, so that when we request all information
+pages again, the data returned includes the new object.
+
+Doing this is quite simple with the query key factory, and we are able to invalidate on multiple levels of granularity:
+
+```ts
+// Invalidate absolutely all information page data
+queryClient.invalidateQueries({
+ queryKey: infoPageKeys.all
+});
+
+// Invalidate all information page lists
+queryClient.invalidateQueries({
+ queryKey: infoPageKeys.lists()
+});
+
+// Invalidate a specific information page's data
+queryClient.invalidateQueries({
+ queryKey: infoPageKeys.detail(id)
+});
+```
+
+## Error handling
+
+We have a very simple error handler defined in the *Query Client*. If the query function returns an error (for instance,
+HTTP 500), we will log it as an error to the console, and display a toast with an error message. This error message is
+by default generic (i.e. "Something went wrong!"), but it can be overwritten by the useQuery-caller if desired. We do
+this using the `meta` and `errorMsg` options in the useQuery hook.
+
+```ts
+const { data, isLoading, isError } = useQuery({
+ queryKey: infoPageKeys.all,
+ queryFn: getInformationPages,
+ meta: {
+ errorMsg: "We couldn't find the pages!"
+ }
+});
+```
+
+In the example above, if `getInformationPages` raises an error, we'll get a toast with "We couldn't find the pages!".
+Note that you can (and should) use translations here as well:
+
+```ts
+const { data, isLoading, isError } = useQuery({
+ queryKey: infoPageKeys.all,
+ queryFn: getInformationPages,
+ meta: {
+ errorMsg: t(KEY.something_something)
+ }
+});
+```
+
+## Further reading
+
+React Query doesn't only have to be used for API calls, we also use it for other async tasks.
+
Please check out the [RQ docs Quick Start](https://tanstack.com/query/latest/docs/framework/react/quick-start).
+
+Also check out TkDodo's (RQ maintainer) [blog posts](https://tkdodo.eu/blog/practical-react-query)
diff --git a/docs/technical/frontend/forms.md b/docs/technical/frontend/forms.md
index 4be7686dd..bb7f23aac 100644
--- a/docs/technical/frontend/forms.md
+++ b/docs/technical/frontend/forms.md
@@ -1,4 +1,4 @@
-[👈 back](/docs/technical/README.md)
+[**← Back: Documentation Overview**](../../../README.md#documentation-overview)
# Forms
@@ -39,7 +39,7 @@ To get started, create a new file, for example `YourForm.tsx`. This file will co
itself. Define a schema using zod. Remember to reuse fields when possible as mentioned in the section above (we won't do
this here for example's sake).
-```typescript jsx
+```ts
import { z } from 'zod';
const schema = z.object({
@@ -51,16 +51,16 @@ Create your form component, and use the `useForm` hook to create the form.
Create the form component, and use the `useForm` hook with your schema,.
-```typescript jsx
+```jsx
export function YourForm() {
// 1. Define the form
- const form = useForm+Be sure to check out the documentation for [Docker command aliases](./docker-project-specific-commands.md). + ### 🐳 Docker: Run command inside container > `
+
+ );
+};
+
+// Basic usage
+export const Basic = Template.bind({});
+Basic.args = {
+ currentPage: 1,
+ totalItems: 100,
+ pageSize: 10,
+};
+Basic.parameters = {
+ docs: {
+ description: {
+ story: 'Basic pagination with default styling',
+ },
+ },
+};
+
+// Many pages example
+export const ManyPages = Template.bind({});
+ManyPages.args = {
+ ...Basic.args,
+ totalItems: 2500,
+ currentPage: 7,
+};
+ManyPages.parameters = {
+ docs: {
+ description: {
+ story: 'Pagination with many pages showing ellipsis',
+ },
+ },
+};
+
+// Minimal pages example
+export const MinimalPages = Template.bind({});
+MinimalPages.args = {
+ ...Basic.args,
+ totalItems: 30,
+ pageSize: 10,
+};
+MinimalPages.parameters = {
+ docs: {
+ description: {
+ story: 'Pagination with only a few pages using text theme',
+ },
+ },
+};
+
+// Example with increased sibling count
+export const SiblingCountTwo = Template.bind({});
+SiblingCountTwo.args = {
+ ...Basic.args,
+ totalItems: 250,
+ siblingCount: 2,
+ currentPage: 5,
+};
+SiblingCountTwo.parameters = {
+ docs: {
+ description: {
+ story: 'Pagination showing two sibling pages around the current page.',
+ },
+ },
+};
+
+// Example with increased boundary count
+export const BoundaryCountTwo = Template.bind({});
+BoundaryCountTwo.args = {
+ ...Basic.args,
+ totalItems: 250,
+ boundaryCount: 2,
+ currentPage: 10,
+};
+BoundaryCountTwo.parameters = {
+ docs: {
+ description: {
+ story: 'Pagination with two boundary pages displayed at the start and end.',
+ },
+ },
+};
+
+// Combination of increased sibling and boundary count
+export const SiblingAndBoundary = Template.bind({});
+SiblingAndBoundary.args = {
+ ...Basic.args,
+ totalItems: 250,
+ siblingCount: 2,
+ boundaryCount: 2,
+ currentPage: 12,
+};
+SiblingAndBoundary.parameters = {
+ docs: {
+ description: {
+ story: 'Pagination showing two sibling pages and two boundary pages.',
+ },
+ },
+};
diff --git a/frontend/src/Components/Pagination/PagedPagination.tsx b/frontend/src/Components/Pagination/PagedPagination.tsx
new file mode 100644
index 000000000..2eb18487a
--- /dev/null
+++ b/frontend/src/Components/Pagination/PagedPagination.tsx
@@ -0,0 +1,115 @@
+import { Icon } from '@iconify/react';
+import classNames from 'classnames';
+import { useMemo } from 'react';
+import styles from './PagedPagination.module.scss';
+import { Pagination, PaginationButton, PaginationContent, PaginationEllipsis, PaginationItem } from './components';
+
+type PagedPaginationPaginationItemType = (number | 'ellipsis')[];
+
+interface PagedPaginationnProps {
+ currentPage: number;
+ totalItems: number;
+ pageSize: number;
+ onPageChange: (page: number) => void;
+ siblingCount?: number; // Controls the number of sibling pages around the current page
+ boundaryCount?: number; // Controls the number of boundary pages on each end
+ paginationClassName?: string;
+ itemClassName?: string;
+}
+
+// Helper function to generate sequential page numbers
+const generateSequentialPages = (start: number, end: number): number[] => {
+ return Array.from({ length: end - start + 1 }, (_, i) => start + i);
+};
+
+// Adjusted ellipsis helper functions
+const showStartEllipsis = (current: number, boundaryCount: number, siblingCount: number): boolean =>
+ boundaryCount > 0 && siblingCount > 0 && current > boundaryCount + siblingCount + 1;
+const showEndEllipsis = (current: number, total: number, boundaryCount: number, siblingCount: number): boolean =>
+ boundaryCount > 0 && siblingCount > 0 && current < total - boundaryCount - siblingCount;
+
+export function PagedPagination({
+ currentPage,
+ totalItems,
+ pageSize,
+ onPageChange,
+ siblingCount = 1,
+ boundaryCount = 1,
+ paginationClassName,
+ itemClassName,
+}: PagedPaginationnProps) {
+ const totalPages = Math.ceil(totalItems / pageSize);
+
+ const paginationItems = useMemo(() => {
+ const pages: PagedPaginationPaginationItemType = [];
+ const startPages = generateSequentialPages(1, Math.min(boundaryCount, totalPages));
+ const endPages = generateSequentialPages(Math.max(totalPages - boundaryCount + 1, boundaryCount + 1), totalPages);
+
+ // Early return for simple pagination case
+ if (totalPages <= 7 + siblingCount * 2 + boundaryCount * 2) {
+ return generateSequentialPages(1, totalPages);
+ }
+
+ // Add boundary pages at the start
+ pages.push(...startPages);
+
+ // Conditionally add start ellipsis
+ if (showStartEllipsis(currentPage, boundaryCount, siblingCount)) {
+ pages.push('ellipsis');
+ }
+
+ // Add sibling pages around the current page
+ const startSibling = Math.max(boundaryCount + 1, currentPage - siblingCount);
+ const endSibling = Math.min(totalPages - boundaryCount, currentPage + siblingCount);
+ pages.push(...generateSequentialPages(startSibling, endSibling));
+
+ // Conditionally add end ellipsis
+ if (showEndEllipsis(currentPage, totalPages, boundaryCount, siblingCount)) {
+ pages.push('ellipsis');
+ }
+
+ // Add boundary pages at the end
+ pages.push(...endPages);
+
+ return pages;
+ }, [currentPage, totalPages, siblingCount, boundaryCount]);
+
+ return (
+ Current page: {currentPage}
+
+
+
+
+
+
+ {paginationItems.map((page, index) => (
+ // biome-ignore lint/suspicious/noArrayIndexKey:
+
+ {page === 'ellipsis' ? (
+ onPageChange(page)}
+ />
+ )}
+
+ ))}
+
+
+
+
+
+
+ );
+}
diff --git a/frontend/src/Components/Pagination/components/Pagination/Pagination.module.scss b/frontend/src/Components/Pagination/components/Pagination/Pagination.module.scss
new file mode 100644
index 000000000..7385cf5f2
--- /dev/null
+++ b/frontend/src/Components/Pagination/components/Pagination/Pagination.module.scss
@@ -0,0 +1,5 @@
+.nav {
+ display: flex;
+ align-items: center;
+ width: 100%;
+}
diff --git a/frontend/src/Components/Pagination/components/Pagination/Pagination.tsx b/frontend/src/Components/Pagination/components/Pagination/Pagination.tsx
new file mode 100644
index 000000000..eb9624caa
--- /dev/null
+++ b/frontend/src/Components/Pagination/components/Pagination/Pagination.tsx
@@ -0,0 +1,8 @@
+import classNames from 'classnames';
+import React from 'react';
+import styles from './Pagination.module.scss';
+
+export const Pagination = React.forwardRef
+
+ {user.first_name} {user.last_name}
+
applicationToRow(application))} />
);
diff --git a/frontend/src/Components/RecruitmentWithoutInterviewTable/components/WithoutInterviewModal.tsx b/frontend/src/Components/RecruitmentWithoutInterviewTable/components/WithoutInterviewModal.tsx
index 2318b9e60..db9fc67a8 100644
--- a/frontend/src/Components/RecruitmentWithoutInterviewTable/components/WithoutInterviewModal.tsx
+++ b/frontend/src/Components/RecruitmentWithoutInterviewTable/components/WithoutInterviewModal.tsx
@@ -1,21 +1,26 @@
import { useState } from 'react';
import { Button, IconButton, Modal } from '~/Components';
-import type { RecruitmentApplicationDto } from '~/dto';
+import type { RecruitmentApplicationDto, RecruitmentUserDto } from '~/dto';
import styles from './WithoutInterview.module.scss';
import { WithoutInterviewList } from './WithoutInterviewList';
type WithoutInterviewModalProps = {
+ user: RecruitmentUserDto;
applications: RecruitmentApplicationDto[];
- applications_without_interview: RecruitmentApplicationDto[];
+ applicationsWithoutInterview: RecruitmentApplicationDto[];
};
-export function WithoutInterviewModal({ applications, applications_without_interview }: WithoutInterviewModalProps) {
+export function WithoutInterviewModal({
+ applications,
+ applicationsWithoutInterview,
+ user,
+}: WithoutInterviewModalProps) {
const [withoutInterviewModal, setWithoutInterviewModal] = useState(false);
return (
<>
-