Mathis/allianceauth
1
0
Fork 0
mirror of https://gitlab.com/allianceauth/allianceauth.git synced 2026-02-06 23:26:19 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' of gitlab.com:allianceauth/allianceauth into v5.x

Browse Source
This commit is contained in:
Joel Falknau
2025-10-26 11:40:21 +10:00
parent 6ab2af79eb bff20ddd5d
commit 05943576a0
94 changed files with 4915 additions and 2510 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/development/custom/aa-framework.md
View File

@@ -13,5 +13,7 @@ The Alliance Auth framework is split into several submodules, each of which is d
framework/api
framework/css
framework/js
framework/templates
framework/svg-sprite
:::

165
docs/development/custom/framework/js.md Normal file
View File

@@ -0,0 +1,165 @@
# JavaScript Framework
This contains some simple JavaScript functions that are used throughout Alliance Auth,
so they can be used by community app developers as well.
The JS file is already loaded in the base template, so it is globally available.
## Functions
The following functions are available in the JavaScript framework:
### isArray()
Checks if the given value is an array.
Usage:
```javascript
/* global isArray */
if (isArray(someVariable)) {
console.log('This is an array');
} else {
console.log('This is not an array');
}
```
### isObject()
Checks if the given value is an object.
Usage:
```javascript
/* global isObject */
if (isObject(someVariable)) {
console.log('This is a plain object');
} else {
console.log('This is not a plain object');
}
```
### fetchGet()
Performs a GET request to the given URL and returns a Promise that resolves with the response data.
Usage:
```javascript
/* global fetchGet */
fetchGet({
url: url,
responseIsJson: false
}).then((data) => {
// Process the fetched data
}).catch((error) => {
console.error(`Error: ${error.message}`);
// Handle the error appropriately
});
```
#### fetchGet() Parameters
- `url`: The URL to fetch data from.
- `payload`: Optional data to send with the request. Can be an object or a string.
- `responseIsJson`: Optional boolean indicating if the response should be parsed as JSON (default is `true`).
### fetchPost()
Performs a POST request to the given URL with the provided data and returns a Promise that resolves with the response data.
Usage:
```javascript
/* global fetchPost */
fetchPost({
url: url,
csrfToken: csrfToken,
payload: {
key: 'value',
anotherKey: 'anotherValue'
},
responseIsJson: true
}).then((data) => {
// Process the fetched data
}).catch((error) => {
console.error(`Error: ${error.message}`);
// Handle the error appropriately
});
```
#### fetchPost() Parameters
- `url`: The URL to send the POST request to.
- `csrfToken`: The CSRF token to include in the request headers.
- `payload`: The data as JS object to send with the request.
- `responseIsJson`: Optional boolean indicating if the response should be parsed as JSON (default is `true`).
### objectDeepMerge()
Recursively merges properties from source objects into a target object. If a property at the current level is an object,
and both target and source have it, the property is merged. Otherwise, the source property overwrites the target property.
This function does not modify the source objects and prevents prototype pollution by not allowing `__proto__`, `constructor`,
and `prototype` property names.
Usage:
```javascript
/* global objectDeepMerge */
const target = {a: 1, b: {c: 2}};
const source1 = {b: {d: 3}, e: 4 };
const source2 = {a: 5, b: {c: 6}};
const merged = objectDeepMerge(target, source1, source2);
console.log(merged); // {a: 5, b: {c: 6, d: 3}, e: 4}
```
### numberFormatter()
Formats a number according to the specified locale.
Usage:
In your template get the current language code:
```django
{% get_current_language as LANGUAGE_CODE %}
```
Then use it in your JavaScript code:
```javascript
/* global numberFormatter */
const userLocale = '{{ LANGUAGE_CODE }}'; // e.g., 'en-US', 'de-DE'
const number = 1234567.89;
const formattedNumber = numberFormatter({
value: number,
locales: userLocale,
options: {
style: 'currency',
currency: 'ISK'
}
});
console.log(formattedNumber); // e.g. "ISK 1,234,567.89" or "1.234.567,89 ISK" depending on locale
```
#### numberFormatter() Parameters
- `value`: The number to format.
- `locales`: The locale(s) to use for formatting (e.g., `en-US`, `de-DE`, `['en-US',
'de-DE']`). If not provided, the browser's default locale will be used and any
language settings from the user will be ignored.
- `options`: Additional options for number formatting (see [`Intl.NumberFormat` documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat))
- `minimumFractionDigits` is set to 0 by default if not provided.
- `maximumFractionDigits` is set to 2 by default if not provided.

60
docs/development/custom/framework/svg-sprite.md Normal file
View File

