Guide interactif pour le backend TYPO3
Auteurs : Marcin Sągol
Traduit par : Léo - W-Seils
Je suis heureux d'être de retour avec un autre rapport sur l'une de nos récentes initiatives. Au cours des dernières semaines, nous nous sommes concentrés sur la création d'un guide/tour interactif pour le backend de TYPO3. Cette idée a été proposée dans les idées du budget de la communauté pour T1/2025 et la communauté l'a sélectionnée pour la mise en œuvre par le biais d'un vote.
Dans cet article, je décrirai nos principaux objectifs, qui a participé à l'initiative et ce que nous avons réalisé à la fin. Alors, prenez quelque chose à boire, installez-vous confortablement et bonne lecture !
Les raisons derrière l'initiative
Avec chaque nouvelle version, TYPO3 évolue et s'aligne de plus en plus sur les standards modernes. Il ajoute de nouvelles fonctionnalités souhaitées par les utilisateurs et introduit des améliorations et des mises à jour de l'interface utilisateur. Dans l'ensemble, TYPO3 continue de se développer, offrant des possibilités de plus en plus puissantes aux développeurs, aux intégrateurs et aux éditeurs. Grâce à sa modularité et son extensibilité, TYPO3 reste un excellent choix pour les petits, moyens et grands projets.
Cependant, l'un des défis auxquels les nouveaux utilisateurs sont souvent confrontés avec TYPO3 est sa courbe d'apprentissage un peu plus élevée par rapport à des produits similaires. Cela s'applique à la fois aux développeurs qui découvrent TYPO3 et aux utilisateurs dont le rôle principal est la gestion de contenu. La communauté TYPO3 a fait des progrès significatifs au cours des dernières années, en fournissant une documentation de meilleure qualité, en standardisant le code, en simplifiant les processus de test et en améliorant l'interface backend avec des solutions éprouvées. Mais nous pensions qu'il y avait de la place pour un ajout supplémentaire - quelque chose pour aider les nouveaux utilisateurs à se familiariser avec TYPO3 encore plus rapidement...
L'idée était de créer un guide interactif pour le backend de TYPO3. Son rôle était de fournir une série de courtes visites guidant les utilisateurs à travers les différentes parties (modules) du backend TYPO3, expliquant leurs fonctionnalités d'une manière claire et simple. Une exigence supplémentaire était de permettre aux développeurs de définir facilement leurs propres visites pour les extensions personnalisées. De telles visites prédéfinies aideraient les nouveaux utilisateurs à se familiariser rapidement avec le backend TYPO3, servant de complément à la documentation traditionnelle. Les visites peuvent également être utilisées pour présenter de nouvelles fonctionnalités au fur et à mesure de leur implémentation dans le projet.
La mise en œuvre - Premières étapes
Lorsque le développement a commencé, il était important d'établir des conventions de nommage claires pour communiquer ce que l'extension offrait et comment identifier ses fonctionnalités individuelles. Le terme central que nous avons choisi est Guide, similaire à un guide humain que vous pourriez engager. Ce guide propose aux utilisateurs différents circuits qu'ils peuvent emprunter. En explorant le code, vous verrez fréquemment des références à ces termes.
La fonctionnalité est actuellement disponible en tant qu'extension TYPO3 autonome afin de faciliter les tests pour les utilisateurs. L'objectif final est d'intégrer cette fonctionnalité dans le noyau TYPO3 - soit en tant que partie d'extensions existantes, soit en tant que nouvelle extension sous le nom du fournisseur TYPO3.
Sélection de la bibliothèque de base pour la gestion des infobulles
Comme TYPO3 est un projet open-source, il était important d'éviter de réinventer la roue et de sélectionner une bibliothèque open-source existante comme base pour le rendu des popups. Nous avons choisi Driver.js parce qu'il est léger, riche en fonctionnalités, extensible et fourni sous la licence MIT. Cependant, il est important de noter que l'intégration de Driver.js a posé plusieurs problèmes en raison de l'utilisation par TYPO3 d'iframes pour le rendu du contenu des modules. Ici, Mateusz Gdula de Macopedia a apporté une contribution significative. Il a créé des solutions pour sélectionner correctement les éléments cibles dans les iframes, positionner les popups en fonction de la configuration de l'étape et a pris en charge la quasi-totalité de l'intégration frontale. Excellent travail, Mateusz, et merci !
Configuration des circuits et des étapes
Ensuite, nous avions besoin d'un moyen de configurer les visites et leurs étapes. Pour ce faire, nous avons défini la configuration à l'aide des fichiers YAML, qui sont stockés dans les extensions du dossier Configuration/Tours. Grâce à cette approche, une seule extension peut proposer plusieurs visites. En outre, nous avons introduit l'option permettant de marquer chaque visite comme étant autonome ou liée à un module. Les visites autonomes sont déclenchées automatiquement dans le backend (si l'utilisateur y a accès), tandis que les visites liées à un module n'apparaissent que lorsque les utilisateurs naviguent vers le module backend concerné. Les visites liées à un module seront probablement utilisées plus fréquemment. Ce concept est expliqué plus en détail dans la documentation.
Chaque visite peut comporter plusieurs étapes. Chaque étape est présentée sous la forme d'une fenêtre contextuelle flottante placée à côté d'un élément spécifique. Les étapes ont un titre, un contenu, un élément cible défini auquel elles sont associées et des événements JavaScript facultatifs. Ces événements peuvent être déclenchés lorsque la fenêtre contextuelle apparaît ou disparaît. En outre, il est possible de définir un ensemble spécial d'événements que les utilisateurs doivent exécuter avant de pouvoir passer à l'étape suivante. Au niveau de la configuration de la visite, il est également possible de spécifier la visite suivante (à l'aide de son identifiant) qui doit démarrer automatiquement à la fin de la visite en cours. Cela permet de créer une séquence ou une chaîne de tournées. Pour plus de détails sur la configuration des tournées et des étapes, voir la documentation.
Mise en œuvre du module backend
Il était également important de fournir aux utilisateurs un moyen d'afficher la liste des visites disponibles, de suivre leur progression et de déclencher manuellement les visites sélectionnées. Pour ce faire, nous avons introduit un nouveau module backend appelé Guide, situé dans le groupe de modules Aide. Le module Guide permet aux utilisateurs de
- Voir une liste des visites disponibles pour l'utilisateur actuel du backend.
- Commencer, poursuivre ou redémarrer une visite sélectionnée.
- Suivre leur progression dans chaque visite.
- Marquer une visite sélectionnée comme terminée.
- Désactiver le démarrage automatique des visites (à l'aide d'un simple interrupteur), tout en permettant aux utilisateurs de les lancer manuellement.
Aperçu de la configuration des visites
Pour permettre aux administrateurs de voir toutes les visites configurées dans TYPO3, nous avons décidé d'étendre le module de configuration en ajoutant une nouvelle entrée appelée Backend Guide Tours. Cette fonctionnalité permet aux administrateurs d'inspecter la configuration de chaque visite, de revoir les étapes définies, de vérifier les permissions attribuées et plus encore. Voici à quoi cela ressemble :
Amélioration de l'expérience utilisateur - Consultation avec l'équipe UX de TYPO3
Lorsque l'extension a atteint un état stable, nous avons approché l'équipe TYPO3 UX pour présenter ses fonctionnalités et recueillir des commentaires. Mateusz et moi avons rencontré Rachel Foucard et Riccardo De Contardi et notre réunion s'est avérée très utile.
Voici un résumé de leurs principales suggestions :
- Ajouter un bouton « Passer » dans la fenêtre contextuelle pour permettre aux utilisateurs de sauter facilement la visite sans avoir à passer par toutes les étapes.
- Distinguer visuellement le bouton « Suivant », qui représente l'action principale.
- Veiller à ce que le contenu de chaque étape soit clair, concis et facilement compréhensible.
- S'assurer que les titres et le contenu des étapes sont traduisibles
- Contactez rapidement l'équipe de traduction de TYPO3 pour inclure l'extension sur Crowdin, permettant des traductions réalisées par la communauté.
- Éviter d'utiliser un bouton flottant pour l'accès rapide à la liste des visites, car cela ajouterait une complexité et un encombrement inutiles à l'interface.
- Ajouter un bouton clairement visible dans la liste des visites pour activer ou désactiver facilement les visites (le bouton actuel dans le formulaire de configuration de l'utilisateur n'est pas facile à découvrir).
- Veiller à ce que le bouton Recommencer dans la liste des visites réinitialise le statut de la visite, en la marquant comme incomplète pour les utilisateurs.
- Fournir une option dans la liste des visites pour marquer manuellement les visites comme terminées
- Permettre de définir des autorisations pour les visites, car certaines étapes n'ont de sens que si les utilisateurs ont l'accès approprié (par exemple, des modules, des widgets ou des tables de base de données spécifiques).
- Créer un simple widget de tableau de bord pour afficher la progression des visites des utilisateurs et fournir un lien rapide vers le module Guide, où la liste complète des visites est affichée.
Encore une fois, merci beaucoup pour votre temps précieux et vos commentaires, Rachel et Riccardo !
Touches finales, polissage et création de la documentation
Après avoir reçu les commentaires de l'équipe TYPO3 UX, nous avons commencé à mettre en œuvre des améliorations. Nous avons fait des ajustements visuels aux popups, y compris l'ajout d'un bouton « Skip » pour permettre aux utilisateurs de quitter la visite rapidement. Nous avons également créé un widget simple pour le tableau de bord qui affiche la progression de la visite de l'utilisateur, montrant le nombre de visites qu'il a complétées parmi celles qui sont disponibles. Ce widget comprend un bouton qui renvoie directement au module Guide, améliorant ainsi sa visibilité. Le module Guide lui-même se trouve dans le groupe Aide, accessible par l'icône en forme de point d'interrogation dans la barre supérieure.
Comme convenu avec l'équipe UX de TYPO3, les utilisateurs ne verront pas les visites auxquelles ils n'ont pas accès. Par exemple, si une visite est liée à un module pour lequel l'utilisateur n'a pas de permission, cette visite ne sera pas affichée. De même, si une visite nécessite des autorisations supplémentaires et que l'utilisateur ne les possède pas, la visite restera cachée.
Pendant le développement, et surtout après la mise en œuvre de toutes les fonctionnalités clés, il était important de bien documenter les fonctionnalités de l'extension, de décrire toutes les options de configuration disponibles pour les visites guidées et les étapes et d'expliquer clairement les sujets connexes. Nous espérons que vous aimerez ce que nous avons créé et que la documentation vous aidera à créer facilement vos propres visites guidées !
Problèmes connus
L'un des principaux problèmes à résoudre est de s'assurer que chaque étape est pertinente et qu'elle a un sens pour l'utilisateur. En raison de la grande personnalisation de TYPO3 et de la gestion avancée des autorisations, il est difficile de déterminer avec précision si un utilisateur aura accès à et verra réellement, l'élément cible associé à une étape spécifique de la visite.
Par exemple, un nouvel utilisateur sans aucune autorisation ne voit guère plus que la barre supérieure de l'interface du backend. Cela limite considérablement les visites qui ont un sens pour un tel utilisateur - en particulier si une visite cible des éléments tels que les entrées du menu principal, l'arborescence de la page ou des composants spécifiques du module.
Ce sujet devrait être discuté avec les développeurs de TYPO3 Core. Il convient de décider s'il faut introduire une logique de validation personnalisée pour les visites ou les étapes individuelles - par exemple, vérifier si un utilisateur a accès à au moins un module de backend ou s'il peut voir toutes les pages de l'arborescence.
Il existe également de nombreux endroits où le fait de disposer d'un identifiant dédié pour un élément simplifierait grandement les sélecteurs et permettrait de distinguer clairement certains types d'éléments. Par exemple, dans l'arborescence des pages, il serait utile que les pages standard ou les dossiers aient des identifiants spécifiques pour simplifier la sélection.
Merci à la communauté TYPO3
J'aimerais remercier chaleureusement la communauté TYPO3 d'avoir sélectionné notre initiative dans le cadre des idées budgétaires de la communauté pour le premier trimestre 2025, ainsi que tous ceux qui ont participé à ce projet jusqu'à présent - votre aide et vos commentaires ont été inestimables !
Tester, explorer, contribuer
Cet article décrit les sujets généraux liés à notre initiative sans approfondir la mise en œuvre ni décrire chaque option de configuration séparément.
Pour ceux qui sont intéressés par le code et les possibilités offertes par l'extension, veuillez consulter le dépôt sur GitHub et la documentation.
Regardez la vidéo de deux minutes qui présente l'extension : TYPO3 Interactive Tour Showcase
Tous les utilisateurs sont invités à tester cette extension, à définir leurs propres visites, à nous faire part de leurs commentaires et à nous aider à l'améliorer pour la rendre plus mature, plus riche en fonctionnalités et plus stable. Si vous rencontrez des problèmes ou avez de nouvelles idées, veuillez les soumettre sur GitHub.