DocAssemble Development

LegalTech

Docassemble PDF Fill Problems: Fields, Checkboxes and Signatures That Won’t Populate

Short answer: When a Docassemble pdf template file doesn’t fill, the cause is nearly always a field name that doesn’t exactly match the PDF, a signature field that shares its name with another field, a value passed in the wrong form, or a PDF that needs pdftk rather than the default pikepdf filler. Check field names first. Court and tribunal forms in the USA, UK and Australia are often supplied as fillable PDFs, so PDF filling is central to legal aid and court-form projects. This guide uses a symptom → cause → fix format, based on the official docassemble Documents docs and real GitHub issues. Note: the code and commands below are examples based on the official docassemble documentation. Test them on a staging server before using them in production. Quick diagnostic table Symptom Likely cause Fix A field stays empty Name doesn’t match the PDF exactly Get the exact names from Utilities and copy them Signature missing Not a “Digital Signature” field, or duplicate field names One uniquely named signature field per spot Same signature needed on several pages Fields share one name Give each field a different name, pass the same variable Uploaded photo or image doesn’t appear, or lands in the wrong box Image needs its own uniquely named “Digital Signature” field; older versions had a bug (#602) One “Digital Signature” field per image; upgrade to 1.4.24 or later ‘str’ object has no attribute ‘signature’ The variable is a string, not an object Make the parent an object (e.g. Individual) Checkboxes not ticked Value isn’t a true/false answer Pass a yes/no variable Users can still edit the output Default: output stays editable editable: False Odd rendering with some forms Filler library differences Try pdftk: True Why aren’t my PDF fields filling in Docassemble? Answer: The keys under fields must match the PDF’s field names exactly, including spaces and capitals. Many government forms have long or auto-generated names. Log in as a developer, open Utilities, and use “Get list of fields from PDF/DOCX template” to get the literal names, then copy them into your YAML. attachment: name: A filled-in form filename: filled-form pdf template file: sample-form.pdf fields: – Your Name: | ${ user } – Your Organization: | ${ user.organization } The docs say field names “must correspond exactly with the names of the fields in the PDF file” and recommend renaming fields in Adobe Acrobat Pro to concise, meaningful names when a form has many fields (Documents). Note that PDF values are passed with Mako (${ … }), not Jinja2. Template files are expected in your package’s data/templates folder. How do you map checkbox values correctly? Answer: Pass a yes/no variable to each checkbox field, as in the official example Apple Checkbox: ${ likes_apples }. Collect it with a yesno question or a yesno field. If a box still won’t tick, check the field’s name with the Utilities field list and test the PDF with pdftk: True. fields: – Apple Checkbox: | ${ likes_apples } – Orange Checkbox: | ${ likes_oranges } Source: the sample-form example in Documents. (Editor’s note: forms with unusual checkbox “on” values should be tested on the actual court form before publishing advice specific to them.) Why does a signature not appear in my PDF template? Answer: Docassemble inserts images into “Digital Signature” fields. Add a signature field in Acrobat, give it a unique name, and set it to ${ user.signature }. If two fields share a name, Docassemble can’t locate them, so the signature won’t appear. It trims whitespace and fits the image to the box. question: | Please sign your name below. signature: user.signature under: | ${ user } — attachment: name: Transfer of ownership filename: Transfer-of-Ownership pdf template file: Transfer-of-Ownership.pdf fields: – "signature": ${ user.signature } Users have reported signatures failing to fill in GitHub issue #434 and signature or image uploads not populating correctly in issue #602. The unique-name rule is in the Documents docs. How do you put the same signature on several pages? Answer: Create a separate “Digital Signature” field for each place, give each a different name, and pass the same variable to all of them. Copying one field across pages in Acrobat gives copies the same name, which stops Docassemble locating them. This is the documented fix for multi-page signatures. fields: – first signature: ${ user.signature } – second signature: ${ user.signature } – third signature: ${ user.signature } Related report: GitHub issue #613, same signature in a multi-page PDF template. Why doesn’t an uploaded image (not a signature) appear in my PDF? Answer: Docassemble fills images into a PDF the same way it fills signatures: through a “Digital Signature” field. In Adobe Acrobat Pro, add a “Digital Signature” field where the image should go, size it to the image, and give it a unique name. Then pass the uploaded file to it in fields. Docassemble trims whitespace and fits the image into the box. question: Insurance card – front fields: – Picture: card_front datatype: file — attachment: name: Medical form filename: medical_form pdf template file: medical_form.pdf fields: – "Signature1": ${ user.signature } – "CardFront": ${ card_front } The docs give the same steps “to add a signature or other image to a fillable PDF file” (Documents). In GitHub issue #602, a signature and an uploaded insurance-card image both landed in the last form field. The maintainer fixed it in version 1.4.24, and the reporter confirmed the fix. If you see this on an older server, upgrade. If the image must flow with text or change size with the content, a PDF form field is the wrong tool. Use a DOCX template instead: see how to resize images in DOCX templates (link live once article 1 is published). What does “‘str’ object has no attribute ‘signature’” mean? Answer: It means the variable before .signature is a plain string, not an object. For example, user was set as text rather than created as an Individual. Declare the object in an objects block before you ask

Docassemble PDF Fill Problems: Fields, Checkboxes and Signatures That Won’t Populate Read More »

Docassemble DOCX Template Errors: Jinja2, Dates, Images and Broken Formatting

Short answer: Most Docassemble DOCX template errors come from five things: Jinja2 tags that Word has split or mis-typed, conditionals and loops that don’t use the p or tr prefixes, dates printed without a format, images mixed with text in one tag, and variables that are undefined when the document is assembled. Each has a predictable fix, set out below. Docassemble assembles Word documents with a docx template file and the python-docx-template library, which uses a slightly modified Jinja2 syntax (docassemble docs: Documents). That makes it powerful, and also easy to break. This guide follows a symptom → cause → fix pattern for each problem. Note: the code and commands below are examples based on the official docassemble documentation. Test them on a staging server before using them in production. Quick diagnostic table Symptom Likely cause Fix Jinja2 syntax error on assembly Tag split by Word formatting, or Python syntax Jinja2 doesn’t allow Retype the tag in one go; use filters instead of Python built-ins Empty paragraphs or broken table rows {% if %} / {% for %} without p / tr prefix Use {%p … %} on its own line, {%tr … %} in its own row Date prints in an odd format or errors Raw date value, no format Call .format_date() Image missing or document error Image mixed with text inside {{ }} Put the image alone in its own tag; use .show(width=…) Fields come out blank Variable undefined, or skip undefined hiding it Define the variable first; use skip undefined with care TypeError: Argument ‘element’ has incorrect type (expected lxml.etree._Element, got NoneType) Small structural errors inside the .docx file Open the file in Word and save it again, or rebuild it from a fresh document & in template code turns into & Known issue with ampersands in Jinja2 expressions (closed on GitHub) Retest on your version; avoid & inside {% %} / {{ }} code Image too large or too small Image inserted without a width {{ my_image.show(width=”2in”) }} Included document loses formatting include_docx_template() not in {{p … }} form Use the p form on its own line Why does my DOCX template throw a Jinja2 error? Answer: A Jinja2 error usually means the tag itself is malformed. Word often splits a tag across formatting runs when you edit part of it, or autocorrect swaps quotes. Jinja2 also rejects some Python, such as referring to None or calling len(). Retype the tag cleanly and use Jinja2 filters instead of Python built-ins. Symptom: the interview stops at the attachment step with a template or syntax error. Cause: Docassemble’s docs note that Jinja2 “does not allow you to write every kind of Python expression” — for example, you can’t refer to None — and it encourages filters instead (Documents: Jinja2 filters). Fix: {# Instead of: {{ len(favorite_fruits) }} #} You have {{ favorite_fruits | length }} favorite fruits. {# Instead of: {% if result_of_api_call is None %} #} {% if none(result_of_api_call) %}N/A{% endif %} Both replacements come from the official documentation. If a tag still fails, delete it and type it again in one go without changing font or style halfway through. Why do conditionals and loops leave blank lines or break tables? Answer: Plain {% if %} and {% for %} tags stay inside the paragraph or table row they sit in, so you get empty paragraphs or broken rows. Put paragraph-level logic in {%p … %} tags on their own lines and table-row logic in {%tr … %} tags in their own rows. python-docx-template then removes those lines from the output. Fix — paragraph conditional: Hello, {{ user }}. {%p if user.age_in_years() > 30 %} You cannot be trusted! {%p endif %} Fix — table loop (two extra rows in the Word table, one for each tr tag): | Name | Age | | {%tr for child in children %} | | | {{ child }} | {{ child.age_in_years() }} | | {%tr endfor %} | | The docs explain that the tr prefix means “process the Jinja2 in this row, but don’t actually include this row in the assembled document” (Documents: tables). How do you format dates correctly in DOCX templates? Answer: Store dates with datatype: date so Docassemble gives you a DADateTime object, then format it in the template with .format_date(). Set a default format with the date format language setting if you need one house style. Users report “Bad date” or unexpected output when the stored value isn’t a real date. Symptom: the date prints as a raw value, in the wrong style, or as “Bad date” (reported in GitHub issue #756; see also #857, dates and template filters). Fix: question: When was the agreement signed? fields: – Date signed: signing_date datatype: date This agreement was signed on {{ signing_date.format_date("MMMM d, yyyy") }}. For UK and Australian documents, use a day-first pattern such as “d MMMM yyyy”. The format_date() function and the date format default are documented in Functions. How do you insert images and signatures into Word output? Answer: Put the image variable alone inside its own {{ }} tag, for example {{ user.signature }}, and control its size with .show(width=”2in”). Don’t concatenate an image with text in one tag. If the image looks cropped or squashed, check the line spacing of the paragraph it sits in. Signed: {{ user.signature.show(width="2in") }} The docs say image references “need to be by themselves inside of {{ }} brackets” and that paragraph spacing can affect how the image appears (Documents). Accessibility of signatures and other inserted images in DOCX output is discussed in GitHub issue #946. Why does include_docx_template corrupt formatting or cross-references? Answer: include_docx_template() must be called with the p form of Jinja2 markup, {{p include_docx_template(‘sub_document.docx’) }}, alone on its own line. Otherwise the included paragraphs don’t merge correctly. Cross-references, bookmarks and complex fields in the included file can still break, so test them. {{p include_docx_template(‘sub_document.docx’) }} The p-form requirement is in the Documents and Functions docs. Cross-reference corruption is reported in GitHub issue

Docassemble DOCX Template Errors: Jinja2, Dates, Images and Broken Formatting Read More »

en_USEnglish
Scroll to Top