@@ -0,0 +1,60 @@
# SVG Sprite
An SVG sprite is a collection of SVG images combined into a single SVG file. This allows for efficient loading and management of icons in web applications.
The Alliance Auth framework provides a built-in SVG sprite that contains a selection of icons used in Alliance Auth. This sprite is automatically included in the base template, so you don't need to do anything special to use it.
## Using the SVG Sprite
To use an icon from the SVG sprite, you can use the following HTML syntax:
```html
<svg>
<use href="#[icon-name]"></use>
</svg>
```
Replace `[icon-name]` with the name of the icon you want to use. For example, to use the Alliance Auth logo, you would write:
```html
<svg>
<use href="#aa-logo"></use>
</svg>
```
## Available Icons
The following icons are available in the Alliance Auth SVG sprite:
- `aa-logo`: The Alliance Auth logo
- `aa-loading-spinner`: A loading spinner icon
### Alliance Auth Logo
The Alliance Auth logo can be used with the following code:
```html
<svg>
<use href="#aa-logo"></use>
</svg>
```
### Loading Spinner
The loading spinner can be used with the following code:
```html
<svg>
<use href="#aa-loading-spinner"></use>
</svg>
```
### Mumble Logo
The Mumble logo can be used with the following code:
```html
<svg>
<use href="#aa-mumble-logo"></use>
</svg>
```

50
docs/development/custom/framework/templates.md
View File

