Version de développement
Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.
Développeurs

Référence technique du constructeur d'impression

Retrouvez les points d'entrée du constructeur d'impression Dodock, les méthodes de brouillon et les règles de validation des conditions.

Référence technique du constructeur d'impression

Cette page s'adresse aux développeurs qui interviennent sur le constructeur de la version next. Pour concevoir un format dans l'interface, consultez le guide utilisateur.

Points d'entrée

Les chemins suivants appartiennent au dépôt Dodock. Les composants internes décrivent l'implémentation actuelle, pas une interface d'extension stable.

RôleChemin
Page du constructeurfrappe/printing/page/print_format_builder/
Interface Vuefrappe/public/js/print_format_builder/PrintFormatBuilder.vue
État et opérations d'éditionfrappe/public/js/print_format_builder/stores/
Disposition et sectionsfrappe/public/js/print_format_builder/components/editor/
Inspection des propriétésfrappe/public/js/print_format_builder/components/inspector/
Redimensionnementfrappe/public/js/print_format_builder/composables/useColumnResize.js
Contrôleur du formatfrappe/printing/doctype/print_format/print_format.py
Génération du rendufrappe/utils/print_format_generator.py
Conversion des anciens formatsfrappe/printing/doctype/print_format/classic_converter.py
Page d'impressionfrappe/printing/page/print/
Préréglages de stylefrappe/printing/print_style_presets.py

Le format publié utilise notamment format_data. Le brouillon conserve les propriétés modifiables par le constructeur dans draft_data. L'en-tête de lettre reste un document distinct.

Brouillons et versions

Les méthodes exposées se trouvent dans frappe.printing.doctype.print_format.print_format. Les écritures de brouillon vérifient les permissions et la valeur modified du format afin de refuser une modification concurrente.

MéthodeParamètresEffet
save_draftname, data, modifiedEnregistrer les propriétés autorisées dans le brouillon.
apply_draftname, modified, data facultatifAppliquer le brouillon au format et enregistrer une version.
discard_draftname, modifiedSupprimer le brouillon sans changer le format publié.
save_versionname, label, data, modifiedConserver une version nommée.
get_versionsnameLire les versions disponibles.
get_version_fieldsname, versionLire les propriétés d'une version.
restore_versionname, version, modifiedCharger une version dans le brouillon, sans la publier.
delete_versionname, versionSupprimer la version désignée.

useDraftSave.js coordonne l'enregistrement automatique et l'application manuelle. useVersions.js gère la consultation et la restauration. Utilisez la signature de la version installée avant d'appeler ces méthodes depuis une intégration.

Le champ roles fait partie des propriétés du brouillon (BUILDER_DRAFT_FIELDS côté serveur) et des champs d'une version (VERSION_FIELDS dans useVersions.js) : une restauration de version recharge aussi les rôles.

Conditions d'affichage

Les expressions visible_if sont évaluées côté serveur avec frappe.safe_eval. Elles utilisent la syntaxe Python, les données de doc et les paramètres de print_settings.

ExpressionRésultat
doc.status == "Paid"Afficher l'élément si le statut technique du document vaut Paid.
doc.total > 1500Afficher l'élément si total dépasse 1 500 dans la devise du document.
len(doc.get("items") or []) > 5Afficher l'élément si le document contient plus de cinq lignes dans items.

Ces exemples supposent que les données citées existent sur le type de document concerné. Les noms techniques et les valeurs de statut ne sont pas leurs traductions affichées dans l'interface. Les opérateurs JavaScript === et .length ne conviennent pas ici.

Une condition vraie affiche l'élément. Par exemple, doc.total < 100 l'affiche pour un montant inférieur à 100, au lieu de le masquer.

Les tableaux et répétiteurs peuvent aussi définir row_condition. Le générateur évalue cette expression pour chaque ligne avec la variable row. Une ligne dont la condition est fausse n'est pas imprimée. Une colonne de tableau peut définir column_condition, évaluée de la même façon que visible_if.

CasComportement
Erreur de syntaxeL'enregistrement du format est refusé : « {0} is not a valid condition », titre « Invalid Condition ». Le contrôle se fait par compile() sur visible_if, row_condition et column_condition.
Erreur à l'exécution (champ absent, type incorrect)L'élément, la ligne ou la colonne reste affiché. L'erreur est enregistrée une seule fois par expression dans le journal des erreurs, avec le titre « Print format condition failed: ».

Vérifiez les cas vrai et faux avant de publier un format, et consultez le journal des erreurs après un premier rendu.

