feat(medic/cht-core#10509): add documentation for contact form attachment uploads

[cliftonmcintosh]

Description

This adds documentation for contact form attachment uploads. This goes with medic/cht-core#10570.

AI disclosure

Claude Code was used when generating this documentation. I gave Claude directions by showing it report documentation and code and examples in cht-core. I reviewed and edited the changes proposed by Claude.

Here are my directions to Claude

Note that Claude filled in the "Plan and implementation" section.

Contact attachment upload documentation

Goal

I want to add documentation about the ability to upload attachments in contact forms.

Similar documentation for "app" forms

There is some documentation for attachment uploads in content/en/building/forms/app.md, but it is pretty minimal. I want to include a small example code snippet in our documentation for contacts.

Samples

The "photo" element in ~/workspace/cht-core/config/default/forms/contact/person-create.xml is an example of using an Enketo upload widget to upload an attachment. You don't need to read the full file. It is very large. You can rely in the diff I have printed here.

Diff showing the "photo" element

+++ b/config/default/forms/contact/person-create.xml
@@ -919,6 +919,7 @@ DOB ISO: <output value=" /data/person/ephemeral_dob/dob_iso "/></value>
             <role_other/>
             <external_id/>
             <notes/>
+            <photo/>
             <user_for_contact>
               <create/>
             </user_for_contact>
@@ -1059,6 +1060,7 @@ DOB ISO: <output value=" /data/person/ephemeral_dob/dob_iso "/></value>
       <bind nodeset="/data/person/role_other" type="string" required="true()" relevant="selected(  /data/person/role ,'other')"/>
       <bind nodeset="/data/person/external_id" type="string"/>
       <bind nodeset="/data/person/notes" type="string"/>
+      <bind nodeset="/data/person/photo" type="binary"/>
       <bind nodeset="/data/person/user_for_contact/create" type="string" calculate=" /data/person/phone  != '' and (selected(  /data/person/role ,'chw') or selected(  /data/person/role ,'chw_supervisor'))"/>
       <bind nodeset="/data/person/meta/created_by" type="string" calculate="../../../inputs/user/name"/>
       <bind nodeset="/data/person/meta/created_by_person_uuid" type="string" calculate="../../../inputs/user/contact_id"/>
@@ -1156,6 +1158,10 @@ DOB ISO: <output value=" /data/person/ephemeral_dob/dob_iso "/></value>
       <input ref="/data/person/notes" appearance="multiline">
         <label ref="jr:itext('/data/person/notes:label')"/>
       </input>
+      <upload ref="/data/person/photo" mediatype="image/*">
+        <label>Photo</label>
+        <hint>Take a photo or select from gallery</hint>
+      </upload>
       <group ref="/data/person/user_for_contact"/>
       <group appearance="hidden" ref="/data/person/meta"/>
     </group>

Your job

1. Read this document
2. Read the "app" forms documentation.
3. Read the sample in ~/workspace/cht-core/config/default/forms/contact/person-create.xml
4. Read the code at ~/workspace/cht-core/webapp/src/ts/services/contact-save.service.ts for extra information
5. Read Enketo documentation about uploads.
6. Decide if you need to read more of the code in ~/workspace/cht-core to understand how uploading attachments works.
7. Ask me questions if you need clarification.
8. Propose documentation for contacts. Edit the existing documentation at content/en/building/forms/contact.md with your proposed changes.
9. Let me know when you are done so I can read it over.

Plan and implementation

Sources reviewed

• content/en/building/forms/app.md — existing "Uploading Binary Attachments" section (brief; no XLSForm example)
• config/default/forms/contact/person-create.xml diff — shows the photo field using <upload ref="..." mediatype="image/*"> and <bind ... type="binary"/>
• webapp/src/ts/services/contact-save.service.ts — confirms files from Enketo's FileManager are attached with a user-file- prefix; file names are sanitized; binary fields in XML are also processed

Approach

Added a new ## Uploading Binary Attachments section to content/en/building/forms/contact.md, placed just before the existing ## Properties section (mirroring placement in app.md).

The section:

1. Explains that binary data is saved as an attachment on the contact document, and images are displayed on the contact profile
2. Describes the XLSForm types to use (image for photos, file for generic files, or instance::type: binary for any field)
3. Includes a concrete XLSForm table example based on the photo field in person-create.xml
4. Includes the Android READ_EXTERNAL_STORAGE permission note (copied from app.md, as it applies equally to contact forms)

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

[cliftonmcintosh]

This note is copied from the report forms documentation. Is this true?

[dianabarsan]

yes.

[cliftonmcintosh]

@dianabarsan

Would you be willing to review this? Is there someone else I should ask?

[dianabarsan]

5.1.0 . please use full semver.

[cliftonmcintosh]

Yes! Updated

[dianabarsan]

yes.

[dianabarsan]

sweet!