140 lines
5.6 KiB
Markdown
140 lines
5.6 KiB
Markdown
# Frontend
|
|
|
|
Ce document sert de référence pour Twig, SCSS et JavaScript côté navigateur. Pour découvrir le projet, commencer plutôt par [ONBOARDING.md](ONBOARDING.md). Pour le travail quotidien, voir aussi [DEVELOPMENT.md](DEVELOPMENT.md).
|
|
|
|
## Vue d'ensemble
|
|
|
|
Le frontend repose sur :
|
|
|
|
- Twig pour le rendu HTML ;
|
|
- Sass pour les styles ;
|
|
- un peu de JavaScript côté navigateur ;
|
|
- Trumbowyg pour l'édition riche côté admin.
|
|
|
|
L'objectif reste simple : pas de couche frontend applicative lourde, mais des scripts dédiés dès qu'un écran dépasse le petit snippet inline.
|
|
|
|
## Où trouver quoi ?
|
|
|
|
- templates de page : `src/<Domaine>/UI/Templates/`
|
|
- partials de domaine : `src/<Domaine>/UI/Templates/partials/`
|
|
- partials partagés : `templates/Kernel/partials/` (avec un fallback interne dans `vendor/netig/netslim-core/src/Kernel/Http/UI/Templates/partials/`)
|
|
- SCSS global : `assets/scss/`
|
|
- scripts frontend dédiés (sources) : `assets/js/`
|
|
- scripts générés servis par l'application : `public/assets/js/`
|
|
|
|
## Lire un template Twig
|
|
|
|
Les constructions les plus courantes sont :
|
|
|
|
- `{% extends %}` : hériter d'un layout ;
|
|
- `{% block %}` : remplir une zone du layout ;
|
|
- `{% include %}` : réutiliser un partial ;
|
|
- `{{ ... }}` : afficher une valeur ;
|
|
- `{% if %}` / `{% for %}` : logique de présentation simple.
|
|
|
|
Principe : garder la logique métier hors de Twig. Un template décide **quoi afficher**, pas **comment fonctionne le métier**.
|
|
|
|
## Organisation SCSS
|
|
|
|
Le dossier `assets/scss/` est organisé en couches :
|
|
|
|
- `core/` : tokens, variables, mixins
|
|
- `base/` : styles HTML globaux
|
|
- `components/` : blocs BEM réutilisables
|
|
- `layout/` : charpente globale de la page
|
|
- `modules/` : styles propres à un domaine ou à un écran
|
|
- `utilities/` : helpers ponctuels de layout (`u-*`)
|
|
|
|
Ordre d'import : `core -> base -> components -> layout -> modules -> utilities`.
|
|
|
|
## Règles de placement
|
|
|
|
- bloc réutilisable sur plusieurs vues : `components/`
|
|
- structure globale de la page : `layout/`
|
|
- style propre à un écran ou à un domaine : `modules/`
|
|
- helper ponctuel de mise en page : `utilities/`
|
|
|
|
En cas d'hésitation entre `components/` et `modules/`, commencer dans `modules/` puis extraire à la deuxième vraie réutilisation.
|
|
|
|
## Convention BEM
|
|
|
|
- bloc : `.card`
|
|
- élément : `.card__title`
|
|
- modificateur : `.card--featured`
|
|
|
|
Règles :
|
|
|
|
- un fichier SCSS reste centré sur un ou plusieurs blocs cohérents ;
|
|
- éviter les sélecteurs descendants hors `base/` et zones de contenu riche ;
|
|
- préférer un modificateur BEM à une nouvelle classe parallèle ;
|
|
- les utilitaires commencent par `u-`.
|
|
|
|
## Contenu riche et Trumbowyg
|
|
|
|
Le contenu HTML issu de l'éditeur est rendu dans `.rich-text` côté public. L'éditeur Trumbowyg est stylé pour rester cohérent avec le reste du projet : même typographie, mêmes états de focus, mêmes espacements généraux.
|
|
|
|
### Workflow média actuel
|
|
|
|
Le workflow média de l'éditeur est désormais le suivant :
|
|
|
|
- l'éditeur ouvre une **modale de médiathèque** ;
|
|
- la modale charge `/admin/media/picker` dans un contexte allégé ;
|
|
- la sélection ou le téléversement d'une image insère un `<img>` avec `data-media-id` ;
|
|
- le backend conserve ensuite ce `data-media-id` à la sanitisation pour synchroniser `post_media`.
|
|
|
|
Le point important est le suivant : l'insertion d'une image ne repose pas sur une simple URL copiée, mais sur un HTML structuré permettant de garder le lien métier avec la médiathèque.
|
|
|
|
## Quand créer un partial Twig ?
|
|
|
|
Créer un partial si :
|
|
|
|
- un fragment est répété dans plusieurs pages ;
|
|
- le template principal devient difficile à lire ;
|
|
- un composant partagé a besoin d'un markup stable (flashs, pagination, badges, empty states, actions admin).
|
|
|
|
## Quand sortir du JavaScript dans un fichier dédié ?
|
|
|
|
Le projet évite une couche JavaScript applicative dédiée tant que le besoin reste limité.
|
|
|
|
Règles :
|
|
|
|
- réserver le JavaScript aux comportements réellement nécessaires ;
|
|
- garder les snippets inline pour les comportements très courts et strictement locaux ;
|
|
- extraire vers `assets/js/` dès qu'un écran devient riche, qu'il faut gérer plusieurs interactions ou qu'un comportement doit rester lisible ;
|
|
- ne charger une librairie tierce dans un template que lorsqu'un écran en a réellement besoin.
|
|
|
|
Exemples actuels sortis des templates :
|
|
|
|
- `assets/js/post-editor-media-picker.js` pour le picker média de l'éditeur ;
|
|
- `assets/js/media-admin.js` pour les actions de la médiathèque (copie, insertion, téléversement AJAX).
|
|
|
|
Après modification de ces fichiers, exécuter `composer frontend:build` pour les recopier dans `public/assets/js/`.
|
|
|
|
## Checklist avant d'ajouter un style ou un comportement
|
|
|
|
Avant d'ajouter du frontend, vérifier :
|
|
|
|
1. est-ce un token ? → `core/`
|
|
2. est-ce un style global HTML ? → `base/`
|
|
3. est-ce un bloc réutilisable ? → `components/`
|
|
4. est-ce structurel à la page ? → `layout/`
|
|
5. est-ce propre à un domaine ? → `modules/`
|
|
6. est-ce un ajustement ponctuel de layout ? → `utilities/`
|
|
7. est-ce un comportement minuscule et local, ou faut-il déjà un fichier JS dédié ?
|
|
|
|
## Vérifications manuelles utiles
|
|
|
|
Après une modification du picker média, de l'éditeur ou de la médiathèque :
|
|
|
|
1. ouvrir l'édition d'un post ;
|
|
2. ouvrir la modale **Médiathèque** ;
|
|
3. sélectionner ou téléverser une image ;
|
|
4. vérifier l'insertion dans l'éditeur ;
|
|
5. enregistrer le post puis vérifier l'usage du média dans `/admin/media`.
|
|
|
|
Après une modification Twig ou SCSS plus générale :
|
|
|
|
1. vérifier le rendu desktop et mobile ;
|
|
2. vérifier les états de focus et les actions principales ;
|
|
3. relire les partials partagés qui utilisent le même composant.
|