Blocs de texte statique

Les blocs Static Text du constructeur acceptent des jetons de champ entre accolades. La syntaxe est {champ} pour un champ du document, {name} pour son nom, ou {champ_lien.champ_cible} pour un champ d'un document lié. Le motif reconnu est \{([A-Za-z_]\w*(?:\.[A-Za-z_]\w*)?)\} : les accolades contenant d'autres caractères (comme {0}) sont conservées telles quelles.

PrintFormatGenerator.prepare_static_text(df) prépare le rendu côté serveur :

  • Chaque ligne du texte saisi passe par la traduction _().
  • Les jetons reconnus sont remplacés par la valeur formatée du champ (frappe.format_value).
  • Pour les champs Text Editor, HTML Editor et Markdown Editor, le balisage HTML est supprimé (frappe.utils.strip_html) et les retours à la ligne sont aplatis en espaces.
  • Les jetons non reconnus (champ inexistant, syntaxe invalide) sont conservés dans le texte.
  • Si l'utilisateur courant n'a pas accès au champ (permlevel ou droits de lecture sur le document lié), le jeton est remplacé par une chaîne vide.

Le résultat est stocké dans df["_text"]. Le template Jinja frappe/templates/print_format/macros/StaticText.html privilégie _text et retombe sur df.text avec traduction pour l'aperçu. L'émetteur Typst (_static_text dans frappe/utils/typst_emitter.py) applique la même logique.

L'aperçu dans l'éditeur (FieldPreviewText.vue) résout les jetons côté client à l'aide de text_field_paths (filtrage des champs valides via frappe.get_meta) et du composable linked_target pour interroger les documents liés en lecture.

La méthode PrintFormatGenerator.static_text_value(match, raw=False) résout un jeton. Avec raw=True, elle renvoie cstr() de la valeur enregistrée, sans format_value, sans get_formatted, sans suppression de balisage ni aplatissement des espaces. Les blocs Code-barres l'utilisent (voir Valeur construite avec des champs).

Numéros de page dans l'en-tête et le pied de page

Dans l'en-tête (layout["header"]) et le pied de page (layout["footer"]) du format, un bloc Static Text remplace aussi {page} et {page_count} par le numéro de la page et le nombre de pages. Dans les sections du corps, ces jetons restent dans le texte.

  • Jinja : la macro render_field(df, doc, in_zone=false) de frappe/templates/print_format/macros.html reçoit in_zone=true depuis render_zone(), qui rend l'en-tête et le pied de page. Avec in_zone, StaticText.html remplace {page} par <span class="page"></span> et {page_count} par <span class="topage"></span>, après échappement de la ligne. Chromium et PlutoPrint remplissent ces éléments page par page, comme pour le numéro de page standard (page_number_html()). Ils ne le font que dans le cadre répété de l'en-tête et du pied de page (repeat_header_footer).
  • Typst : TypstEmitter._field_body() calcule in_zone (la section est layout["header"] ou layout["footer"]) et le passe à _static_text(df, in_zone). Dans une zone, _static_text découpe le texte avec PAGE_NUMBER_TOKEN (\{(page|page_count)\}), échappe les parties de texte avec typst_escape et remplace chaque jeton par son expression de PAGE_NUMBER_COUNTERS : #context counter(page).display("1"); pour page, #context counter(page).final().first(); pour page_count. Le point-virgule termine l'expression : un texte collé au jeton, comme (, reste du texte. Sans repeat_header_footer, TypstEmitter.emit() place l'en-tête au début du corps et le pied de page à la fin. Les compteurs sont alors évalués à cet endroit : la première page pour l'en-tête, la dernière pour le pied de page.
  • prepare_static_text() s'exécute avant ce remplacement et STATIC_TEXT_FIELD reconnaît aussi {page} et {page_count}. Si le type de document a un champ page ou page_count, le jeton est donc remplacé par la valeur de ce champ.

Ce mécanisme est distinct du réglage page_number du Print Format (Select : Hide, Top Left, Top Center, Top Right, Bottom Left, Bottom Center, Bottom Right), qui ajoute un compteur standard « X de Y » (PAGE_NUMBER_POSITIONS pour Typst, PAGE_NUMBER_ALIGN et page_number_html() pour Chromium et PlutoPrint).

Colonnes vides des tableaux

