Ajout doc dev sélection groupes

This commit is contained in:
Emmanuel Viennet 2024-09-05 11:03:08 +02:00
parent 75eacf1e73
commit a698c80f7b
2 changed files with 67 additions and 10 deletions

View File

@ -1,7 +1,7 @@
# Conventions de codage pour ScoDoc
Le projet étant très ancien, le code est passé par différentes conventions et
frameworks. Le style de python et celui du *frontend* web ont considérablement
frameworks. Le style de python et celui du _frontend_ web ont considérablement
évolués ces dernières décennies.
Pour les nouveaux codes, respecter les principes suivants:
@ -22,7 +22,7 @@ Pour les nouveaux codes, respecter les principes suivants:
- l'usage de **[black](https://black.readthedocs.io/en/stable/)** est obligatoire
- l'usage de pylint et mypy est fortement recommandé
- Pour le code JS, indentation avec 2 espaces (sous VS Code, utiliser *Prettier*).
- Pour le code JS, indentation avec 2 espaces (sous VS Code, utiliser _Prettier_).
### Conventions standard Python
@ -44,7 +44,7 @@ def _upload_justificatif_files(
## Pages et templates
Les vues utilisent un template *Jinja2*, fichier avec extension j2.
Les vues utilisent un template _Jinja2_, fichier avec extension j2.
On s'astreint, sauf cas particulier, à un nommage identique de la route, la vue et du template.
@ -76,7 +76,7 @@ Les templates suivants sont les plus utilisés pour les pages:
- `sco_page.j2` page standard dans un formsemestre: avec sidebar et barre de
menu du semestre. Le contenu de la variable `content` est placé comme HTML
brut (*safe*) dans la partie contenu. Passer `sco=ScoData(formsemestre=formsemestre)`
brut (_safe_) dans la partie contenu. Passer `sco=ScoData(formsemestre=formsemestre)`
en argument au template.
- `sco_page_dept.j2` page dans un département (avec sidebar) mais sans formsemestre (pas de
@ -120,6 +120,7 @@ html_sco_header.sco_footer()
```
La migration la plus simple consiste à utilise `sco_page.j2`:
```py
render_template(
"sco_page.j2",
@ -163,7 +164,6 @@ Mais si on souhaite générer le contenu dans un template, cela prendra la forme
{% endblock %}
```
### Classes css
`scodoc.css` (et à partir de 9.7, `scodoc97.css`) définissent quelques classes à usage général:
@ -179,12 +179,12 @@ Mais si on souhaite générer le contenu dans un template, cela prendra la forme
## Accès à la base de donnée
Sauf exception (requêtes exotiques, problèmes de performance) à discuter, les
accès à la base se font à travers l'ORM *SQLAlchemy*. Les modèles sont définis
accès à la base se font à travers l'ORM _SQLAlchemy_. Les modèles sont définis
dans `app/models`, sauf les comptes utilisateurs qui sont dans
`/app/auth/models.py`.
Au moment de la définition de nouveaux modèles, éviter si possible les champs
*nullables*, penser à créer là où ce sera utile des index.
_nullables_, penser à créer là où ce sera utile des index.
## Tableaux
@ -192,19 +192,76 @@ ScoDoc génère beaucoup de tableaux, sauf exception destinés à l'affichage We
On utilise la super-classe `Table` de `app/tables/table_builder.py`.
Le rendu HTML utilise *DataTables*.
Le rendu HTML utilise _DataTables_.
## Dates et heures
ScoDoc, contrairement à de nombreuses applications, est centré sur les
*étudiants* et les enseignements, qui sont censés opérer dans le fuseau horaire
_étudiants_ et les enseignements, qui sont censés opérer dans le fuseau horaire
du serveur. Cela signifie que, quelle que soit l'emplacement de l'utilisateur,
les heures affichées et saisies par ScoDoc seront données dans le fuseau horaire
du serveur.
L'API publie et reçoit des heures au format ISO avec fuseau horaire (*timezone*) et n'est pas
L'API publie et reçoit des heures au format ISO avec fuseau horaire (_timezone_) et n'est pas
concernée par cette remarque.
## Sélection de groupes
De nombreuses pages ont besoin d'offrir un moyen de sélectionner un ou plusieurs
groupes d'étudiants, comme dans cet exemple:
![menu multiselect des groupes](screens/multiselect_groups.png)
La vue doit récupérer la liste des groupes sélectionnés ainsi:
```py
group_ids = request.args.getlist("group_ids")
```
ou s'il s'agit un `POST`:
```py
group_ids = request.form.getlist("group_ids")
```
On converti ensuite les arguments en entiers:
```py
try:
group_ids = [int(gid) for gid in group_ids]
except ValueError as exc:
raise ScoValueError("group_ids invalide") from exc
```
et on peut utiliser le code ancien `sco_groups_view`:
```py
groups_infos = sco_groups_view.DisplayedGroupsInfos(
group_ids,
formsemestre_id=formsemestre.id,
select_all_when_unspecified=True,
)
```
`groups_infos` est un objet qui permet de récupérer les informations et de générer le menu.
Par exemple:
```py
Choix des groupes :
{sco_groups_view.menu_groups_choice(groups_infos, submit_on_change=True)
if groups_infos else ''}
```
La fonction `form_groups_choice` génère un formulaire complet.
Autres attributs/méthodes utiles de `groups_infos`:
- `get_etudids():list[int]` : les ids des étudiants des groupes sélectionnés;
- `groups_titles:str` : titres des groupes;
- `groups_filename:str`: un (morceau de) nom de fichier pour ces groupes.
!!! note "Voir aussi"

Binary file not shown.

After

Width:  |  Height:  |  Size: 39 KiB