@@ -66,3 +66,53 @@ To use it, you can use the following code in your template:
</div>
{% endblock %}
```
### Top Navigation Buttons
To ensure a unified style for top navigation buttons, we provide a template partial for this.
To use it, you can use the following code in your template:
```django
{% block header_nav_collapse_right %}
{% translate "My Awesome Link" as nav_item_title %}
{% url "my_app:my_function" as nav_item_link %}
{% include "framework/header/nav-collapse-button.html" with btn_modifier="success" url=nav_item_link title=nav_item_title fa_icon="fa-solid fa-plus" icon_on_mobile=True icon_on_desktop=True %}
{% endblock header_nav_collapse_right %}
```
This template takes care of the mobile responsiveness and the styling. In mobile view,
the button will be changed to a text link. The icon will be placed in front of the text
link if `icon_on_mobile` is set to `True`.
#### Button Parameters
- `btn_modifier`: (Optional) The button modifier class, e.g. `primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light`, `dark`, `link`. Default is `primary`.
- `url`: The URL the button should point to.
- `title`: The title of the button.
- `fa_icon`: (Optional) The FontAwesome icon class to use, e.g. `fa-solid fa-plus`.
- `icon_on_mobile`: (Optional) Boolean to indicate if the icon should be shown on mobile devices in front of the text link. Default is `False`.
- `icon_on_desktop`: (Optional) Boolean to indicate if the icon should be shown on desktop devices in front of the button text. Default is `False`.
### Top Navigation FontAwesome Icons
To ensure a unified style for top navigation FontAwesome icons, we provide a template partial for this.
To use it, you can use the following code in your template:
```django
{% block header_nav_collapse_right %}
{% translate "My Awesome Link as FontAwesome Icon" as nav_item_title %}
{% url "my_app:my_function" as nav_item_link %}
{% include "framework/header/nav-collapse-icon.html" with fa_icon="fa-solid fa-check-double" url=nav_item_link title=nav_item_title icon_on_mobile=True %}
{% endblock header_nav_collapse_right %}
```
This template takes care of the mobile responsiveness and the styling. In mobile view,
the icon will be changed to a text link. The icon will be placed in front of the text
link if `icon_on_mobile` is set to `True`.
#### Icon Parameters
- `fa_icon`: The FontAwesome icon class to use, e.g. `fa-solid fa-check-double`.
- `url`: The URL the icon should point to.
- `title`: The title of the icon (used as tooltip).
- `icon_on_mobile`: (Optional) Boolean to indicate if the icon should be shown on mobile devices in front of the text link. Default is `False`.

95
docs/development/dev_setup/aa-dev-setup-wsl-vsc-v2.md
View File

@@ -1,6 +1,6 @@
# Development on Windows 10 with WSL and Visual Studio Code
# Development on Windows with WSL and Visual Studio Code
This document describes step-by-step how to set up a complete development environment for Alliance Auth apps on Windows 10 with Windows Subsystem for Linux (WSL) and Visual Studio Code.
This document describes step-by-step how to set up a complete development environment for Alliance Auth apps on Windows with Windows Subsystem for Linux (WSL) and Visual Studio Code.
The main benefit of this setup is that it runs all services and code in the native Linux environment (WSL) and at the same time can be fully controlled from within a comfortable Windows IDE (Visual Studio Code) including code debugging.
@@ -15,9 +15,9 @@ This guide is meant for development purposes only and not for installing AA in a
The development environment consists of the following components:
- Visual Studio Code with the Remote WSL and Python extension
- WSL with Ubuntu (18.04. LTS or higher)
- Python environment on WSL (3.8 or higher)
- MySQL server on WSL
- WSL with Ubuntu (24.04. LTS or higher)
- Python environment on WSL (3.12 or higher)
- MySQL/MariaDB server on WSL
- Redis on WSL
- Alliance Auth on WSL
- Celery on WSL
@@ -30,14 +30,14 @@ This setup works with both WSL 1 and WSL 2. However, due to the significantly be
## Requirement
The only requirement is a PC with Windows 10 and Internet connection to download the additional software components.
The only requirement is a PC with Windows + WSL and Internet connection to download the additional software components.
## Installing Windows apps
### Windows Subsystem for Linux
- Install from here: [Microsoft docs](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
- Choose Ubuntu 18.04. LTS or higher
- Install from here: [Microsoft docs](https://learn.microsoft.com/en-us/windows/wsl/install)
- Choose Ubuntu 24.04 LTS or higher
### Visual Studio Code
@@ -81,7 +81,7 @@ sudo apt-get install python3.10 python3.10-dev python3.10-venv python3-setuptool
Use the following command to install Python 3 with all required libraries with the default version:
```shell
sudo apt-get install python3 python3-dev python3-venv python3-setuptools python3-pip python-pip
sudo apt-get install python3 python3-dev python3-venv python3-setuptools python3-pip
```
### Install redis and other tools
@@ -101,17 +101,7 @@ sudo redis-server --daemonize yes
Install MySQL and required libraries with the following command:
```shell
sudo apt-get install mysql-server mysql-client libmysqlclient-dev
```
:::{note}
We chose to use MySQL instead of MariaDB, because the standard version of MariaDB that comes with this Ubuntu distribution will not work with AA.
:::
We need to apply a permission fix to mysql, or you will get a warning with every startup:
```shell
sudo usermod -d /var/lib/mysql/ mysql
sudo apt-get install mariadb-server mariadb-client libmariadb-dev-compat libmariadb-dev
```
Start the mysql server
@@ -162,12 +152,14 @@ A good location for setting up this folder structure is your home folder or a su
~/aa-dev
|- venv
|- myauth
|- my_app_1
|- my_app_2
|- working
| - allianceauth
| - my_app_1
| - my_app_2
|- ...
```
Following this approach, you can also set up additional AA projects, e.g. aa-dev-2, aa-dev-3 if needed.
Following this approach, you can also set up additional AA projects, e.g. aa-dev-2, aa-dev-3 if needed. this also lets you group all the working applications into a folder so you can still find the parts that are important.
Create the root folder `aa-dev`.
@@ -175,6 +167,14 @@ Create the root folder `aa-dev`.
The folders `venv` and `myauth` will be created automatically in later steps. Please do not create them manually as this would lead to errors.
:::
eg
```shell
mkdir aa-dev
cd aa-dev
mkdir working
```
### Setup virtual Python environment for aa-dev
Create the virtual environment. Run this in your aa-dev folder:
@@ -199,8 +199,19 @@ pip install -U pip setuptools wheel
### Install and create AA instance
if you are not already int he `aa-dev/working` folder `cd` there
```shell
pip install allianceauth
cd aa-dev/working
```
now we are going to install allianceauth from a locally cloned repo
```shell
git clone https://gitlab.com/allianceauth/allianceauth.git
cd allianceauth
pip install -e .
cd ..
```
Now we are ready to set up our AA instance. Make sure to run this command in your aa-dev folder:
@@ -237,6 +248,7 @@ There are two Django settings files: ``base.py`` and ``local.py``. The base sett
```python
DEBUG = True
DISPLAY_DEBUG = False
```
Define URL and name of your site:
@@ -343,7 +355,7 @@ The result should look something like this:
```json
{
"name": "Python: Django",
"name": "Python: Django-Webserver",
"type": "python",
"request": "launch",
"program": "${workspaceFolder}/myauth/manage.py",
@@ -385,6 +397,31 @@ Here is an example debug config for Celery:
},
```
Sometimes you may just need to do a lot of tasks to get data in from ESI.
```json
{
"name": "Python: Celery - No debug 10 Threads",
"type": "python",
"request": "launch",
"module": "celery",
"cwd": "${workspaceFolder}/myauth",
"console": "integratedTerminal",
"args": [
"-A",
"myauth",
"worker",
"-l",
"info",
"-P",
"threads",
"--concurrency=10"
],
"django": true,
"justMyCode": true,
},
```
### Debug config for unit tests
Finally, it makes sense to have a dedicated debug config for running unit tests. Here is an example config for running all tests of the app `example`.
@@ -473,7 +510,7 @@ Install from here. [DBeaver](https://dbeaver.io/)
## Adding apps for development
The idea behind the particular folder structure of aa-dev is to have each and every app in its own folder and git repo. To integrate them with the AA instance, they need to be installed once using the -e option that enabled editing of the package. And then added to the INSTALLED_APPS settings.
The idea behind the particular folder structure of aa-dev is to have each and every app in its own folder under the `working` folder as a git repo. To integrate them with the AA instance, they need to be installed once using the -e option that enabled editing of the package. And then added to the INSTALLED_APPS settings.
To demonstrate, let's add the example plugin to our environment.
@@ -482,8 +519,10 @@ Open a WSL bash and navigate to the aa-dev folder. Make sure you have activated
Run these commands:
```shell
git clone https://gitlab.com/ErikKalkoken/allianceauth-example-plugin.git
pip install -e allianceauth-example-plugin
cd working
git clone https://github.com/ppfeufer/aa-example-plugin.git
cd aa-example-plugin
pip install -e .
```
Add `'example'` to INSTALLED_APPS in your `local.py` settings.