Les tableaux du constructeur peuvent contenir des colonnes vides, prévues pour être remplies à la main sur le document imprimé. Dans table_columns, une telle colonne porte fieldtype: "Blank", un fieldname généré de la forme blank_ suivi de 6 caractères aléatoires, un label modifiable (vide à la création) et une width (10 par défaut).

  • TableFieldInspector.vue ajoute l'entrée { label: "Blank column", fieldname: "__blank", fieldtype: "Blank" } à la liste des colonnes disponibles ; elle n'accepte pas de champs fusionnés (le sélecteur Add field... est masqué pour fieldtype === "Blank").
  • PrintFormatGenerator (frappe/utils/print_format_generator.py) exempte ces colonnes de la suppression des colonnes sans valeur (column_has_value) : une colonne Blank est toujours rendue, alors qu'une colonne de champ dont aucune ligne n'a de valeur est omise du tableau imprimé.
  • Le template frappe/templates/print_format/macros/Table.html affiche le libellé (ou une chaîne vide si aucun libellé) dans l'en-tête et une cellule <td> vide pour chaque ligne d'une colonne Blank.
  • L'émetteur Typst (frappe/utils/typst_emitter.py) renvoie une chaîne vide pour une colonne sans fieldname ou avec fieldtype == "Blank".

La procédure côté interface est décrite dans le guide utilisateur : Mettre en page un format d'impression.

Codes-barres

Dokos dessine les blocs Code-barres (fieldtype: "Barcode") sur le serveur. Chromium, PlutoPrint, Typst et l'éditeur reçoivent donc la même image SVG. Les fonctions se trouvent dans frappe/utils/print_format_generator.py.

FonctionParamètresRésultat
get_qr_code (whitelisted)valueQR code sous forme d'URI de données data:image/svg+xml;base64,…. Le SVG est produit par pyqrcode avec scale=5, quiet_zone=1 et omithw=True.
get_barcode (whitelisted)value, barcode_format (CODE128 par défaut), show_text (True par défaut)Code-barres sous forme d'URI de données SVG. Une valeur qui commence par <svg est renvoyée telle quelle en URI de données (caractères de contrôle retirés). Pour QR, la fonction appelle get_qr_code. Elle renvoie None si le format n'est pas dans LINEAR_BARCODE_FORMATS, si la valeur est vide, ou si la valeur n'est pas encodable telle quelle (voir Codes linéaires).

Les deux fonctions lèvent frappe.ValidationError (« La valeur du code-barres doit être un texte de moins de 2000 caractères ») si value n'est pas une chaîne ou dépasse 2 000 caractères.

Codes linéaires

LINEAR_BARCODE_FORMATS associe chaque format de l'éditeur à un codage de python-barcode et à ses options :

FormatCodage python-barcodeOptions
CODE128code128—
CODE39code39add_checksum: False
EAN13ean13—
EAN8ean8—
EAN14ean14—
UPCAupca—
ISBN13isbn13—
ITFitf—
GS1_128gs1_128—

Avant l'encodage, get_barcode adapte ou refuse certaines valeurs :

  • ISBN13 : les tirets sont retirés (value.replace("-", "")).
  • GS1_128 : une valeur qui contient ( renvoie None. Les parenthèses autour des identifiants d'application sont du texte d'étiquette, et python-barcode les encoderait.
  • Une BarcodeError levée par barcode.get() ou build() renvoie None.

Après l'encodage, get_barcode compare code.get_fullcode() à la valeur reçue : si fullcode.upper() ne commence pas par value.upper(), elle renvoie None. python-barcode ajoute une clé de contrôle manquante, remplace une clé fausse, complète un code ITF de longueur impaire avec un zéro initial et met en majuscules un code CODE39. Seul l'ajout d'une clé manquante (et la mise en majuscules) passe donc ce contrôle : une clé fausse ou un ITF complété ne produit pas de code-barres. Par exemple, 590123412345 en EAN13 donne 5901234123457, mais 5901234123450 renvoie None.

python-barcode calcule seulement la suite des modules (build()). Dokos écrit le SVG lui-même :

  • chaque module a une largeur de 3 unités, et une barre a une hauteur de 40 ;
  • avec show_text, le SVG a une hauteur de 60 et contient un élément <text> avec fullcode échappé, clé de contrôle comprise (police DejaVu Sans Mono, monospace, taille 16) ;
  • le SVG porte width, height et viewBox.

Préparation du bloc

PrintFormatGenerator.prepare_barcode(df) est appelée pour chaque élément de la disposition (_prepare_field). Elle écrit le résultat dans df["_barcode_data_uri"].

CasValeur lueFormat
Bloc ajouté dans le constructeur (custom) avec barcode_fieldcstr(doc.get(barcode_field))barcode_format (CODE128 par défaut) et show_text
Bloc ajouté dans le constructeur (custom) sans barcode_fieldbarcode_value dont les jetons {champ} et {champ_lien.champ_cible} sont remplacés par leur valeur brutebarcode_format (CODE128 par défaut) et show_text
Champ Barcode glissé depuis la liste des champsdoc.get(fieldname)QR si is_qr_barcode_options() reconnaît les options du champ (qr, qrcode ou un JSON {"format": "qrcode"}), sinon CODE128. Le texte est toujours affiché.

Une valeur qui commence par <svg est encodée telle quelle en URI de données, sans passer par get_barcode. Une valeur vide ne produit pas _barcode_data_uri.

Valeur construite avec des champs

Pour un bloc custom sans barcode_field, prepare_barcode applique STATIC_TEXT_FIELD.sub() à barcode_value avec static_text_value(match, raw=True). Le motif et les règles de résolution sont ceux des blocs de texte statique, avec ces différences :

  • la valeur est cstr() de la valeur enregistrée : un nombre, une date ou une monnaie n'est pas formaté, et une valeur None devient une chaîne vide ;
  • pour un champ lié, resolve_linked_path renvoie None quand l'utilisateur n'a pas accès au lien ou à la cible, quand le document lié est illisible ou quand la valeur est None : le jeton devient une chaîne vide ;
  • les jetons non reconnus (champ inexistant, champ Table, lien invalide) restent dans la valeur ;
  • le texte autour des jetons n'est pas traduit (pas d'appel à _()).

