Référence technique du constructeur d'impression
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ôle | Chemin |
|---|---|
| Page du constructeur | frappe/printing/page/print_format_builder/ |
| Interface Vue | frappe/public/js/print_format_builder/PrintFormatBuilder.vue |
| État et opérations d'édition | frappe/public/js/print_format_builder/stores/ |
| Disposition et sections | frappe/public/js/print_format_builder/components/editor/ |
| Inspection des propriétés | frappe/public/js/print_format_builder/components/inspector/ |
| Redimensionnement | frappe/public/js/print_format_builder/composables/useColumnResize.js |
| Contrôleur du format | frappe/printing/doctype/print_format/print_format.py |
| Génération du rendu | frappe/utils/print_format_generator.py |
| Conversion des anciens formats | frappe/printing/doctype/print_format/classic_converter.py |
| Page d'impression | frappe/printing/page/print/ |
| Préréglages de style | frappe/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éthode | Paramètres | Effet |
|---|---|---|
save_draft | name, data, modified | Enregistrer les propriétés autorisées dans le brouillon. |
apply_draft | name, modified, data facultatif | Appliquer le brouillon au format et enregistrer une version. |
discard_draft | name, modified | Supprimer le brouillon sans changer le format publié. |
save_version | name, label, data, modified | Conserver une version nommée. |
get_versions | name | Lire les versions disponibles. |
get_version_fields | name, version | Lire les propriétés d'une version. |
restore_version | name, version, modified | Charger une version dans le brouillon, sans la publier. |
delete_version | name, version | Supprimer 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.
| Expression | Résultat |
|---|---|
doc.status == "Paid" | Afficher l'élément si le statut technique du document vaut Paid. |
doc.total > 1500 | Afficher l'élément si total dépasse 1 500 dans la devise du document. |
len(doc.get("items") or []) > 5 | Afficher 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.
| Cas | Comportement |
|---|---|
| Erreur de syntaxe | L'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)defrappe/templates/print_format/macros.htmlreçoitin_zone=truedepuisrender_zone(), qui rend l'en-tête et le pied de page. Avecin_zone,StaticText.htmlremplace{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()calculein_zone(la section estlayout["header"]oulayout["footer"]) et le passe à_static_text(df, in_zone). Dans une zone,_static_textdécoupe le texte avecPAGE_NUMBER_TOKEN(\{(page|page_count)\}), échappe les parties de texte avectypst_escapeet remplace chaque jeton par son expression dePAGE_NUMBER_COUNTERS:#context counter(page).display("1");pourpage,#context counter(page).final().first();pourpage_count. Le point-virgule termine l'expression : un texte collé au jeton, comme(, reste du texte. Sansrepeat_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 etSTATIC_TEXT_FIELDreconnaît aussi{page}et{page_count}. Si le type de document a un champpageoupage_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.vueajoute 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électeurAdd field...est masqué pourfieldtype === "Blank").PrintFormatGenerator(frappe/utils/print_format_generator.py) exempte ces colonnes de la suppression des colonnes sans valeur (column_has_value) : une colonneBlankest 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.htmlaffiche 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 colonneBlank. - L'émetteur Typst (
frappe/utils/typst_emitter.py) renvoie une chaîne vide pour une colonne sansfieldnameou avecfieldtype == "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.
| Fonction | Paramètres | Résultat |
|---|---|---|
get_qr_code (whitelisted) | value | QR 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 :
| Format | Codage python-barcode | Options |
|---|---|---|
CODE128 | code128 | — |
CODE39 | code39 | add_checksum: False |
EAN13 | ean13 | — |
EAN8 | ean8 | — |
EAN14 | ean14 | — |
UPCA | upca | — |
ISBN13 | isbn13 | — |
ITF | itf | — |
GS1_128 | gs1_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(renvoieNone. Les parenthèses autour des identifiants d'application sont du texte d'étiquette, et python-barcode les encoderait.- Une
BarcodeErrorlevée parbarcode.get()oubuild()renvoieNone.
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>avecfullcodeéchappé, clé de contrôle comprise (policeDejaVu Sans Mono, monospace, taille 16) ; - le SVG porte
width,heightetviewBox.
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"].
| Cas | Valeur lue | Format |
|---|---|---|
Bloc ajouté dans le constructeur (custom) avec barcode_field | cstr(doc.get(barcode_field)) | barcode_format (CODE128 par défaut) et show_text |
Bloc ajouté dans le constructeur (custom) sans barcode_field | barcode_value dont les jetons {champ} et {champ_lien.champ_cible} sont remplacés par leur valeur brute | barcode_format (CODE128 par défaut) et show_text |
| Champ Barcode glissé depuis la liste des champs | doc.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 valeurNonedevient une chaîne vide ; - pour un champ lié,
resolve_linked_pathrenvoieNonequand l'utilisateur n'a pas accès au lien ou à la cible, quand le document lié est illisible ou quand la valeur estNone: 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.htmln'imprime rien sans_barcode_data_uri. Sinon, elle imprime une balise<img>dansdiv.print-barcode. Sa largeur estdf.width, ou35mmpour un QR code sans largeur. Pour un code linéaire sans largeur, l'image garde la taille du SVG. print_format_doc.cssappliquemax-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
widthetheight(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 estdf.width, ou35mmpour un QR code. Pour un code linéaire sans largeur, l'image n'a pas de largeur explicite.typst_blockersettypst_blockers_clientne signalent plus les codes-barres.- L'aperçu de l'éditeur (
FieldPreviewBarcode.vue) appelleget_barcodeavecfrappe.call(délai de 300 ms). Une valeur qui commence par<svgest affichée directement. Sans résultat, l'aperçu affiche « Valeur invalide pour {0} ».print_format.htmlne charge plusprint.bundle.jspour dessiner les codes-barres dans le navigateur. - Pour une valeur construite avec des jetons,
FieldPreviewBarcode.vueremplace côté client les jetons reconnus partext_field_paths(barcode_raw_value). Les champs liés sont lus aveclinked_targetetfrappe.db.get_value, après chargement du type de document lié (frappe.model.with_doctype). La fonctionraw_text()reproduit lestr()de Python : un nombre décimal entier (type numérique autre queInt) s'écrit avec une décimale (5.0), une valeurnulldonne une chaîne vide. Le même traitement s'applique à unbarcode_field. La zone Value deBarcodeRows.vuea pour suggestion de saisieText or {fieldname}. plutoprint_can_render()(frappe/utils/pdf_generator/pluto.py) renvoie toujoursFalsesi le HTML contientdata-barcode-value=. Seul un format HTML personnalisé qui dessine un code-barres dans le navigateur est concerné : la macroBarcode.htmlne 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é | Contenu | Remarques |
|---|---|---|
page | size, orientation et, pour une taille personnalisée, width et height | size : 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. |
background | image et opacity | opacity 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) convertitlayout["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 quePortraitouLandscapeest ignorée. Poursize == "Custom",widthetheightsont lus avecflt: la conversion produitpdf_page_size: "Custom",pdf_page_widthetpdf_page_heightseulement si les deux valeurs sont comprises entreMIN_PAGE_MM(10) etMAX_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 defrappe.meta.get_print_sizes(),Customcompris, et chaque libellé passe par__().set_page(): avecsize == "Custom",widthetheightvalent 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 pourCustom, etclamp_page_mm()ramène chaque valeur entre 10 et 5 000. StepperRow.vueaccepte 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 parparseInt.PrintFormatGenerator.format_page_settings()applique cette conversion àformat_datadu format. Une valeur deformat_dataillisible donne un dictionnaire vide.build_context()applique d'abord ces réglages sur Print Settings, puis les surcharges de l'impression (settings_override), puisapply_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 champspdf_page_sizeetpage_orientationproposent une valeur vide (« Default ») et démarrent vides. Une valeur vide supprime la clé depage_overrides. - La méthode whitelisted
frappe.utils.print_format_generator.get_page_size_mm(page=None)accepte un dictionnaire ou une chaîne JSONpage({"size", "orientation", "width", "height"}) et renvoie(largeur, hauteur)en mm. Elle passe parlayout_page_settingspuispage_size_mm: pourCustom, la largeur et la hauteur valentpdf_page_widthetpdf_page_height, ou 210 et 297 si elles sont vides. Les dimensions sont inversées enLandscape.PrintFormat.vuel'appelle aveclayout.pageet la rappelle quand celui-ci change.
Reprise de la taille personnalisée à la conversion
classic_converter.convert_classic_to_beta()copiepaper_widthetpaper_heightdu format danslayout["page"]quandpaper_sizevautCustom. La clépagen'est écrite que silayout_page_settingsen 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_sizesavec 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) quandcurrentPageSizevautcustomet 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_sizereprend les formats convertis (print_format_builder_beta = 1,classic_format_datarenseigné,paper_size = "Custom") et leur ajoutepage.size,widthetheightdansformat_dataavecadd_page_size(), sans mettre à jourmodified.repair_converted_print_formats.add_page_size()etrepair_layout()acceptent désormaispaper_widthetpaper_height, et le patchrepair_converted_print_formatsles lit aussi.
Image d'arrière-plan
PrintFormatGenerator.clean_background(background)normaliselayout["background"]. L'image doit correspondre en entier àBACKGROUND_IMAGE_URL: un chemin commençant par/, une adressehttp://ouhttps://, oudata:image/<type>;base64,<données>. Sinon, l'arrière-plan est ignoré (None). Le résultat contientimage,url(adresse encodée avecurllib.parse.quote, sauf pourdata:) etopacity(entier borné entre 0 et 100, 100 si vide).print_format.cssajoute, silayout.backgroundexiste,--pfb-cell-bg: transparentpour le corps du document et rendhtmletbodytransparents avec Chromium. Hors Chromium, un pseudo-élémentbody::beforeporte l'image avec l'opacité.print_format_doc.cssutilisevar(--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 avecpypdf(merge_page(..., over=False)). Quand un arrière-plan existe, l'optionpasswordn'est pas transmise à Chromium : le PDF final est chiffré après la fusion. - Pour Typst,
TypstEmitter._page_background()ajoutebackground:à#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.throws'arrête avec le titre « Typst renderer unavailable » (fr : « Moteur de rendu Typst indisponible »). typst_blockers(frappe/utils/typst_emitter.py) ettypst_blockers_client(print_format_builder/utils.js) ajoutent le blocage « Background image loaded from a web address » quandbackground.imagecommence parhttp://,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()litpaper_size,paper_widthetpaper_heightavecfrappe.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-widthoupage-height.- Le dictionnaire
RECEIPT_WIDTHSassocieReceipt 80 mmà80mmetReceipt 58 mmà58mm. Pour un reçu, les options reçoivent cette largeur enpage-width,297mmenpage-heightetfit-heightàTrue. - Si
paper_sizevautCustomet quepaper_widthetpaper_heightsont renseignées, les options reçoiventpage-width: f"{width}mm"etpage-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 dansprepare(), aprèsfit_body_to_page()et uniquement lorsquefit-heightest actif : elle mesure la hauteur du contenu, puis fixepaperHeightà 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.makeet_makefrappe.core.doctype.communication.mixins.CommunicationEmailMixin.mail_attachmentsfrappe.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 :
| Fonction | Effet |
|---|---|
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 oufrappe.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 retourneNone, 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é retourneNone.frappe.core.doctype.communication.email.makeappellecheck_print_format_roles_by_name(print_format)quand un format est transmis.frappe.flow.utils.safe_exec._readable_attachmentappellecheck_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.FormMetaajoute à chaque format de__print_formatsune 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éfautroles.frappe.meta.get_print_formats(doctype)exclut ces formats. Quand le format par défaut du type est limité, le code@dokosqui retire Standard de la liste ne s'applique pas : Standard reste le repli. Le testTestDokosPrintFormatListDropsStandardvé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) ajoutename not in restrictedau filtre du champ « Format d'impression » et vide le format initial si le défaut est limité. bulk_operations.jsproposefrappe.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.