LiquidJS est un moteur de template compatible Shopify, implémenté en JavaScript pur. Ce guide détaille comment étendre ses capacités via des plugins, notamment en créant des tags et filtres personnalisés pour des besoins spécifiques.

Raisons de développer des plugins

Les plugins permettent d'intégrer une logique métier dédiée, de simplifier les opérations répétées dans les templates, et d'améliorer la maintenabilité globale du code.

Configuration de l'environnement

Prérequis : Node.js et npm installés. Clonez le dépôt LiquidJS et exécutez l'installation des dépendances.

Enregistrement de tags personnalisés

Implémentation de base

Un tag simple nécessite les méthodes parse et render :

// Utilisation : {% uppercase name %}
import { Value, TagToken, Context } from 'liquidjs'

engine.registerTag('uppercase', {
    parse: function(tagToken, remainTokens) {
        this.expression = new Value(tagToken.args, engine);
    },
    render: function*(ctx) {
        const input = yield this.expression.value(ctx);
        return input.toUpperCase();
    }
});

Implémentation basée sur une classe

Pour des tags complexes, une approche orientée objet est recommandée :

// Utilisation : {% uppercase name:"alice" %}
import { Hash, Tag, TagToken, Context, Liquid } from 'liquidjs'

engine.registerTag('uppercase', class UppercaseTag extends Tag {
    private parameters: Hash;
    constructor(tagToken, remainTokens, liquid) {
        super(tagToken, remainTokens, liquid);
        this.parameters = new Hash(tagToken.args);
    }
    * render(ctx) {
        const params = yield this.parameters.render();
        return params.name.toUpperCase(); // Résultat : 'ALICE'
    }
});

Création de filtres personnalisés

Filtre de base

Les filtres transforment les données dans les templates :

// Utilisation : {{ name | uppercase }}
engine.registerFilter('uppercase', value => value.toUpperCase());

Filtre avec paramètres

Les filtres peuvent accepter des arguments supplémentaires pour des traitements flexibles :

// Utilisation : {{ 1 | addition: 2, 3 }}
engine.registerFilter('addition', (initial, a, b) => initial + a + b);

Désactivation de tags et filtres existants

Pour renforcer la sécurité, il est possible de désactiver certaines fonctionnalités :

// Désactiver un tag
const inactiveTag = {
    parse: function(token) {
        throw new Error(`Le tag "${token.name}" est désactivé.`);
    }
}
engine.registerTag('include', inactiveTag);

// Désactiver un filtre
function deactivateFilter(filterName) {
    return function() {
        throw new Error(`Le filtre "${filterName}" est désactivé.`);
    }
}
engine.registerFilter('plus', deactivateFilter('plus'));

Bonnes pratiques de dévelopepment

• Adopter le principe de responsabilité unique pour chaque plugin.
• Implémenter une gestion d'erreurs claire pour faciliter le débogage.
• Rédiger des tests unitaires pour garantir la stabilité du plugin.
• Utiliser TypeScript afin d'améliorer la qualité et la maintenabilité du code.
• S'inspirer des implémentations existantes dans le code source de LiquidJS.