Par exemple, "{priority}/{date}" sur un ToDo de priorité High et de date 2026-02-11 encode High/2026-02-11 (test test_barcode_value_fills_field_placeholders_with_raw_values).

Rendu

  • La macro Jinja frappe/templates/print_format/macros/Barcode.html n'imprime rien sans _barcode_data_uri. Sinon, elle imprime une balise <img> dans div.print-barcode. Sa largeur est df.width, ou 35mm pour un QR code sans largeur. Pour un code linéaire sans largeur, l'image garde la taille du SVG.
  • print_format_doc.css applique max-width: 100% à .print-format-doc .print-barcode img. Une image plus large que sa colonne est réduite à la largeur de celle-ci.
  • Le SVG du QR code n'a pas d'attributs width et height (omithw=True). La largeur de la balise <img> détermine donc sa taille, aussi dans les PDF PlutoPrint.
  • TypstEmitter._barcode() (frappe/utils/typst_emitter.py) décode l'URI de données et intègre le SVG avec #image(...). Sa largeur est df.width, ou 35mm pour un QR code. Pour un code linéaire sans largeur, l'image n'a pas de largeur explicite. typst_blockers et typst_blockers_client ne signalent plus les codes-barres.
  • L'aperçu de l'éditeur (FieldPreviewBarcode.vue) appelle get_barcode avec frappe.call (délai de 300 ms). Une valeur qui commence par <svg est affichée directement. Sans résultat, l'aperçu affiche « Valeur invalide pour {0} ». print_format.html ne charge plus print.bundle.js pour dessiner les codes-barres dans le navigateur.
  • Pour une valeur construite avec des jetons, FieldPreviewBarcode.vue remplace côté client les jetons reconnus par text_field_paths (barcode_raw_value). Les champs liés sont lus avec linked_target et frappe.db.get_value, après chargement du type de document lié (frappe.model.with_doctype). La fonction raw_text() reproduit le str() de Python : un nombre décimal entier (type numérique autre que Int) s'écrit avec une décimale (5.0), une valeur null donne une chaîne vide. Le même traitement s'applique à un barcode_field. La zone Value de BarcodeRows.vue a pour suggestion de saisie Text or {fieldname}.
  • plutoprint_can_render() (frappe/utils/pdf_generator/pluto.py) renvoie toujours False si le HTML contient data-barcode-value=. Seul un format HTML personnalisé qui dessine un code-barres dans le navigateur est concerné : la macro Barcode.html ne produit plus cet attribut.

Conversion depuis Print Designer

PrintDesignerConverter.barcode_node() (print_designer_converter.py) convertit le type de code-barres Print Designer (barcodeFormat, en minuscules) avec BARCODE_FORMATS : qrcode et qr → QR, code128 → CODE128, code39 → CODE39, ean, ean13 et jan → EAN13, ean8 → EAN8, ean14 et gtin → EAN14, upc et upca → UPCA, isbn et isbn13 → ISBN13, itf → ITF, gs1_128 → GS1_128. Un autre type devient CODE128, et la conversion ajoute la note « The {0} barcode type was changed to CODE128. » (message non traduit) quand le bloc est converti.

