TutorielGuides

Thème d'un royaume : une autre apparence pour la connexion et le compte

Sur cette page

Les pages de connexion (/auth/) et l’espace compte (/account/) lisent au chargement un fichier, auth/themes/themes.json. Pour chaque royaume, il peut donner une feuille de style, un logo, un nom et une ligne de copyright. Une seule feuille habille tout le parcours, de la connexion à l’espace compte, et il n’y a rien à recompiler ni à redémarrer.

Ce tutoriel installe l’exemple Université des Sciences, puis montre comment sa feuille est construite pour que vous puissiez l’adapter à votre établissement. L’exemple ne change pas seulement les couleurs : la page de connexion perd sa carte et montre un campus dessiné, et le menu latéral du compte devient une barre d’onglets.

Page de connexion TOSIAM par défaut : carte centrée avec le logo TOSIAM, champs identifiant et mot de passe, bouton Se connecter, fond de caractères Page de connexion TOSIAM par défaut : carte centrée avec le logo TOSIAM, champs identifiant et mot de passe, bouton Se connecter, fond de caractères
Avant : la page de connexion par défaut.

Étape 1 : télécharger l’exemple#

Téléchargez theme-universite.zip (50 Ko). Il contient :

Faites défiler le tableau
FichierRôle
themes.jsonDéclare le thème pour le royaume racine
universite/theme.cssLa feuille de style : palette, jetons TOSIAM, mise en page
universite/logo.svg, universite/logo-dark.svgLe logo, sur fond clair et sur fond sombre
universite/login-art.svg, universite/login-art-dark.svgLe campus dessiné à droite du formulaire de connexion
universite/favicon.svg, universite/favicon-dark.svgL’icône de l’onglet, pour une barre d’onglets claire et sombre
universite/fonts/La police Atkinson Hyperlegible Next et sa licence (SIL Open Font License 1.1)

Tout est local : la page ne charge rien depuis un autre site, pas même la police.

Étape 2 : copier le thème dans TOSIAM#

Les thèmes vivent dans le dossier auth/themes/ de l’application déployée. Avec la QuickStart, c’est apache-tomcat-11.0.14/webapps/tosiam/auth/themes/ :

bash
cd ~/tosiam-quickstart-3.38.0/apache-tomcat-11.0.14/webapps/tosiam/auth/themes
unzip -o ~/Téléchargements/theme-universite.zip

Étape 3 : déclarer le thème#

Voici le themes.json de l’archive :

json· auth/themes/themes.json
{
  "default": {},
  "realms": {
    "/": {
      "stylesheet": "universite/theme.css",
      "logo": { "light": "universite/logo.svg", "dark": "universite/logo-dark.svg", "alt": "Université des Sciences" },
      "name": { "fr": "Espace étudiant", "en": "Student portal" },
      "layout": "card",
      "theme": "auto",
      "copyright": "Copyright © 2026 Université des Sciences. Tous droits réservés.",
      "favicon": { "light": "universite/favicon.svg", "dark": "universite/favicon-dark.svg" }
    }
  }
}

Chaque clé de realms est le chemin d’un royaume. / est le royaume racine ; un royaume sans entrée prend celle de son parent le plus proche, donc / habille aussi tous les royaumes qui n’ont pas la leur. Pour n’habiller qu’un royaume, utilisez son chemin, par exemple "/ref". default donne les valeurs communes à toutes les entrées.

Faites défiler le tableau
RéglageRôle
stylesheetLa feuille chargée après celle de l’application, relative au dossier themes/
logoLe logo à la place de celui de TOSIAM : light, dark (facultatif, pour le thème sombre) et alt, le texte lu par les lecteurs d’écran
nameLe nom de l’espace, par langue : pastille à côté du logo sur la connexion, légende sous le logo dans le compte
layoutconnected (par défaut : la carte reliée à ses nœuds, sur le fond animé) ou card (une carte simple sur --tos-bg, que la feuille peut ensuite remodeler)
themeauto (suit l’appareil), light ou dark. L’utilisateur peut toujours choisir le sien : avec le bouton à côté de la langue sur la connexion, dans son menu dans le compte
copyrightLa ligne du pied de page, en texte
faviconL’icône de l’onglet à la place de celle de TOSIAM : light, et dark (facultatif) pour les barres d’onglets sombres

