Dokos
Documentation
API

Génération d'images de prévisualisation

Dodock permet de générer des images de prévisualisation (captures d'écran) à partir de HTML ou d'une URL, en réutilisant le Chromium intégré au framework — sans dépendance externe.

Génération d'images de prévisualisation

Dodock utilise un Chromium sans interface pour générer les PDF. Le module frappe.utils.preview utilise ce même Chromium pour capturer une image à partir d'un HTML ou d'une URL. Aucune dépendance supplémentaire n'est nécessaire, et les ressources locales (/assets, /files) s'affichent.

Cette fonctionnalité est une API Python réservée aux développeurs. Elle n'expose pas de point d'accès HTTP. Appelez-la depuis le code Python d'une application. Les scripts serveur ne peuvent pas l'importer.

Utilisation

from frappe.utils.preview import get_preview_from_html, get_preview_from_url

# Capturer une image à partir d'un HTML
image_bytes = get_preview_from_html("<h1>Bonjour</h1>", format="webp")

# Capturer une image à partir d'une URL
image_bytes = get_preview_from_url("https://example.com", format="jpg")

Les deux fonctions renvoient l'image encodée, en bytes.

FonctionParamètres
get_preview_from_html(html, format="jpg")html : contenu HTML à afficher. format : format de l'image
get_preview_from_url(url, wait_for=0, headers=None, format="jpg")url : page à capturer. wait_for : délai d'attente avant la capture, en millisecondes. headers : en-têtes HTTP ajoutés à la requête

Formats supportés

FormatValeur à passer
JPEG"jpg" ou "jpeg"
WebP"webp"

Un autre format lève une erreur « Invalid format ». Le format par défaut est jpg.

Comportement technique

Points clés :

  • La capture fait toujours 1280×720 pixels
  • Le rendu utilise le mode média screen (et non print)
  • Pour un HTML, Dodock intercepte les ressources locales (/assets, /files) et les lit sur le disque
  • Les aperçus et les PDF partagent la même instance de Chromium

Prérequis

Chromium doit être installé sur le bench. Il est téléchargé quand le moteur Chrome est activé pour la génération PDF (voir Moteurs de génération PDF).

Si Chromium n'est pas disponible, les appels à get_preview_from_html et get_preview_from_url lèvent une erreur.

Sécurité — surface SSRF

get_preview_from_url accepte n'importe quelle URL et ordonne à Chromium de la charger côté serveur. Cela constitue une surface d'attaque SSRF (Server-Side Request Forgery) si l'URL est fournie par un utilisateur non contrôlé. Pour cette raison, Dodock n'expose pas cette API en HTTP. Appelez-la seulement depuis du code de confiance. Si l'URL vient d'un utilisateur, validez-la avant l'appel.

Exemple dans une application

Le type de document Mon Modele et son champ contenu_html sont fictifs.

import frappe
from frappe.utils.preview import get_preview_from_html

def generer_apercu_modele(nom_modele: str) -> str:
    """Génère un aperçu WebP d'un modèle HTML et l'enregistre comme fichier."""
    modele = frappe.get_doc("Mon Modele", nom_modele)
    html = frappe.render_template(modele.contenu_html, {"doc": modele})

    image_bytes = get_preview_from_html(html, format="webp")

    fichier = frappe.get_doc({
        "doctype": "File",
        "file_name": f"apercu_{nom_modele}.webp",
        "content": image_bytes,
        "is_private": 0,
    })
    fichier.insert()
    return fichier.file_url

Voir aussi