barcode_node() reconnaît les parties {{ doc.<champ> }} avec DOC_FIELD ({{\s*doc\.(\w+)\s*}}). Une valeur qui se réduit à une seule partie vers un champ connu (ou name) devient un bloc avec barcode_field. Sinon, les parties sont réécrites en {champ} : si le reste ne contient plus de Jinja et que chaque champ cité existe dans le type de document sans être de type Table (name est accepté), le bloc reçoit ce barcode_value, par exemple {{ doc.title }}-{{ doc.name }} devient {title}-{name}. Un code-barres linéaire dont la valeur contient un autre Jinja est toujours laissé de côté avec une note ; un QR code reste un bloc HTML.

Pour un code-barres converti en bloc HTML, element_html() calcule barcode_value avec doc.get('<champ>') et remplace None par une chaîne vide, ce qui évite d'encoder « None » pour un champ vide.

La procédure côté interface est décrite dans le guide utilisateur : Mettre en page un format d'impression.

Jinja et dépendances

get_qr_code est disponible dans le contexte Jinja des blocs HTML du constructeur (set_field_renderers) et de l'aperçu render_jinja_template. get_barcode n'est pas ajoutée à ce contexte.

pyproject.toml déclare python-barcode~=0.16.1 et PyQRCode~=1.2.1.

La procédure côté interface est décrite dans le guide utilisateur : Mettre en page un format d'impression.

Aperçu et paramètres d'impression

download_builder_preview_pdf reçoit les données du format en cours et l'identifiant du document à imprimer. L'aperçu ne dispense pas des permissions de lecture et d'impression sur ce document.

Le panneau du format modifie ses propriétés, comme les marges, les couleurs ou le moteur PDF. La fenêtre ouverte par open_print_settings modifie le document singleton Print Settings avec frappe.client.set_value. Ces paramètres concernent le site.

Page et arrière-plan d'un format du constructeur

La disposition (format_data) peut porter deux clés de premier niveau, éditées dans PrintSettingsPanel.vue.

CléContenuRemarques
pagesize, orientation et, pour une taille personnalisée, width et heightsize : une option du champ pdf_page_size de Print Settings, y compris Custom. width et height (en mm) n'existent que si size vaut Custom. orientation : Landscape uniquement. Les valeurs par défaut (taille vide, Portrait) sont retirées de l'objet, et la clé page disparaît quand il est vide.
backgroundimage et opacityopacity va de 0 à 100 (100 par défaut). La clé est supprimée quand l'image est vidée.

Taille de page

  • layout_page_settings(layout) (frappe/utils/print_format_generator.py) convertit layout["page"] en clés de Print Settings (pdf_page_size, pdf_page_width, pdf_page_height, page_orientation). Une taille inconnue ou une orientation autre que Portrait ou Landscape est ignorée. Pour size == "Custom", width et height sont lus avec flt : la conversion produit pdf_page_size: "Custom", pdf_page_width et pdf_page_height seulement si les deux valeurs sont comprises entre MIN_PAGE_MM (10) et MAX_PAGE_MM (5 000). Sinon aucune clé de taille n'est produite et la taille de Print Settings s'applique.
  • Dans PrintSettingsPanel.vue, la liste des tailles vient de frappe.meta.get_print_sizes(), Custom compris, et chaque libellé passe par __(). set_page() : avec size == "Custom", width et height valent 210 et 297 s'ils sont absents ; avec une autre taille, ces deux clés sont supprimées. Les lignes Width et Height (StepperRow, unité mm, minimum 10, pas 5) ne s'affichent que pour Custom, et clamp_page_mm() ramène chaque valeur entre 10 et 5 000.
  • StepperRow.vue accepte la propriété decimals (faux par défaut). Active, elle arrondit la valeur saisie ou le résultat d'un pas à un chiffre après la virgule (Math.round(x * 10) / 10) ; sinon la saisie passe par parseInt.
  • PrintFormatGenerator.format_page_settings() applique cette conversion à format_data du format. Une valeur de format_data illisible donne un dictionnaire vide.
  • build_context() applique d'abord ces réglages sur Print Settings, puis les surcharges de l'impression (settings_override), puis apply_page_overrides(). L'ordre de priorité est donc : surcharge de la page d'impression, format, Print Settings. apply_page_overrides() est désormais appelée même sans surcharge.
  • Dans frappe/printing/page/print/print.js, les champs pdf_page_size et page_orientation proposent une valeur vide (« Default ») et démarrent vides. Une valeur vide supprime la clé de page_overrides.
  • La méthode whitelisted frappe.utils.print_format_generator.get_page_size_mm(page=None) accepte un dictionnaire ou une chaîne JSON page ({"size", "orientation", "width", "height"}) et renvoie (largeur, hauteur) en mm. Elle passe par layout_page_settings puis page_size_mm : pour Custom, la largeur et la hauteur valent pdf_page_width et pdf_page_height, ou 210 et 297 si elles sont vides. Les dimensions sont inversées en Landscape. PrintFormat.vue l'appelle avec layout.page et la rappelle quand celui-ci change.