D’autres réglages ajoutent des textes, un avis, des liens, un contact, ou un thème propre à un arbre : voir Aller plus loin.

Le fichier est relu à chaque chargement de page : il n’y a pas de cache à vider dans TOSIAM. Tomcat peut servir l’ancienne version quelques secondes après une modification.

Étape 4 : voir le résultat#

Ouvrez http://localhost:8080/tosiam/auth/. La connexion est maintenant une page à part entière : le logo et le nom de l’espace dans la barre du haut (1), le formulaire posé sur la page, sans carte, avec un grand titre (2), le bouton principal aux couleurs de l’université (3) et, à droite, le campus. À côté de la langue, le bouton de thème (4) reprend le style du thème sans rien ajouter à la feuille.

Page de connexion Université des Sciences : logo et pastille Espace étudiant en haut, boutons de thème et de langue à droite, titre Connexion à TOSIAM, formulaire sans carte à gauche, campus dessiné à droite Page de connexion Université des Sciences : logo et pastille Espace étudiant en haut, boutons de thème et de langue à droite, titre Connexion à TOSIAM, formulaire sans carte à gauche, campus dessiné à droite 1 2 3 4
Après : le logo et le nom (1), le formulaire posé sans carte, sous son titre (2), le bouton principal (3), le bouton de thème (4).

Connectez-vous : l’espace compte suit le même thème, avec l’en-tête sombre et son logo clair (1), et le menu devenu une barre d’onglets (2).

Espace compte Université des Sciences, page Ressources : en-tête sombre avec le logo, barre d'onglets Profil, Sécurité, Tableau de bord, Ressources, Historique, Demandes, tableau des ressources posé sur la page Espace compte Université des Sciences, page Ressources : en-tête sombre avec le logo, barre d'onglets Profil, Sécurité, Tableau de bord, Ressources, Historique, Demandes, tableau des ressources posé sur la page 1 2
L’espace compte : l’en-tête (1) et la barre d’onglets (2). Sur un téléphone, le menu reste un tiroir.

Pour voir l’autre version, choisissez « Sombre » ou « Clair » avec le bouton de thème (4) : chaque couleur du thème a ses deux valeurs. Le choix est gardé dans le navigateur, le même pour la connexion et l’espace compte ; « Appareil » revient au réglage de l’appareil. Les captures de cette page suivent d’ailleurs le thème du site.

Comment la feuille est construite#

Ouvrez universite/theme.css. Elle se lit en quatre parties.

1. Une portée : :root[data-realm]#

Les deux applications posent le royaume courant sur l’élément racine (data-realm="root" pour le royaume racine, data-realm="ref" pour /ref), et ne chargent la feuille que pour les royaumes qui la déclarent. Toute la feuille est donc imbriquée sous :root[data-realm] : cela suffit à la limiter à ces royaumes, et ce sélecteur l’emporte sur les valeurs par défaut de TOSIAM.

2. La palette, puis les jetons de TOSIAM#

La feuille définit d’abord la palette de l’université (--hz-*), puis y fait pointer les jetons de TOSIAM (--tos-*) que les deux applications utilisent pour tout dessiner :

