Débuter avec Quasar Framework (2/2)
Prérequis
Si ce n’est pas déjà fait, commencez par lire la première partie de cette article : elle aborde l’historique du projet Quasar, sa promesse et l’initialisation d’un nouveau projet avec la CLI.
Entrons à présent dans le détail, en abordant les différents aspects du framework qui vont vous permettre de développer votre application sereinement et rapidement.
Note : Medium ne proposant pas de colorisation de code, j’ai pris des captures d’écran des exemples de codes avec le plugin Polacode de Visual Studio Code et créé un dépôt Github avec une branche par exemple de code. Vous retrouverez sous chaque exemple, le lien vers le code source sur Github.
Le fichier de configuration unique : quasar.conf.js
Avant de s’intéresser aux styles et composants, il est important de regarder le fichier de configuration quasar.conf.js qui va déterminer toutes les dépendances de votre application.
Il contient les sections pour configurer :
- Les modules à charger au boot (noeud “boot”)
- Le pré-processeur CSS (noeud “css”)
- Les bibliothèques d’icônes (noeud “extras”)
- La stratégie d’import des composants et la liste des plugins de Quasar (noeud “framework”)
- Les variables d’environnements (noeud “build”)
- Les plugins Webpack (noeud “build”, fonction “extendWebpack”)
- La configuration par type d’application (noeud “pwa”, etc…)
Ce fichier va vous permettre de configurer l’application Quasar, et également de l’étendre si vous avez besoin de mettre en place un module tiers, un plugin Webpack, etc…
L’arborescence des sources
Pour démarrer, voici ce qu’il faut repérer au niveau des sources du projet :
- src/router/routes.js : il s’agit du routeur de votre application qui va faire correspondre une route (url) à un layout et une page.
- src/pages : ce répertoire contient les pages de votre application.
- src/components : ce répertoire contient les composants Vue de votre application. Ce sont les composants que vous allez utiliser dans vos pages.
- src/layouts/MainLayout.vue : ce fichier correspond à la mise en page principale de votre application. Vous pouvez créer d’autres layouts dans ce répertoire et utiliser le routeur pour spécifier quel est le layout utilisé pour chaque page.
- src/css/app.sass : ce fichier est la feuille de style globale de l’application.
Par défaut, Quasar ne propose pas de répertoire “services” ou “helpers” pour ranger le code métier, c’est à vous de le créer. En ce qui me concerne, j’ai ajouté pour cela un répertoire “services” dans le répertoire “src”.
La bibliothèque de composants
Une bibliothèque très complète
Quasar propose en standard un peu plus de 70 composants : avatar, boutons, badges, fil de discussion, color picker, infinite scroll, tableaux, parallax, etc..
Chaque composant est un composant Vue : il présente des propriétés (props) pour le paramétrer et des événements pour le faire réagir.
Ils sont reconnaissables facilement dans le code : ils commencent toujours par la lettre “q” de Quasar.
Lorsque vous incluez le composant dans votre page, la balise du composant commence par “q-” et s’écrit en kebab case.
Exemple du composant Button
Prenons l’exemple d’un composant simple : le composant q-btn qui permet d’afficher un bouton.
Il s’inclut comme ceci dans un composant parent :
Vous obtiendrez le second bouton visible dans les boutons standards de la documentation :
Pour voir le code permettant d’obtenir tous les boutons visibles sur cette image, cliquez sur l’icône “< >” en haut à droite du cadre.
Cette icône est disponible pour chaque exemple de chaque composant et vous donne accès aux onglets TEMPLATE et SCRIPT (si besoin) afin de copier / coller le code html et javascript nécessaire pour reproduire l’exemple sur votre projet.
Sur la page du composant, vous retrouverez également les exemples de personnalisation : avec ou sans icône, différentes tailles, etc…
En bas de chaque page de composant, vous trouverez une section “API” précisant toutes les props, événements et méthodes permettant de configurer le composant.
Focus sur certains composants
Après vous avoir montré comment mettre en place un composant et connaître son API avec un composant basique qui est le bouton, j’ai choisi de vous présenter :
- Un composant classique : le tableau.
- Un composant qui bénéficie de la réactivité de Vue : le carrousel.
- Un composant qui met en valeur l’aspect multiplateforme intégré de Quasar : l’uploader.
- La combinaisons de deux composants : infinite scroll et pull to refresh.
Le composant table
Ce composant est un classique pour afficher un tableau de données.
Pour l’utiliser dans votre application Quasar, ajoutez le code suivant dans la partie <template> du composant parent :
Puis, tout se joue dans la partie <script> où vous devez déclarer les colonnes (columns) et les données (data) sous forme de tableaux d’objets.
Exemple d’un tableau comportant deux colonnes :
Vous obtiendrez ceci :
Quasar se charge d’ajouter par défaut la pagination et de mettre en place les curseurs permettant de trier sur les colonnes qui ont la propriété sortable à true.
Pour la colonne “Poids du fichier”, la propriété format permet de mettre en forme la valeur définie dans la propriété field.
La fonction humanStorageSize, fournie par Quasar, permet de représenter une valeur en KB, MB ou GB.
Notez que le tri fonctionne correctement sur cette colonne car il s’effectue sur la valeur de la propriété field.
Vous retrouverez tous les paramètres de personnalisation du composant table sur cette page : https://quasar.dev/vue-components/table.
Tout est configurable : la pagination, les colonnes invisibles, l’entête, les états de chargement, les body slots, l’export CSV, la navigation au clavier et les popups d’édition de champs.
Le composant carousel
Pour afficher des informations et notamment des images, le composant carousel est un très bon choix.
Voyons comment l’utiliser pour afficher rapidement une petite galerie d’images avec un bouton pour les voir en plein écran et des vignettes pour la navigation.
Dans la section <script> de votre composant, ajoutez :
Enfin, dans la section <template>, ajoutez :
Voici ce que vous obtiendrez :
Comme vous pouvez le constater, l’essentiel du code est dans la partie template. On notera :
- swipeable : permet de définir que le carrousel peut être manipulé par un geste de la souris ou du doigt sur mobile.
- animated : permet de déclencher une animation en cas de changement d’image. Par défaut l’animation est fade, elle peut être remplacée par un slide-right ou slide-down.
- thumbnails : permet d’afficher les vignettes. Au clic sur une vignette, le carrousel s’anime jusqu’au slide correspondant.
- infinite : permet de revenir à la première image lorsque l’on clique sur “suivant” sur la dernière image, et inversement.
- Les balises q-carousel-slide permettent de définir les différents slides à afficher. Si vous récupérez dynamiquement le contenu du carrousel, vous pouvez utiliser la directive v-for pour boucler sur les données à afficher.
- Le template v-slot:control permet de définir le bouton permettant de passer en plein écran. Au clic sur le bouton, la propriété fullscreen change de valeur. Dans les attributs du carrousel, fullscreen.sync est une propriété réactive qui est liée à la valeur de la propriété fullscreen. Le carrousel passe donc automatiquement en plein écran dès que fullscreen passe à true.
- Pour les besoins du test, la propriété style est présente pour définir la largeur du carrousel. Elle a été rendue réactive grâce aux “:” présents en préfixe. Elle réagit à la valeur de la propriété fullscreen de façon à régler différemment la largeur du carrousel s’il est en plein écran ou non. La même technique peut être utilisée, par exemple, pour afficher deux résolutions d’images différentes en fonction de l’affichage : vignette ou plein écran.
Vous retrouverez toutes les options de personnalisation du composant carrousel sur la page du composant : https://quasar.dev/vue-components/carousel
Le composant uploader
Dans le cadre d’une application de souvenirs que je suis en train de développer, j’avais besoin d’implémenter un formulaire avec un drag’n drop de médias (photos et vidéos). Mon application étant à destination du web et du mobile, mon premier réflexe a été d’identifier des outils permettant de répondre à ce besoin :
- Dropzone.js pour la gestion du drag’n drop et de l’upload multiple pour la version web.
- Un plugin Cordova pour récupérer un média de la galerie du téléphone et implémenter une barre de chargement pour le suivi de l’upload.
Après avoir implémenté Dropzone.js dans mon application Quasar via le composant vue-dropzone et la possibilité d’ajouter des librairies externes, j’ai eu besoin de trouver une meilleure façon de représenter l’upload des fichiers car celle de Dropzone.js ne me convenait pas.
Et c’est là que j’ai découvert le composant uploader en parcourant la liste des composants Quasar.
Ce composant fournit exactement les fonctionnalités que je recherchais : drag’n drop de fichiers, suivi des uploads et surtout la sélection des fichiers sur le disque dur si on l’utilise via un navigateur et la sélection dans la galerie du téléphone si on l’utilise sur mobile.
Nul besoin d’implémenter une librairie externe ni de gérer la spécificité mobile iOS / Android. Le composant s’adapte automatiquement à son contexte d’exécution et propose une expérience utilisateur simple et performante.
Et bien évidemment, votre projet contient de fait moins de dépendances et de code grâce à cela.
Pour utiliser QUploader dans votre application, ajoutez dans la section <template> :
Dans sa version basique, vous n’avez pas besoin de spécifier quoi que ce soit dans la section <script> de votre composant. En ce qui me concerne, j’envoie les médias sélectionnés sur la Google Cloud Platform, j’avais donc besoin de générer une url signée dédiée à chaque transfert de fichier. C’est ce que j’ai fait en utilisant la propriété factory de q-uploader, qui appelle ici la méthode getSignedUrl de mon composant à chaque transfert de fichier, pour récupérer l’url cible.
Parmi les autres attributs utilisés ci-dessus :
- method : permet de spécifier le verbe de la requête qui envoie chaque fichier (par défaut c’est post).
- multiple : permet de spécifier que l’on souhaite transférer plusieurs fichiers.
- send-raw : envoie le contenu brut des fichiers, sans entêtes.
- accept : permet de filtrer les types de fichiers au moment de la sélection sur l’appareil.
- flat et bordered : permettent d’ajuster le style du composant.
L’action de glisser / déposer des fichiers sur le composant est activée par défaut.
Voici le rendu du composant :
Il inclut l’affichage du poids de chaque fichier, un bouton d’ajout de nouveaux médias, un bouton d’upload et un bouton pour supprimer un fichier.
En terme de design, il peut être retravaillé pour afficher les médias sous forme de grille en utilisant un composant q-card.
Vous retrouverez toutes les options de personnalisation de q-uploader sur la page du composant : https://quasar.dev/vue-components/uploader
Combiner les composants infinite scroll et pull to refresh
Voici les deux derniers composants que je souhaitais vous présenter : Infinite Scroll et Pull to refresh.
Le premier permet, lors de l’affichage d’une liste, de gérer l’apparition des éléments suivants lorsque l’on arrive en bas de la liste.
Le second, de rafraîchir la liste lorsque l’on effectue une action de scroll depuis le haut de l’écran, comme si on souhaitait remonter en haut de la liste.
De nos jours, ces deux comportements sont des standards que l’on retrouve dans quasiment toutes les applications.
Leur implémentation avec Quasar est très simple.
Dans la section <template>, ajoutez :
Ce code définit un infinite scroll avec une icône de chargement (composant q-spinner-dots) qui s’affiche le temps de charger les éléments suivants.
Et au sein de l’infinite scroll, il ajoute la fonctionnalité de “tirer pour rafraîchir” sur la liste des blocs grâce au composant q-pull-to-refresh.
Pour remplir la liste et rendre tout cela dynamique, ajoutez dans la section <script> :
La liste des blocs comporte 50 blocs par page et à chaque déclenchement de l’infinite scroll, 50 nouveaux éléments sont ajoutés dans la liste.
L’utilisation de setTimeout permet de simuler un temps d’attente de manière à voir apparaître l’icône de chargement.
L’appel à la fonction “done()” fournie par Quasar permet de déclencher la disparition de l’indicateur de chargement (composant q-spinner-dots) et l’affichage des 50 nouveaux blocs. L’utilisation de cette fonction est la bonne pratique en cas de traitement asynchrone afin de déclencher la fin du traitement après chargement des nouvelles données.
Voici ce que vous allez obtenir à partir de ce code :
Vous retrouverez toutes les options de personnalisation de ces 2 composants sur leurs pages respectives :
- Infinite scroll : https://quasar.dev/vue-components/infinite-scroll
- Pull to refesh : https://quasar.dev/vue-components/pull-to-refresh
Le layout et les styles
Maintenant que nous avons vu comment initialiser un projet et y ajouter des composants, nous allons voir comment utiliser les layouts et les styles proposés par Quasar pour pouvoir maîtriser la mise en page de votre application.
Vue d’ensemble
Quasar utilise Flexbox et un ensemble de classes CSS pour sa gestion du layout.
La documentation est très complète : https://quasar.dev/layout/
Vous y retrouverez toutes les explications dont vous avez besoin ainsi qu’un layout builder pour vous aider à configurer la mise en page de votre application.
Vous y trouverez également une layout gallery proposant des mises en page pré-configurées, dont :
Cela peut être un excellent point de départ et un gain de temps significatif pour débuter.
Enfin, Quasar propose un ensemble de classes CSS permettant de modifier les styles :
Pour en savoir plus, visitez la section Style & Identity de la documentation.
Typographie et couleurs
Quasar applique automatiquement un style sur les balises titre h1 à h6 et propose ces styles pour une utilisation sur les autres balises, sous la forme “text-hX”.
Par exemple, les deux lignes suivantes affichent la même taille de texte :
Pour compléter les styles de titres, vous trouverez des styles de sous-titres et de body.
Vous retrouverez sur la page Typography de la documentation comment changer la graisse, ajouter une typo personnalisée et utiliser les helpers CSS disponibles.
Pour coloriser le texte, choisissez une couleur dans la palette de couleur et appliquez la classe sur votre élément, en préfixant avec “text-” pour coloriser le texte et/ou “bg-” pour coloriser le fond.
Par exemple :
Margins et paddings
Sur le même principe que Bootstrap, Quasar propose plusieurs mot-clés pour définir les tailles : xs, sm, md, lg et xl.
Pour régler les margins et paddings d’un bloc il faut combiner ces tailles avec un type et une direction selon le modèle :
q-[type][direction]-[taille]Le type est “p” pour padding ou“m” pour margin.
Les valeurs pour la direction sont :
- t (top), r (right), b (bottom), l(left)
- a (all), x (left and right), y (top and bottom)
Dans la pratique, cela donne :
Pour aller plus loin dans la gestion des styles de Quasar avec notamment les variables Sass / SCSS / Stylus, les breakpoints et autres classes de body, reportez-vous à la documentation des styles.
Les icônes
Quasar utilise par défaut les Material Icons.
Il est tout à fait possible d’utiliser d’autres bibliothèques d’icônes (Font Awesome, Ionicons, Themify, etc…) ou d’en utiliser plusieurs en même temps.
Il suffit de préciser la bibliothèque d’icônes à utiliser dans le fichier de configuration quasar.conf.js, dans la section “extras”.
Par défaut :
extras: [
'material-icons'
]De base, les composants Quasar référencent des icônes de la bibliothèque Material. Si vous souhaitez utiliser uniquement Font Awesome et donc désactiver Material, pensez à modifier les icônes qui viennent avec le code des composants pour conserver un affichage correct.
Exemples d’affichage d’une icône :
Voici le résultat :
Conclusion
Il resterait encore tant à dire sur Quasar.
Nous n’avons pas abordé les helpers, ni parlé des plugins, des utils, du SSR, de l’intégration d’une librairie externe, des tests unitaires et end to end, des fonctionnalités spécifiques aux PWA (Progressive Web Apps), de la génération d’applications desktop avec Electron ou d’extensions navigateurs (Browser extensions — BEX).
Il faudrait continuer ce double article en y ajoutant de nouvelles parties, mais vous savez quoi ? Le mieux est directement de se lancer et d’apprendre au fur et à mesure de vos besoins.
J’espère que cette mise en jambe vous aura donné envie de donner une chance à Quasar.
Pour finir, sachez que le dimanche 5 juillet 2020 à 15h a eu lieu la première conférence dédiée au framework : Quasar.Conf.
Le live est disponible en replay sur Youtube :