Reprise de la taille personnalisée à la conversion

  • classic_converter.convert_classic_to_beta() copie paper_width et paper_height du format dans layout["page"] quand paper_size vaut Custom. La clé page n'est écrite que si layout_page_settings en tire un réglage valide.
  • print_designer_converter.custom_page_size(width_mm, height_mm, sizes) reçoit les dimensions en mm. Elle trie les deux valeurs, les compare à PageSize.page_sizes avec une tolérance de 1 mm et renvoie {"size": <nom>} (plus "orientation": "Landscape" si la largeur dépasse la hauteur) pour la première taille standard qui correspond. Sinon, elle renvoie {"size": "Custom", "width": ..., "height": ...} arrondis à un chiffre après la virgule.
  • PrintDesignerConverter.page_settings() convertit les pixels de la page Print Designer en mm (PX_PER_MM = 96 / 25.4) quand currentPageSize vaut custom et que la largeur et la hauteur sont renseignées. La note « The custom paper size was not kept; set the paper size in the editor. » n'est donc plus ajoutée.
  • Le patch frappe.patches.v16_0.repair_converted_custom_paper_size reprend les formats convertis (print_format_builder_beta = 1, classic_format_data renseigné, paper_size = "Custom") et leur ajoute page.size, width et height dans format_data avec add_page_size(), sans mettre à jour modified. repair_converted_print_formats.add_page_size() et repair_layout() acceptent désormais paper_width et paper_height, et le patch repair_converted_print_formats les lit aussi.

Image d'arrière-plan

  • PrintFormatGenerator.clean_background(background) normalise layout["background"]. L'image doit correspondre en entier à BACKGROUND_IMAGE_URL : un chemin commençant par /, une adresse http:// ou https://, ou data:image/<type>;base64,<données>. Sinon, l'arrière-plan est ignoré (None). Le résultat contient image, url (adresse encodée avec urllib.parse.quote, sauf pour data:) et opacity (entier borné entre 0 et 100, 100 si vide).
  • print_format.css ajoute, si layout.background existe, --pfb-cell-bg: transparent pour le corps du document et rend html et body transparents avec Chromium. Hors Chromium, un pseudo-élément body::before porte l'image avec l'opacité. print_format_doc.css utilise var(--pfb-cell-bg, var(--white)) comme fond des cellules des tableaux enfants.
  • Pour Chromium, PrintFormatGenerator.underlay_background(pdf, background, password) génère un PDF d'une page contenant l'image à la taille du papier (page_size_mm), puis la fusionne sous chaque page du PDF avec pypdf (merge_page(..., over=False)). Quand un arrière-plan existe, l'option password n'est pas transmise à Chromium : le PDF final est chiffré après la fusion.
  • Pour Typst, TypstEmitter._page_background() ajoute background: à #set page(...). L'image est intégrée par _embed_image ; l'opacité est rendue par un rectangle blanc semi-transparent superposé. Si l'image ne peut pas être intégrée, frappe.throw s'arrête avec le titre « Typst renderer unavailable » (fr : « Moteur de rendu Typst indisponible »).
  • typst_blockers (frappe/utils/typst_emitter.py) et typst_blockers_client (print_format_builder/utils.js) ajoutent le blocage « Background image loaded from a web address » quand background.image commence par http://, https:// ou // (le contrôle client reconnaît aussi //).

La procédure côté interface est décrite dans le guide utilisateur : Créer et modifier un format d'impression.

Taille de papier du format

