Comment ajouter du code de votre application au thème d'un client

Cet article accompagne une vidéo de la chaîne YouTube ShopifyDevs. Shayne Parmelee, Developer Advocate chez Shopify, vous montre comment effectuer l'une des tâches les plus courantes pour un développeur Shopify : l'ajout de code d’une application au thème d'un client, lorsque l’application interagit avec le thème ou y ajoute des fonctionnalités. Il présentera les deux approches possibles et les avantages de chacune.

Dans cet article, nous vous expliquons comment :

• Ajouter du code JavaScript pour les tâches d'arrière-plan sur les pages
• Afficher sous condition un fragment de code en utilisant l'objet Liquid content_for_header
• Supprimer automatiquement du code avec des ScriptTags

Avant de commencer

Nous répondons aujourd’hui à l'une des questions les plus fréquemment posées sur la plateforme des développeurs : comment ajouter facilement et efficacement du code d’une application dans un thème ?

Les développeurs utilisent plusieurs méthodes différentes. Nous allons ici aborder deux des méthodes les plus courantes et vous expliquer laquelle est à privilégier.

La première option est de charger notre code dynamiquement via JavaScript. Cela fonctionne très bien pour les tâches d'arrière-plan, comme le suivi des conversions par exemple. Cependant, ce n'est pas idéal si vous devez rendre du contenu que les utilisateurs devront voir ou avec lequel ils devront interagir.

La deuxième option est l’affichage conditionnel de contenu Liquid, basé sur la présence d'un ScriptTag. Cette option est parfaite pour afficher des éléments et éviter à vos clients d'avoir à supprimer du code de leurs thèmes si l'application est désinstallée, car dans ce cas le contenu ne s'affichera tout simplement plus.

Les ScriptTags sont des scripts distants qui sont automatiquement supprimés lorsqu'une application est désinstallée. Ils sont très importants dans les deux approches. La ressource ScriptTagg est un code JavaScript exécuté à distance qui est chargé dans les pages de la vitrine virtuelle d'une boutique ou dans la page de statut de commande pour le paiement. Elle vous permet d'ajouter des fonctionnalités à ces pages sans modifier les templates des thèmes.

Voyons plus en détail les deux options.

Première option : chargement de code avec JavaScript

Vous voyez à droite un exemple avec le thème Debut, le thème par défaut qui est attribué à la boutique de tous les clients. Aucun changement n'a été apporté au thème Debut pour l'instant. Effectuons une requête pour savoir si des ScriptTags sont inclus dans cette application pour cette boutique. Nous constatons qu'il n'y en a aucun. Nous allons donc en créer un.

Créer un ScriptTag

Nous devons définir deux attributs pour notre ScriptTag lors de sa création.

Le premier est l'événement. Ici nous utilisons l'événement onload. Cela nous permet d’assurer un chargement sur chaque page. La source ici est scripttags.ngrok.io (consultez notre documentation pour en savoir plus sur les sources et autres attributs). Il s'agit simplement d'un serveur rapidement configuré pour servir un ScriptTag. Auparavant, un tableau vide était renvoyé ici. Maintenant, si nous effectuons une nouvelle requête, nous voyons que le ScriptTag a bien été créé.

En elle-même, cette balise ne va pas faire grand-chose, il s'agit simplement d'une adresse. Elle doit récupérer du code JavaScript à exécuter sur le thème. Allons dans le serveur que nous avons configuré, dans Visual Studio Code. C'est un serveur qui renvoie simplement un fichier, scripttag.js. Retournons dans notre thème, nous voyons que ce code est correctement rendu.

Pour l’instant, il n’y a qu’un console.log, rien ne s'affiche donc pour l'instant, mais nous allons changer cela tout de suite. Copions du code que nous avons écrit à l'avance. C'est un code très simple, avec quelques styles en ligne, une boîte, qui indique juste que c'est une barre chargée avec JavaScript. Nous allons rendre cela dans l'élément script.div, que nous n'avons pas encore écrit.

Pour créer script.div, nous allons dans notre thème, nous sélectionnons « Modifier le code », et puisque nous souhaitons qu'il s'applique à toutes nos pages, nous l'ajoutons dans notre mise en page theme.liquid. Juste en dessous de cette section d'en-tête, nous allons ajouter <div id=”ScriptApp”></div>.

Remarque sur le comportement attendu d'un ScriptTag

Après avoir enregistré, nous constatons que la barre se charge bien, mais qu'il y a tout de même un problème : elle n’apparaît qu’une fois que le reste de la page est chargé. C'est le comportement attendu des ScriptTags. Ce comportement est acceptable si nous effectuons des tâches d'arrière-plan comme un suivi des conversions, pour lesquelles l'utilisateur n'a pas à interagir avec le rendu. C'est vraiment le premier cas d'utilisation des ScriptTags. Mais dans notre exemple, le fait que la barre s'affiche après le reste de la page est assez dérangeant.