css· universite/theme.css (extrait)
:root[data-realm] {
  --hz-surface:  light-dark(#FFFFFF, #202734);
  --hz-ink:      light-dark(#202734, #E0F8C7);
  --hz-primary:  light-dark(#36415A, #B7D894);

  --tos-surface: var(--hz-surface);
  --tos-text:    var(--hz-ink);
  --tos-accent:  var(--hz-primary);
  --tos-font-sans: "Atkinson Hyperlegible Next", system-ui, sans-serif;
  --tos-radius-md: 10px;
}

Chaque couleur est une paire light-dark(clair, sombre) : le navigateur choisit selon le choix de l’utilisateur, sinon selon theme dans themes.json, sinon selon le thème de l’appareil. Les jetons les plus utiles :

Faites défiler le tableau
JetonCe qu’il colore
--tos-accent, --tos-accent-hover, --tos-accent-contrastLe bouton principal, son survol, son texte
--tos-id-fill, --tos-id-text, --tos-id-lineLe bouton « Se connecter », la pastille du royaume, l’entrée choisie du menu et les compteurs du compte
--tos-brand, --tos-focusLes liens et l’anneau de focus
--tos-bg, --tos-surface, --tos-surface-raisedLe fond, les cartes, les zones en relief
--tos-text, --tos-text-soft, --tos-text-mutedLe texte, du plus fort au plus discret
--tos-border, --tos-border-strongLes traits, et le contour des champs
--tos-danger, --tos-warning, --tos-info, --tos-success et leurs -softLes états : erreur, avertissement, information, succès
--tos-font-sans, --tos-font-monoLes polices
--tos-radius-*, --tos-control-hLes arrondis et la hauteur des champs et boutons

Changez aussi les couleurs d’état : le rouge par défaut de TOSIAM jure vite avec une autre palette. L’exemple prend un rouge brique, un ocre et un bleu ardoise de la même famille que ses couleurs, chacun avec au moins 4,5:1 de contraste sur la page et sur sa teinte claire. En sombre, le texte posé sur ces couleurs est foncé, pas blanc.

3. La mise en page#

Aucune des deux applications n’enferme ses composants dans un shadow DOM : la feuille atteint chaque élément par sa classe, et peut donc changer la mise en page, pas seulement les couleurs. La page de connexion « sans carte » tient en quelques règles :

css· universite/theme.css (extrait)
:root[data-realm] {
  --hz-login-split: 52%;
  --hz-login-art: url("login-art.svg");

  .tos-cardlogo, .tos-circuit { display: none; }
  .tos-column { position: relative; }
  /* le campus, à droite du formulaire, sous la barre du haut */
  .tos-column::after { content: ""; position: absolute; top: 64px; right: 0; bottom: 0; left: var(--hz-login-split);
    background: var(--hz-login-art) center / cover no-repeat; }
  .tos-main, .tos-footer { margin-right: calc(100% - var(--hz-login-split)); }
  .tos-shell[data-layout] .tos-card { max-width: 400px; padding: 0; background: transparent; box-shadow: none; }
}

La barre d’onglets du compte ne s’applique qu’au-dessus de 860 px (@media (min-width: 861px)) : en dessous, le compte garde son tiroir de menu, pensé pour le téléphone. Gardez cette règle si vous remodelez le compte.

4. Les images et la police#

Une image n’est pas une couleur : light-dark() ne peut pas choisir entre deux fichiers. Le campus passe donc par une variable, changée pour le thème sombre :

css· universite/theme.css (extrait)
:root[data-realm][data-theme="dark"] { --hz-login-art: url("login-art-dark.svg"); }
@media (prefers-color-scheme: dark) {
  :root[data-realm]:not([data-theme="light"]) { --hz-login-art: url("login-art-dark.svg"); }
}

Le logo, lui, a sa version sombre dans themes.json (logo.dark). Les adresses de la feuille (url(...)) sont relatives au dossier de la feuille, et la police est déclarée par un @font-face vers fonts/ : rien ne part vers un autre site.

Adapter l’exemple à votre établissement#

  1. Copiez le dossier universite sous un autre nom et changez le chemin dans themes.json.
  2. Remplacez les logos (SVG de préférence, environ 130 × 40) et le dessin, ou supprimez la règle .tos-column::after pour une page sans image.
  3. Changez la palette --hz-* en haut de la feuille, en gardant deux valeurs par couleur, et vérifiez les contrastes : 4,5:1 pour le texte, 3:1 pour les contours de champs et l’anneau de focus.
  4. Changez name et copyright.
  5. Vérifiez la connexion, une erreur de mot de passe, l’espace compte et un téléphone, en clair et en sombre.

Aller plus loin : textes, avis, liens, contact, thème d’un arbre#

Une entrée de themes.json peut aussi changer des textes de la page et ajouter des informations autour du formulaire. Tout reste du texte : aucun HTML n’est accepté, et rien ne demande de recompiler TOSIAM.

Page de connexion Université des Sciences avec un avis de maintenance au-dessus du titre, un bouton Entrer dans l'Espace étudiant, deux liens sous le bouton et le contact du support dans le pied de page Page de connexion Université des Sciences avec un avis de maintenance au-dessus du titre, un bouton Entrer dans l'Espace étudiant, deux liens sous le bouton et le contact du support dans le pied de page 1 2 3 4
L’avis (1), un texte changé (2), les liens (3) et le contact (4).
json· auth/themes/themes.json, entrée du royaume /
"texts": {
  "fr": { "logIn": "Entrer dans l'Espace étudiant", "forgotPassword": "Code perdu ?" },
  "en": { "logIn": "Enter the student portal", "forgotPassword": "Lost your code?" }
},
"notice": {
  "fr": "Maintenance prévue samedi de 8 h à 10 h : la connexion sera indisponible.",
  "en": "Planned maintenance on Saturday, 8 to 10 am: sign-in will be unavailable."
},
"links": [
  { "label": { "fr": "Première connexion ?", "en": "First time here?" }, "href": "https://www.example.edu/premiere-connexion" },
  { "label": { "fr": "Charte informatique", "en": "IT charter" }, "href": "https://www.example.edu/charte" }
],
"contact": { "email": "support@example.edu", "phone": "+33 1 23 45 67 89", "url": "https://aide.example.edu" },
"trees": {
  "sms": {
    "name": { "fr": "Connexion par SMS", "en": "Sign in by SMS" },
    "notice": { "fr": "Un code vous sera envoyé par SMS.", "en": "A code will be sent to you by SMS." }
  }
}
Faites défiler le tableau
RéglageRôle
textsDes textes à la place de ceux de TOSIAM, par langue puis par clé de traduction. Ils valent pour la connexion et pour le compte
noticeUn avis au-dessus du formulaire, par langue
linksDes liens sous le formulaire : un libellé par langue et une adresse
contactLe support dans le pied de page, sur la connexion et dans le compte : email, phone et url, chacun facultatif
treesUne entrée par arbre (ou chaîne) du royaume, qui complète celle du royaume

Quelques règles :

  • Un texte contenant <, > ou " est ignoré, et la console du navigateur dit lequel. Une clé inconnue est ignorée aussi.
  • Une adresse de links doit commencer par https:, mailto: ou tel: ; une autre est ignorée, javascript: comme http:. L’url de contact doit commencer par https:.
  • L’entrée d’un arbre s’applique quand le lien de connexion le demande, avec service=sms ou authIndexType=service&authIndexValue=sms ; sans ce paramètre, la page prend l’entrée du royaume. Ici, seuls le nom et l’avis changent pour l’arbre sms.

Les clés de texte#

Les clés sont celles des fichiers de traduction de l’interface, src/apps/auth/locales/fr.json pour la connexion et src/apps/account/locales/fr.json pour le compte. Les plus utiles sur la page de connexion :

Faites défiler le tableau
CléTexte par défaut
logInSe connecter (le bouton)
forgotPasswordMot de passe oublié ?
forgotUsernameNom d’utilisateur oublié ?
rememberMeSe souvenir de moi
createAccountCréer un compte (le lien vers l’inscription)

Le titre de l’étape (« Connexion à TOSIAM ») et les libellés des champs (« Nom d’utilisateur », « Mot de passe ») viennent du serveur : ils se règlent dans l’arbre ou le module d’authentification, pas dans texts.

Garder le thème après un redémarrage#

Le dossier auth/themes/ fait partie de l’application déployée. Au démarrage, la QuickStart extrait de nouveau tosiam.war par-dessus webapps/tosiam/ : votre dossier universite/ reste, mais themes.json reprend la version du WAR, qui ne déclare aucun royaume. Recopiez votre themes.json après chaque démarrage, ou ajoutez le thème au WAR lui-même :

bash
mkdir -p build/auth/themes
cp -r universite themes.json build/auth/themes/
cd build && zip -r ../tosiam.war auth/themes

Lancée à côté de votre tosiam.war, la commande y remplace auth/themes/themes.json et ajoute le dossier du thème ; déployez ensuite ce WAR comme d’habitude.

Limites#

  • Le thème ne change ni l’ordre des champs ni les étapes de connexion : ils viennent du graphe d’authentification, comme le titre de l’étape et les libellés des champs. texts ne change que les textes de l’interface.
  • Un thème ne peut pas remplacer le HTML de la page comme les gabarits de l’ancienne interface (XUI) : les textes, l’avis, les liens et le contact sont posés comme du texte.
  • name est le même pour la connexion et le compte.
  • La console d’administration (/console) ne lit pas themes.json.
  • Derrière un CDN placé sur l’adresse de TOSIAM, le thème s’applique de la même façon : themes.json et les dossiers des thèmes ne sont jamais mis en cache. Voir CDN sur le même domaine.

Mis à jour le