Cette section décrit des champs des formats qui ne passent pas par le nouveau constructeur. Le doctype Print Format porte un champ paper_size (Select, libellé « Format du papier »), affiché lorsque le format n'est ni créé avec le nouveau constructeur (print_format_builder_beta) ni en impression brute (raw_printing). Les options sont "", A4, A5, A3, Letter, Legal, Receipt 80 mm, Receipt 58 mm et Custom (libellés « Ticket 80 mm », « Ticket 58 mm » et « Personnalisation ») ; le typage du contrôleur les déclare sous forme de DF.Literal. Une valeur vide conserve la taille définie dans les Print Settings.

Deux champs numériques paper_width et paper_height (DF.Float, libellés « Largeur du papier (en mm) » et « Hauteur du papier (en mm) ») apparaissent et deviennent obligatoires lorsque paper_size vaut Custom, hors nouveau constructeur et impression brute (depends_on et mandatory_depends_on : eval:doc.paper_size == "Custom" && !doc.print_format_builder_beta && !doc.raw_printing). La description de paper_height conseille de petites marges pour les petites tailles, par exemple @page { margin: 2mm; } dans le CSS personnalisé.

PrintFormat.validate_paper_size(), appelée depuis validate(), contrôle ces valeurs à l'enregistrement : si paper_size vaut Custom (hors nouveau constructeur et impression brute) et que frappe.utils.flt(self.paper_width) ou frappe.utils.flt(self.paper_height) est inférieure ou égale à 0, l'enregistrement est refusé par frappe.throw avec le titre « Format de papier non valide » et un message demandant des dimensions strictement supérieures à 0.

La génération PDF applique ces champs dans frappe/utils/pdf_generator/browser.py :

  • Browser._set_page_size_from_print_format() lit paper_size, paper_width et paper_height avec frappe.get_cached_value("Print Format", self.print_format, ["paper_size", "paper_width", "paper_height"]). Elle ne modifie aucune option si celles-ci contiennent déjà page-size, page-width ou page-height.
  • Le dictionnaire RECEIPT_WIDTHS associe Receipt 80 mm à 80mm et Receipt 58 mm à 58mm. Pour un reçu, les options reçoivent cette largeur en page-width, 297mm en page-height et fit-height à True.
  • Si paper_size vaut Custom et que paper_width et paper_height sont renseignées, les options reçoivent page-width: f"{width}mm" et page-height: f"{height}mm" : la page PDF a exactement ces dimensions.
  • Pour les autres tailles renseignées, la valeur du champ est placée dans page-size.

Ces réglages s'appliquent aux moteurs Chrome et PlutoPrint. Le moteur Typst ne traite que les formats du nouveau constructeur (get_typst_pdf ignore un format sans print_format_builder_beta) : il n'imprime pas les formats HTML.

frappe/utils/print_format_generator.py applique aussi la taille du format pour les formats de l'ancien constructeur : lorsque format_data se parse en une liste (disposition de l'ancien constructeur), les paramètres de page sont calculés à partir du format — Custom avec paper_width et paper_height produit pdf_page_size: "Custom", pdf_page_width et pdf_page_height ; toute autre valeur de paper_size produit layout_page_settings({"page": {"size": pf.paper_size}}). Ces formats utilisent donc la taille définie sur le format plutôt que celle des Print Settings. build_context() copie ce résultat dans self.print_settings, que lisent page_options() (Chrome) et TypstEmitter._page_size_mm() : la taille s'applique donc aussi au moteur Typst pour un format du constructeur dont format_data est encore une liste.

  • Browser.fit_body_height() s'exécute dans prepare(), après fit_body_to_page() et uniquement lorsque fit-height est actif : elle mesure la hauteur du contenu, puis fixe paperHeight à cette hauteur (à l'échelle appliquée, avec une marge de 2 px), à laquelle s'ajoutent les marges haute et basse définies dans les options. La page imprimée a ainsi exactement la hauteur du contenu.

La mesure de la hauteur du contenu est fournie par get_content_height() : sur frappe.utils.chromium.page.Page pour le moteur Chrome (la méthode neutralise temporairement les hauteurs fixes de html, body et .print-format avant de lire scrollHeight), et sur PlutoPage dans frappe/utils/pdf_generator/pluto.py pour PlutoPrint. Le rendu des tickets est donc identique avec les deux moteurs.

Styles d'impression

Le module frappe.printing.print_style_presets applique des préréglages aux sections et tableaux du format standard. Le dictionnaire STYLE_PRESETS définit les réglages pour les styles Modern, Classic, Striped et Monochrome (bordures de section, style de tableau, en-tête de tableau, espacements).

La fonction apply_style_preset(layout, style) modifie le dictionnaire de layout en appliquant le préréglage correspondant au style. Elle retourne le layout inchangé si le style est inconnu ou si le layout n'est pas un dictionnaire.