Certains développeurs d'applications ont trouvé des astuces pour contourner le problème : ils rendent cette barre verte avec des espaces dans un premier temps et ajoutent le texte ensuite, ou ils utilisent un texte fictif, ou ils remplissent les parties pour lesquelles un appel distant est nécessaire uniquement lorsque l'appel a été effectué. Mais quoi que vous fassiez, ce code s'exécutera après que le reste du thème s'affiche, donc son contenu apparaîtra subitement.

Deuxième option : affichage conditionnel de contenu avec Liquid

La première chose que nous allons faire ici est d'ajouter un nouveau fragment. Appelons-le script-tag-app. C'est un simple morceau de code auquel nous pouvons faire référence depuis notre autre fichier de thème. Là encore, il s'agit d'une simple barre avec du style en ligne, qui s'affichera sur le thème.

La balise {{ content_for_header }} est très importante. C'est dans cette balise {{ content_for_header }} que seront rendues les adresses pour tous les ScriptTags de la page.

Nous pouvons donc utiliser ce comportement afin de savoir si l'application est installée ou non, tant que nous ajoutons toujours un ScriptTag à la boutique lorsque l'application est installée. Dans notre cas, le ScriptTag que nous avons créé est toujours là, et voici notre adresse.

Nous allons vérifier que ce ScriptTag est bien présent dans notre balise {{ content_for_header }}, puis nous allons afficher conditionnellement le fragment. Écrivons donc :

{% section ‘header’ %}
{% if content_for_header contains ‘script-tags.ngrok.io’ %}
{%render ‘script-tag-app’ %}
{% endif %}

Maintenant, si nous rechargeons la page, nous voyons que la barre s'affiche toujours, car elle est affichée par le moteur de rendu du thème, Liquid, et non par un appel JavaScript distant.

Les avantages de l'affichage avec Liquid

Nous voyons ici aussi que nous pouvons récupérer des informations contextuelles à propos de la page en cours d'affichage. De nombreuses données sont disponibles sur le thème via le moteur de rendu Liquid. Cela inclut des métadonnées que vous pouvez ajouter aux produits, à la boutique ou à tout autre élément. Ces métadonnées peuvent également être transmises par vos thèmes afin d'assurer un rendu ultra-rapide.

L'avantage de cette approche est que si nous supprimons le ScriptTag et que nous actualisons la page, notre code disparaît. L'impact sur les performances de notre thème est minime, car cette partie du code est simplement évaluée comme fausse et ne sera jamais rendue. Cela évite une situation non souhaitable qui pourrait se produire si nous avions directement rendu cette partie de code. Enlevons l'opérateur conditionnel. Dans ce cas, si l'application est désinstallée, il est possible que la barre s'affiche toujours, même si l'utilisateur ne peut plus la configurer avec votre application.

Bien sûr, nous ne voulons pas que l'utilisateur ait besoin d'aller dans l'éditeur de thème pour ajouter du code à chaque fois que votre application est installée. Nous allons voir comment faire cela de façon automatisée. Supprimons tout le code que nous avons ajouté, nous voyons que plus rien ne s'affiche. Nous n'avons plus non plus de ScriptTags dans la boutique, nous sommes donc revenus au point de départ.

L'équivalent API pour l'affichage ou la modification de thèmes

La méthode équivalente dans l’API pour savoir quels thèmes sont installés sur une boutique est la requête pour themes.json. Nous voyons ici que Debut est le seul thème actuellement disponible, exactement comme nous l'indique l'interface administrateur.

L'équivalent API pour modifier ou inspecter une ressource spécifique dans un thème est celui-ci : nous prenons l'identifiant à partir du thème, nous ajoutons /assets.json, puis nous entrons le paramètre de requête asset[key] et précisons la ressource que nous cherchons à récupérer.

Afin de pousser le code modifié vers notre thème, nous allons effectuer une requête PUT avec le nouveau contenu. Dans notre cas, nous avons ajouté du code sous cette section d’en-tête, « section 'header' », du thème. Recherchons « section 'header' », ajoutons ce petit morceau de code préparé à l'avance, puis envoyons cette requête PUT. Mettons à jour le fichier theme.liquid, et actualisons la page pour voir à quoi cela ressemble dans l'éditeur.

Évidemment, rien ne va s'afficher pour l'instant car nous n'avons pas de ScriptTag, mais si nous recréons notre ScriptTag, la barre s'affiche de nouveau sur la boutique.

C'est la même chose pour les fragments de code : nous n'avons pas encore supprimé script-tag-app. Mais si nous le supprimons, nous voyons que cela génère une erreur indiquant que le fragment de code est introuvable. Mais les fragments de code peuvent également être créés via l'API, via des requêtes comme celles-ci.

Conclusion sur l'ajout de code au thème d'un client

Liquid est un outil très performant pour afficher du contenu sur la vitrine virtuelle et offre également énormément d'informations contextuelles sur les produits, le panier ou le client actuellement connecté. Il offre de nombreuses possibilités et nous vous conseillons donc de l'utiliser dès que vous pouvez. J'espère que cet article vous aura aidé à ajouter du code au thème d'un client.

---

Publié par Maud Leuenberger. Maud est la rédactrice en chef du blog français de Shopify.

Texte original par Shayne Parmelee. Traduction par Solenn Marchand.