# 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 :

```html title="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 :

![Option d’injection JavaScript dans l’onglet Settings du template](../img/template-settings-js-injection.webp)

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

```json title="JSON"
{
  "movie": {
    "title": "12 Monkeys",
    "year": 1995
  }
}
```

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

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

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

> [!WARNING]
> **Limitation d’accès aux données avec JavaScript**
>
> Lorsque vous accédez aux données avec JS, **vous ne pouvez pas les insérer** en utilisant la syntaxe `{{movieTitle}}`. Cette syntaxe est spécifique à [Liquid](./la-syntaxe-liquid.md) et est exécutée avant que votre code JS ne s’exécute.
> 
> Cela dit, vous pouvez générer du code JS en utilisant Liquid :
> 
> ```html
> <script>
>   const movieTitle = "{{movieTitle | upcase}}";
> </script>
> ```


## Bibliothèques externes

> [!WARNING]
> **Compte payant uniquement**
>
> L’inclusion de JavaScript basé sur une URL n’est possible que sur un compte payant. Les Documents incluant des fichiers JavaScript externes échoueront sur un compte gratuit. Consultez [Ressources externes](../premiers-pas/ressources-externes.md) pour la liste complète.


Si vous avez besoin d’une bibliothèque qui transforme du texte, applique des filtres aux images, ou [insère des graphiques](#including-charts) 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](https://marked.js.org/) :

```html title="HTML"
<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.

> [!TIP]
> **Utilisez Liquid en priorité**
>
> La plupart des besoins de formatage de dates sont couverts par les filtres Liquid seuls, sans JavaScript. Utilisez le filtre [in_time_zone](./filtres.md#in_time_zone) pour définir un fuseau horaire et le filtre [date](./filtres.md#date) pour formater une date.


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

### toLocaleString(locales, options)

La méthode [toLocaleString](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/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.

```html title="HTML"
<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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleString).

### Utiliser une bibliothèque

> [!WARNING]
> **Compte payant uniquement**
>
> L’utilisation d’une bibliothèque JS externe ne fonctionnera que sur un compte payant. Sur un compte gratuit, l’aperçu et la génération seront bloqués.


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](https://moment.github.io/luxon/#/?id=luxon), une itération plus récente de la même idée par l’auteur même de MomentJS :

```html title="HTML"
<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 {#including-charts}

> [!WARNING]
> **Compte payant uniquement**
>
> L’inclusion de JavaScript basé sur une URL n’est possible que sur un compte payant. Les Documents incluant des fichiers JavaScript externes échoueront sur un compte gratuit. Consultez [Ressources externes](../premiers-pas/ressources-externes.md) pour la liste complète.


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](https://www.chartjs.org/) 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 {#chartjs-example}

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 :

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

Ajoutez ceci dans le HTML de votre template :

```html title="HTML"
<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>
```

![Exemple de graphique en barres généré avec Chart.js](../img/chart-example.webp)

Vous pouvez adapter cet exemple à n’importe quel [type de graphique Chart.js](https://www.chartjs.org/docs/latest/charts/) (courbes, camembert, anneau, radar, etc.) en changeant la valeur de `type` et en ajustant la structure de `data`.

> [!WARNING]
> **Compatibilité ApexCharts**
>
> [ApexCharts.js](https://apexcharts.com/) est connu pour produire des bordures noires autour des graphiques dans certains lecteurs PDF, notamment sous Windows et sur Android. Si vous utilisez ApexCharts, testez votre rendu sur plusieurs appareils avant de passer en production.


## 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.

![Bouton Debug en haut de l’éditeur de template](../img/template-debug-button.webp)

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&nbsp;133**. Vous pouvez vérifier si une fonctionnalité JS spécifique est disponible en utilisant le [tableau de comparaison caniuse](https://caniuse.com/?compare=chrome+133&compareCats=JS,JS%20API).

> [!NOTE]
> Si vos templates utilisent une version de moteur plus ancienne, consultez [Nos moteurs](./nos-moteurs.md) pour voir quelle version de Chrome s’applique à votre moteur.



## FAQ

**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.