La page d'impression expose la méthode whitelisted frappe.printing.page.print.print.get_print_styles() qui retourne la liste des noms de styles d'impression actifs (Print Style non désactivés), ordonnés par date de création.

Les fonctions d'envoi d'email acceptent les paramètres print_style et print_settings :

  • frappe.core.doctype.communication.email.make et _make
  • frappe.core.doctype.communication.mixins.CommunicationEmailMixin.mail_attachments
  • frappe.core.doctype.communication.mixins.CommunicationEmailMixin.sendmail

Ces paramètres sont transmis à la génération du PDF pour les pièces jointes. Le téléchargement PDF (frappe.utils.print_format.download_pdf) accepte également les paramètres style et settings dans l'URL.

Le format standard applique la classe CSS .print-format-doc--standard sur le corps du document. Les styles d'impression peuvent cibler cette classe pour modifier l'apparence du format standard sans affecter les formats personnalisés.

Rôles autorisés à imprimer avec un format

Le doctype Print Format porte un champ roles (Table MultiSelect sur Has Role, libellé « Rôles »), dans la section access_section (« Accès »). La section est masquée pour un format de rapport (print_format_for == "Report") et repliée tant que roles est vide. Sans rôle, le format est ouvert à tous.

Les fonctions de frappe.printing.doctype.print_format.print_format :

FonctionEffet
can_print_with(print_format)Retourne True si le format n'a aucun rôle, ou si l'utilisateur courant a au moins un de ces rôles (frappe.get_roles()).
check_print_format_roles(print_format)Lève frappe.PermissionError (titre « Non autorisé », message « Vous n'êtes pas autorisé à imprimer avec {0} ») si can_print_with est faux.
check_print_format_roles_by_name(print_format)Ne fait rien pour une valeur vide, pour Standard ou pour un format inexistant ; sinon appelle check_print_format_roles sur le document en cache.

Points de contrôle côté serveur :

  • frappe.www.printview.get_print_format_doc : un format limité demandé explicitement (paramètre ou frappe.form_dict.format) et différent du format par défaut du type de document lève l'erreur. Un format limité qui est le format par défaut est ignoré : la fonction retourne None, donc Standard.
  • frappe.utils.print_utils._print_format_doc_or_none : même logique pour les PDF et les pièces jointes. Un format demandé et différent du défaut lève l'erreur ; un défaut limité retourne None.
  • frappe.core.doctype.communication.email.make appelle check_print_format_roles_by_name(print_format) quand un format est transmis.
  • frappe.flow.utils.safe_exec._readable_attachment appelle check_print_format_roles_by_name(attachment.get("print_format")) pour les pièces jointes d'impression des scripts Flow.

Côté client :

  • frappe.desk.form.meta.FormMeta ajoute à chaque format de __print_formats une liste __roles (rôles des lignes Has Role dont le parent est le format).
  • frappe.meta.get_restricted_print_formats(doctype) (model/meta.js) retourne les noms des formats du type de document dont les rôles ne contiennent aucun rôle de l'utilisateur (frappe.user.has_role). Elle lit __roles, ou à défaut roles.
  • frappe.meta.get_print_formats(doctype) exclut ces formats. Quand le format par défaut du type est limité, le code @dokos qui retire Standard de la liste ne s'applique pas : Standard reste le repli. Le test TestDokosPrintFormatListDropsStandard vérifie que le retrait de Standard reste dans la branche du format par défaut, qui ne s'applique pas quand ce format est limité.
  • La page d'impression (print.js) ajoute name not in restricted au filtre du champ « Format d'impression » et vide le format initial si le défaut est limité.
  • bulk_operations.js propose frappe.meta.get_print_formats(doctype) et utilise le premier élément comme valeur par défaut.

Les contrôles côté client ne remplacent pas ceux du serveur.

Conversion et validation

classic_converter.py convertit les anciennes dispositions et conserve leur source dans classic_format_data. La conversion peut signaler des éléments non repris. Comparez les documents rendus avant et après conversion. La taille de papier Custom d'un ancien format est reprise dans layout["page"] (voir Reprise de la taille personnalisée à la conversion).

Pour convertir un format Print Designer, consultez la référence de la conversion Print Designer.

Les tests du contrôleur et du convertisseur se trouvent dans frappe/printing/doctype/print_format/test_print_format.py. Une modification des composants doit aussi être vérifiée dans l'interface et sur un PDF.

Voir aussi