Débuter efficacement avec KnockoutJS dans Magento

Contexte

Nous allons voir comment réaliser des actions très simples avec KnockoutJS dans Magento 2. Pour la rédaction de l'article, je me suis basé sur un article que j'ai rédigé récemment : Comment ajouter du contenu HTML dans un layout de l'interface d'administration.

Ajout de la structure HTML

Dans l'article précédent, nous avons un fichier PHTML nommé text.phtml qui nous servira de base pour ajouter un champ texte avec son label ainsi qu'un bouton. Une fois que l'on aura cliqué sur le bouton, nous afficherons la valeur renseignée. Voici le code HTML qui nous permettra de réaliser cela :

<section class="admin__page-section">
    <div class="admin__page-section-title">
        <span class="title"><?= $block->escapeHtml(__('Lorem ipsum dolor sit amet')) ?></span>
    </div>
    <div class="admin__page-section-content">
        <div class="admin__page-section-item">
            <div data-bind="scope: 'custom-component'" class="admin__field">
                <div class="admin__field-label">
                    <label class="label" for="input_text"><?= $block->escapeHtml(__('Label')) ?></label>
                </div>
                <div class="admin__field-control">
                    <input type="text" class="admin__control-text" name="input_text" data-bind="value: textValue" />
                </div>
                <div>
                    <button class="action-primary" data-bind="click: handleClick">
                        <?= $block->escapeHtml(__('Show value')) ?>
                    </button>
                </div>
                <div>
                    <p data-bind="text: result"></p>
                </div>
            </div>
        </div>
    </div>
</section>

Les classes CSS présentes dans le code sont celles de Magento, vous êtes libres de renseigner ce que vous souhaitez. Vous avez également la possibilité d'ajouter une feuille de style dans le but d'obtenir un rendu plus adéquat avec vos attentes.

Pour le bouton, la classe action-primary permet d'appliquer le style principal du thème de l'interface d'administration de Magento, soit le fond orange. Si vous le souhaitez, vous pouvez utiliser la classe action-secondary pour appliquer le style secondaire, soit le fond gris.

Nous avons, dans le template précédent, ajouter un attribut data-bind="scope: 'custom-component'" qui permet de définir la portée du composant Javascript personnalisé que nous allons créer dans la suite de l'article. Au sein de ce composant, nous avons défini deux variables : textValue et result. La première, instancié sur le champ input, permet de récupérer la valeur saisie dans le champ texte et la seconde, instancié sur la balise p, permet d'afficher le résultat la valeur de la variable textValue lorsque nous aurons cliqué sur le bouton. C'est sur ce dernier que nous avons défini l'appel de la fonction handleClick lorsque l'on cliquera dessus.

Création du composant Javascript

Pour créer le composant Javascript, nous allons ajouter à la fin du fichier text.phtml, le code ci-dessous qui va nous permettre d'initialiser le composant :

<script type="text/x-magento-init">
    {
        "*": {
            "Magento_Ui/js/core/app" : {
                "components" : {
                    "custom-component" : {
                        "component" : "BejeanDeveloppement_BackendDocumentation/js/custom-component"
                    }
                }
            }
        }
    }
</script>

Ce code permet d'utiliser la librairie de base de Magento Magento_Ui/js/core/app pour notre composant custom-component. La valeur "BejeanDeveloppement_BackendDocumentation/js/custom-component" permet de spécifier le chemin vers le fichier Javascript du composant. Ce dernier sera créé dans le dossier view/adminhtml/web/js du module BejeanDeveloppement_BackendDocumentation. Le fichier devra contenir le code ci-dessous :

define(['ko', 'uiComponent'],
    function (ko, Component) {
        'use strict';

        return Component.extend({
            textValue: ko.observable(),
            result: ko.observable(),

            handleClick: function () {
                this.message('La valeur renseignée est ' + this.textValue());
            },
        });
    }
);

Ici, nous définissons la logique du composant custom-component. Nous commençons par définir les dépendances à KnockoutJS et uiComponent. Nous retournons ensuite le composant avec la commande return Component.extend({});. Ce dernier contient la logique.

Les 2 lignes textValue: ko.observable() et result: ko.observable() permettent de définir les propriétés observables par KnockoutJS. Puis la fonction handleClick sera automatique appelée dès que l'on cliquera sur le bouton. Cette dernière permet d'afficher la valeur saisie dans le champ texte en assignant la valeur de la variable textValue à la variable textValue.

Il ne vous reste plus qu'à tester le composant en vous rendant dans l'interface d'administration de Magento. Avec ce code, nous avons une bonne base pour réaliser des actions plus poussées avec KnockoutJS.