Loaders, skeleton screens, overlays et indicateurs HTMX pour Django.
Project description
xeolux-loadingkit
Package Django léger pour ajouter des loaders, skeleton screens, overlays et indicateurs HTMX dans n'importe quel projet.
Fait partie de la suite Xeolux — packages Django minimalistes et réutilisables.
Fonctionnalités
| Template tag | Description |
|---|---|
{% xeolux_loadingkit_css %} |
Injecte la feuille CSS du package |
{% xeolux_loader %} |
Spinner animé (sm / md / lg) avec texte optionnel |
{% xeolux_overlay %} |
Overlay plein écran avec backdrop blur |
{% xeolux_skeleton %} |
Skeleton shimmer (text / card / avatar / table / form) |
{% xeolux_htmx_indicator %} |
Indicateur compatible HTMX |
Installation
pip install xeolux-loadingkit
Ajout dans INSTALLED_APPS
# settings.py
INSTALLED_APPS = [
...
"xeolux_loadingkit",
]
django.contrib.staticfilesdoit également être présent (il l'est par défaut).
Utilisation
1. Injecter le CSS
Placez ce tag dans le <head> de votre template de base, après avoir chargé la bibliothèque :
{% load xeolux_loadingkit %}
<head>
{% xeolux_loadingkit_css %}
</head>
2. Loader (spinner)
{# Taille par défaut (md) #}
{% xeolux_loader %}
{# Avec taille et texte #}
{% xeolux_loader size="sm" %}
{% xeolux_loader size="md" text="Chargement..." %}
{% xeolux_loader size="lg" text="Veuillez patienter" %}
Paramètres :
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
size |
str |
"md" |
"sm", "md" ou "lg" |
text |
str|None |
None |
Texte affiché à côté du spinner |
3. Overlay
{# Overlay inactif (caché) #}
{% xeolux_overlay %}
{# Overlay actif (visible) #}
{% xeolux_overlay text="Traitement en cours..." active=True %}
Pour l'activer dynamiquement via JavaScript :
document.querySelector('.xlk-overlay').classList.add('xlk-overlay--active');
Paramètres :
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
text |
str |
"Chargement en cours..." |
Texte de l'overlay |
active |
bool |
False |
Si True, l'overlay est visible au chargement |
4. Skeleton
{# Texte (défaut) #}
{% xeolux_skeleton %}
{% xeolux_skeleton type="text" lines=4 %}
{# Card #}
{% xeolux_skeleton type="card" %}
{# Avatar #}
{% xeolux_skeleton type="avatar" %}
{# Tableau #}
{% xeolux_skeleton type="table" lines=4 rows=5 %}
{# Formulaire #}
{% xeolux_skeleton type="form" lines=3 %}
Paramètres :
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
type |
str |
"text" |
"text", "card", "avatar", "table", "form" |
lines |
int |
3 |
Nombre de lignes (text / form) ou colonnes (table) |
rows |
int |
4 |
Nombre de lignes pour le type "table" |
5. Indicateur HTMX
{% xeolux_htmx_indicator text="Chargement..." %}
L'indicateur est masqué par défaut et devient visible pendant une requête HTMX grâce à la classe .htmx-indicator standard.
Exemple complet avec HTMX
<button
hx-post="/save/"
hx-target="#result"
hx-indicator="#xeolux-htmx-loader">
Enregistrer
</button>
{% xeolux_htmx_indicator text="Enregistrement..." %}
Paramètres :
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
text |
str |
"Chargement..." |
Texte affiché pendant la requête |
Personnalisation CSS
Toutes les valeurs visuelles sont contrôlées par des variables CSS. Surchargez-les dans votre propre feuille de style :
:root {
--xlk-primary: #3b6cf7; /* Couleur principale (spinner, accents) */
--xlk-bg: #ffffff; /* Fond de l'overlay intérieur */
--xlk-muted: #e2e6f0; /* Fond des skeletons et du spinner */
--xlk-text: #374151; /* Couleur du texte */
--xlk-overlay-bg: rgba(15, 20, 40, 0.55); /* Fond de l'overlay plein écran */
--xlk-radius: 0.5rem; /* Border-radius global */
--xlk-speed: 0.7s; /* Vitesse des animations */
}
Tester dans un projet Django
- Installez le package en mode éditable depuis la racine du repo :
pip install -e /chemin/vers/xeolux-loadingkit
-
Ajoutez
"xeolux_loadingkit"dansINSTALLED_APPS. -
Dans n'importe quel template :
{% load xeolux_loadingkit %}
{% xeolux_loadingkit_css %}
{% xeolux_loader size="md" text="Chargement..." %}
- Lancez
python manage.py collectstaticsi vous êtes en production.
Lancer les tests
# Depuis la racine du repo
pip install django pytest pytest-django
python -m pytest tests/ -v
Build & Publication PyPI
Build local
pip install build twine
python -m build
Les fichiers .tar.gz et .whl seront générés dans dist/.
Vérifier le package
twine check dist/*
Publier sur TestPyPI (recommandé avant la vraie publication)
twine upload --repository testpypi dist/*
Tester l'installation depuis TestPyPI :
pip install --index-url https://test.pypi.org/simple/ xeolux-loadingkit
Publier sur PyPI
twine upload dist/*
Vous aurez besoin d'un compte PyPI et d'un token API.
Configurez~/.pypircou utilisez la variable d'environnementTWINE_PASSWORD.
Structure du projet
xeolux-loadingkit/
├── xeolux_loadingkit/
│ ├── __init__.py
│ ├── apps.py
│ ├── templatetags/
│ │ ├── __init__.py
│ │ └── xeolux_loadingkit.py
│ ├── templates/
│ │ └── xeolux_loadingkit/
│ │ ├── loader.html
│ │ ├── overlay.html
│ │ ├── skeleton.html
│ │ └── htmx_indicator.html
│ └── static/
│ └── xeolux_loadingkit/
│ └── css/
│ └── loadingkit.css
├── tests/
│ └── test_template_tags.py
├── README.md
├── pyproject.toml
├── LICENSE
└── MANIFEST.in
Compatibilité
| Django | Python |
|---|---|
| 4.2 | 3.10, 3.11, 3.12 |
| 5.0 | 3.10, 3.11, 3.12 |
| 5.1 | 3.10, 3.11, 3.12 |
Licence
MIT © Xeolux
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file xeolux_loadingkit-0.1.0.tar.gz.
File metadata
- Download URL: xeolux_loadingkit-0.1.0.tar.gz
- Upload date:
- Size: 12.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.14.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
74e7599b02b5c58912eedb50c82b9b61a0fdf26519585398b39912815eef18f3
|
|
| MD5 |
dc263af77b22a6b4a6126926d1340709
|
|
| BLAKE2b-256 |
6702897b79db379472d6d25ec506f3b2ccd6f2880d6ff4b50d88d8d8c41fc111
|
File details
Details for the file xeolux_loadingkit-0.1.0-py3-none-any.whl.
File metadata
- Download URL: xeolux_loadingkit-0.1.0-py3-none-any.whl
- Upload date:
- Size: 10.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.14.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7aaaace223c40c1641dcd1364e11cd6dfd5c6c308eba5b0be2c78af815cdb9c7
|
|
| MD5 |
62cd498eaa9d0945a1b6b2aaaf0d4c1b
|
|
| BLAKE2b-256 |
18d48313082e21781ba82910cfa0186faf899717033f307026e71629b919672c
|
