mirror of
https://gitlab.com/allianceauth/allianceauth.git
synced 2025-07-09 12:30:15 +02:00
bb2e0aabbc
### Added - `main_first` option to move the main character to the first position of the character list ### Changed - Character list sorted alphabetically
118 lines
3.7 KiB
Markdown
118 lines
3.7 KiB
Markdown
# Alliance Auth Helper-Functions API
|
|
|
|
The following helper-functions are available in the `allianceauth.framework.api` module.
|
|
They are intended to be used in Alliance Auth itself as well as in the community apps.
|
|
|
|
These functions are intended to make the life of our community apps developer a little
|
|
easier, so they don't have to reinvent the wheel all the time.
|
|
|
|
## EveCharacter API
|
|
|
|
### get_main_character_from_evecharacter
|
|
|
|
This is to get the main character object (`EveCharacter`) of an `EveCharacter` object.
|
|
|
|
Given we have an `EveCharacter` object called `my_evecharacter` and we want to get the main character:
|
|
|
|
```python
|
|
# Alliance Auth
|
|
from allianceauth.framework.api.evecharacter import get_main_character_from_evecharacter
|
|
|
|
main_character = get_main_character_from_evecharacter(character=my_evecharacter)
|
|
```
|
|
|
|
Now, `main_character` is an `EveCharacter` object, or `None` if the `EveCharacter` has no main character.
|
|
|
|
### get_user_from_evecharacter
|
|
|
|
This is to get the user object (`User`) of an `EveCharacter` object.
|
|
|
|
Given we have an `EveCharacter` object called `my_evecharacter` and we want to get the user:
|
|
|
|
```python
|
|
# Alliance Auth
|
|
from allianceauth.framework.api.evecharacter import get_user_from_evecharacter
|
|
|
|
user = get_user_from_evecharacter(character=my_evecharacter)
|
|
```
|
|
|
|
Now, `user` is a `User` object, or the sentinel username (see [get_sentinel_user](#get_sentinel_user))
|
|
if the `EveCharacter` has no user.
|
|
|
|
## User API
|
|
|
|
### get_all_characters_from_user
|
|
|
|
This is to get all character objects (`EveCharacter`) of a user (alphabetically sorted).
|
|
|
|
Given we have a `User` object called `my_user` and we want to get all characters:
|
|
|
|
```python
|
|
# Alliance Auth
|
|
from allianceauth.framework.api.user import get_all_characters_from_user
|
|
|
|
characters = get_all_characters_from_user(user=my_user, main_first=False)
|
|
```
|
|
|
|
Now, `characters` is a `list` containing all `EveCharacter` objects of the user.
|
|
If the user is `None`, an empty `list` will be returned.
|
|
|
|
The second parameter `main_first` is optional and defaults to `False`.
|
|
If set to `True`, the function will return the main character as the first
|
|
item in the list of characters.
|
|
|
|
### get_main_character_from_user
|
|
|
|
This is to get the main character object (`EveCharacter`) of a user.
|
|
|
|
Given we have a `User` object called `my_user` and we want to get the main character:
|
|
|
|
```python
|
|
# Alliance Auth
|
|
from allianceauth.framework.api.user import get_main_character_from_user
|
|
|
|
main_character = get_main_character_from_user(user=my_user)
|
|
```
|
|
|
|
Now, `main_character` is an `EveCharacter` object, or `None` if the user has no main
|
|
character or the user is `None`.
|
|
|
|
### get_main_character_name_from_user
|
|
|
|
This is to get the name of the main character from a user.
|
|
|
|
Given we have a `User` object called `my_user` and we want to get the main character name:
|
|
|
|
```python
|
|
# Alliance Auth
|
|
from allianceauth.framework.api.user import get_main_character_name_from_user
|
|
|
|
main_character = get_main_character_name_from_user(user=my_user)
|
|
```
|
|
|
|
Now, `main_character` is a `string` containing the user's main character name.
|
|
If the user has no main character, the username will be returned. If the user is `None`,
|
|
the sentinel username (see [get_sentinel_user](#get_sentinel_user)) will be returned.
|
|
|
|
### get_sentinel_user
|
|
|
|
This function is useful in models when using `User` model-objects as foreign keys.
|
|
Django needs to know what should happen to those relations when the user is being
|
|
deleted. To keep the data, you can have Django map this to the sentinel user.
|
|
|
|
Import:
|
|
|
|
```python
|
|
# Alliance Auth
|
|
from allianceauth.framework.api.user import get_sentinel_user
|
|
```
|
|
|
|
And later in your model:
|
|
|
|
```python
|
|
creator = models.ForeignKey(
|
|
to=User,
|
|
on_delete=models.SET(get_sentinel_user),
|
|
)
|
|
```
|