JavaScript personnalisé

L’éditeur de templates fournit un onglet HTML et un onglet CSS mais pas d’onglet JavaScript dédié. Vous pouvez toutefois utiliser JavaScript en ajoutant des balises script directement dans votre HTML.

Utiliser les balises Script

Pour utiliser JavaScript dans vos templates, ouvrez une balise script dans l’onglet HTML :

<script>
  // Écrivez votre JavaScript ici.
</script>

Vous pouvez ajouter autant de balises script que nécessaire, n’importe où dans votre HTML.

Accéder aux données du Document

Pour rendre JavaScript plus puissant dans vos templates, vous pouvez accéder au payload de votre Document en tant qu’objet JavaScript.

Commencez par activer l’injection JavaScript pour votre template dans son onglet Paramètres :

Une fois activé, un objet $docPayload devient disponible dans vos scripts. Par exemple, avec ce payload :

{
  "movie": {
    "title": "12 Monkeys",
    "year": 1995
  }
}

Vous pouvez accéder aux données comme ceci :

<script>
  const movieTitle = $docPayload.movie.title;
  const titleDiv = document.getElementById('mt');
  titleDiv.textContent = movieTitle;
</script>

<div id="mt"></div>

<script>
  const movieTitle = "{{movieTitle | upcase}}";
</script>

Bibliothèques externes

Si vous avez besoin d’une bibliothèque qui transforme du texte, applique des filtres aux images, ou insère des graphiques dans votre Document, vous pouvez l’importer comme vous le feriez dans une page HTML normale.

Par exemple, pour afficher une chaîne Markdown issue de votre payload avec marked.js :

<div id="notes"></div>

<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
<script>
  document.getElementById('notes').innerHTML = marked.parse($docPayload.notes);
</script>

Toute bibliothèque chargeable via CDN peut être utilisée dans vos templates de cette manière.

Formater les dates et heures

Le moteur de PDFMonkey fonctionne sur des serveurs AWS situés en Europe. Le fuseau horaire du serveur n’est peut-être pas celui dans lequel vous souhaitez afficher vos dates.

Si les filtres Liquid ne couvrent pas vos besoins, JavaScript offre des options supplémentaires.

toLocaleString(locales, options)

La méthode toLocaleString retourne une chaîne avec une représentation de la date adaptée à la langue.

Les arguments locales et options vous permettent de spécifier la langue dont les conventions de formatage doivent être utilisées et de personnaliser le comportement de la fonction.

<script>
  // Afficher la date actuelle (date de génération du PDF) avec les conventions françaises.
  //
  new Date().toLocaleString('fr-FR');
  //=> "25/10/2050, 12:34:56"

  // Afficher une date fournie dans le payload du Document avec les conventions US.
  // Exemple de payload
  // { "someDate": "2050-10-25 12:34:56" }
  //
  new Date($docPayload.someDate).toLocaleString('en-US');
  //=> "10/25/2050, 12:34:56 PM"

  // Afficher une date avec les conventions en-US dans un fuseau horaire personnalisé.
  //
  let date = new Date(Date.UTC(2050, 1, 1, 12, 34, 56));
  new Date(date).toLocaleString('en-GB', { timeZone: 'Pacific/Honolulu' });
  //=> "01/02/2050, 02:34:56"
</script>

Vous pouvez en apprendre davantage sur la méthode toLocaleString dans sa page de documentation MDN.

Utiliser une bibliothèque

Si vous avez besoin d’une bibliothèque plus puissante, vous pouvez charger celle dont vous avez besoin. La plus fréquemment utilisée est MomentJS mais nous recommandons Luxon, une itération plus récente de la même idée par l’auteur même de MomentJS :

<script src="https://cdn.jsdelivr.net/npm/luxon@2.3.1/build/global/luxon.min.js"></script>
<script>
  let { DateTime } = luxon;
  let date = DateTime.fromISO("2050-01-01T12:34:56");
  date.plus({ days: 3 }).setZone('Pacific/Honolulu').toLocaleString(DateTime.DATETIME_HUGE);
  //=> "Tuesday, 4 January 2050, 01:34 Hawaii-Aleutian Standard Time"
</script>

Inclure des graphiques

Vous pouvez utiliser la plupart des bibliothèques de graphiques pour générer des graphiques dans PDFMonkey. D’après notre expérience, Chart.js est l’option la plus fiable : il s’affiche correctement dans tous les lecteurs PDF et propose une grande variété de types de graphiques.

Deux réglages sont essentiels pour les graphiques dans un PDF :

• animation: false — Les animations ne sont pas jouées dans un PDF. Si elles restent activées, le graphique risque d’être capturé en cours de transition, produisant un rendu vide ou incomplet.
• responsive: false — Désactiver cette option vous permet de contrôler la taille du graphique via les attributs width et height de l’élément canvas, évitant les surprises de mise en page.

Exemple avec Chart.js

L’exemple ci-dessous charge Chart.js depuis un CDN et affiche un graphique en barres à partir des données du payload du Document. Il inclut les deux réglages essentiels mentionnés ci-dessus.

Avec ce payload :

{
  "chart": {
    "labels": ["Jan", "Fév", "Mar", "Avr", "Mai"],
    "values": [120, 190, 150, 210, 175]
  }
}

Ajoutez ceci dans le HTML de votre template :

<canvas id="myChart" width="500" height="300"></canvas>

<script src="https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.js"></script>
<script>
  new Chart(document.getElementById('myChart'), {
    type: 'bar',
    data: {
      labels: $docPayload.chart.labels,
      datasets: [{
        label: 'Ventes mensuelles',
        data: $docPayload.chart.values,
        backgroundColor: '#4f8bc6'
      }]
    },
    options: {
      animation: false,
      responsive: false
    }
  });
</script>

Vous pouvez adapter cet exemple à n’importe quel type de graphique Chart.js (courbes, camembert, anneau, radar, etc.) en changeant la valeur de type et en ajustant la structure de data.

Débogage

Si votre JavaScript ne se comporte pas comme prévu, utilisez le bouton Debug en haut de l’éditeur de templates. Il ouvre la version HTML de votre template, générée à partir de vos données de test, directement dans votre navigateur.

Cela vous donne l’occasion d’inspecter les erreurs JS dans la console et devrait vous aider à comprendre ce qui ne fonctionne pas.

Compatibilité navigateur

Notre moteur PDF actuel (v5) est basé sur Chrome 133. Vous pouvez vérifier si une fonctionnalité JS spécifique est disponible en utilisant le tableau de comparaison caniuse.

Questions fréquentes

Peut-on utiliser du JavaScript dans les modèles PDFMonkey ?

Oui. Ajoutez des balises script directement dans l’onglet HTML de l’éditeur de modèle. Activez l’injection JavaScript dans les paramètres du modèle pour accéder aux données du document via l’objet $docPayload.

Quelles bibliothèques JavaScript sont disponibles dans PDFMonkey ?

Chart.js pour les graphiques et Day.js pour le formatage des dates sont intégrés au moteur de rendu. Sur les forfaits payants, vous pouvez également charger des bibliothèques JavaScript externes depuis un CDN.

Comment accéder aux données du document depuis JavaScript dans PDFMonkey ?

Activez l’injection JavaScript dans les paramètres du modèle. Un objet $docPayload devient alors disponible dans vos scripts, contenant l’intégralité du payload JSON transmis lors de la création du document.