Forms section migration and consolidation (#1696)

* Forms section * move uhc and others * Update content/en/building/cht-forms/_index.md Co-authored-by: mrjones <[email protected]> * Review feedback * Update content/en/building/cht-forms/_index.md Co-authored-by: mrjones <[email protected]> * cht-forms to forms * Fix 404s * Fix grep results * Configuring forms to forms --------- Co-authored-by: mrjones <[email protected]>
medic · Dec 2, 2024 · 070d1af · 070d1af
1 parent af66e9d
commit 070d1af
Show file tree

Hide file tree

Showing 51 changed files with 116 additions and 125 deletions.
diff --git a/content/en/building/concepts/care-guides.md b/content/en/building/concepts/care-guides.md
@@ -5,7 +5,7 @@ description: >
   Taking health workers through care protocols and providing decision support
 keywords: care-guides
 relatedContent: >
-  building/concepts/forms
+  building/forms
   building/tasks/#care-guides
   building/contact-summary/contact-summary-templated/#care-guides
 aliases:

diff --git a/content/en/building/contact-management/contacts.md b/content/en/building/contact-management/contacts.md
@@ -6,7 +6,7 @@ description: >
   Contacts and users overview
 keywords: hierarchy contacts care-guides
 relatedContent: >
-  building/reference/forms/contact
+  building/forms/contact
   building/contact-summary/contact-summary-templated
   building/contact-management/moving-contacts
   building/contact-management/contact-and-users-1

diff --git a/content/en/building/contact-summary/contact-summary-templated.md b/content/en/building/contact-summary/contact-summary-templated.md
@@ -5,7 +5,7 @@ weight: 2
 description: >
   Customizing the fields, cards, and actions on profile pages
 relatedContent: >
-  building/guides/forms/form-inputs
+  building/forms/configuring/form-inputs
 relevantLinks: >
   docs/building/features/contacts
   docs/building/concepts/hierarchies
@@ -87,7 +87,7 @@ Each condition card is defined as a card object in the `cards` array of `contact
 
 ## Care Guides
 
-Each care guide accessible from a contact profile is defined as an [App Form]({{< ref "building/reference/forms/app" >}}). Context information can be provided to forms via the `context` object of `contact-summary.templated.js`.
+Each care guide accessible from a contact profile is defined as an [App Form]({{< ref "building/forms/app" >}}). Context information can be provided to forms via the `context` object of `contact-summary.templated.js`.
 
 To show an App Form on a contact's profile, the form's `expression` field in its properties file must evaluate to true for that contact. The context information from the profile is accessible as the variable `summary`.
 

diff --git a/content/en/building/examples/anc.md b/content/en/building/examples/anc.md
@@ -6,7 +6,7 @@ description: >
   Reference application for maternal and newborn care for CHW's using a mobile app
 relatedContent: >
   building/concepts
-  building/reference/forms/app
+  building/forms/app
   building/tasks/tasks-js
 aliases:
    - /apps/examples/anc
@@ -37,7 +37,7 @@ Once a [hierarchy]({{< relref "building/workflows/hierarchy" >}}) of people and
 
 {{< figure src="forms-hierarchy.png" link="forms-hierarchy.png" class="right col-12 col-lg-12" >}}
 
-{{< see-also page="building/reference/forms/app" title="Controlling form properties" >}}
+{{< see-also page="building/forms/app" title="Controlling form properties" >}}
 
 ## Workflows
 

diff --git a/content/en/building/examples/covid-rdt-reference-app.md b/content/en/building/examples/covid-rdt-reference-app.md
@@ -5,9 +5,9 @@ weight:
 description: >
  CHT example application that uses a third party app to capture the result of a Rapid Diagnostic Test.
 relatedContent: >
-  building/reference/forms/app/#android-app-launcher
-  building/reference/forms/app/#cht-xform-widgets
-  building/reference/forms/app/#parse-timestamp-to-date
+  building/forms/app/#android-app-launcher
+  building/forms/app/#cht-xform-widgets
+  building/forms/app/#parse-timestamp-to-date
 aliases:
    - /apps/examples/covid-rdt-reference-app
 ---
@@ -41,7 +41,7 @@ For more information on these features, see the ["Related Content"](#related-con
 
 Additional requirements for this application beyond CHT 3.13, include [CHT Android 0.10.0](https://github.com/medic/cht-android) or later and Dimagi's [RD-Toolkit 0.9.8](https://github.com/dimagi/rd-toolkit/) or later. 
 
-While this application calls the RD-Toolkit, the integration features in the CHT Core and CHT Android are generic.  This means you could use a different RDT Android application if you prefer. Beyond the scope of RDTs, you could use this integration feature to launch any other Android app to perform an action and save the result in the CHT. To read more about this feature, see the [Android App Launcher section in the Forms reference documentation]({{< ref "building/reference/forms/app#android-app-launcher" >}}). 
+While this application calls the RD-Toolkit, the integration features in the CHT Core and CHT Android are generic.  This means you could use a different RDT Android application if you prefer. Beyond the scope of RDTs, you could use this integration feature to launch any other Android app to perform an action and save the result in the CHT. To read more about this feature, see the [Android App Launcher section in the Forms reference documentation]({{< ref "building/forms/app#android-app-launcher" >}}). 
 
 ## Workflow
 
@@ -165,7 +165,7 @@ These are the files in the COVID-19 app where you'll want to focus your customiz
 
 The `forms/app/covid19_rdt_provision` and `forms/app/covid19_rdt_capture` forms (`xlsx`, `xml` and `properties.json`) represent the provision and capture portions of the forms.  The tasks that get created are defined in `tasks.js`.  Not shown are standard contact definitions in `forms/contact/*` as well as supporting configurations for icons and other CHT application settings.  
 
-To read more about how these files all work together, see [app forms]({{< ref "building/reference/forms/app" >}}), [contact forms]({{< ref "building/reference/forms/contact" >}}), and [task]({{< ref "building/tasks/tasks-js" >}}) reference documentation
+To read more about how these files all work together, see [app forms]({{< ref "building/forms/app" >}}), [contact forms]({{< ref "building/forms/contact" >}}), and [task]({{< ref "building/tasks/tasks-js" >}}) reference documentation
 
 ## Example form submission
 

diff --git a/content/en/building/examples/direct-to-client.md b/content/en/building/examples/direct-to-client.md
@@ -6,7 +6,7 @@ description: >
   Reference for Direct-to-client, two-way texting workflows with CHT and RapidPro
 relatedContent: >
   building/concepts
-  building/reference/forms/app
+  building/forms/app
   building/tasks/tasks-js
 aliases:
    - /apps/examples/direct-to-client

diff --git a/content/en/building/examples/supervisor-reference-app.md b/content/en/building/examples/supervisor-reference-app.md
@@ -7,7 +7,7 @@ description: >
 relatedContent: >
   building/concepts
   building/features/supervision
-  building/reference/forms/app
+  building/forms/app
   building/tasks/tasks-js
 aliases:
    - /apps/examples/supervisor-reference-app

diff --git a/content/en/building/features/messaging/_index.md b/content/en/building/features/messaging/_index.md
@@ -6,7 +6,7 @@ description: >
 relatedContent: >
   building/reference/app-settings/schedules
   building/guides/messaging
-  building/guides/forms/app-form-sms
+  building/forms/configuring/app-form-sms
 aliases:
    - /apps/features/messaging/
 ---

diff --git a/content/en/building/features/reports/_index.md b/content/en/building/features/reports/_index.md
@@ -6,7 +6,7 @@ description: >
 relatedContent: >
   building/reference/app-settings/patient_reports
   building/guides/data/invalid-reports
-  building/guides/forms/report-titles
+  building/forms/configuring/report-titles
 aliases:
    - /apps/features/reports/
 ---
@@ -92,7 +92,7 @@ The buttons at the bottom are configurable. The ones you see will depend on your
 ## Defining Forms
 
 The reports shown in your app are the completed and submitted *forms*. These forms must be defined and included with the application. There are two types of form definitions for reports:
-- **App forms**: actions within the app, such as a completed task, or an action on a contact's profile or reports tab. App forms are defined as [XForms]({{< ref "building/reference/forms/app" >}}).
+- **App forms**: actions within the app, such as a completed task, or an action on a contact's profile or reports tab. App forms are defined as [XForms]({{< ref "building/forms/app" >}}).
 - **JSON forms**: data coming from external channels such as SMS, or via interoperability with other tools. JSON forms are defined using a [JavaScript Object Notation schema]({{< ref "building/reference/app-settings/forms" >}}). 
 
 
diff --git a/content/en/building/features/uhc-mode/_index.md b/content/en/building/features/uhc-mode/_index.md
@@ -5,7 +5,7 @@ weight: 11
 description: >
   Supporting equitable and timely care to families to increase Universal Health Coverage (UHC)
 relatedContent: >
-  building/guides/forms/uhc-mode
+  building/forms/configuring/uhc-mode
   building/reference/app-settings/user-roles
   building/reference/app-settings/user-permissions
 aliases:
@@ -28,4 +28,4 @@ The _UHC Mode_ in the CHT allows health workers to see when a household within t
 When using the _UHC Mode_, the households in the contact list can be sorted by when they were last visited. The days since the last visit is also shown in the app, along with the number of visits made to a household in a month period. 
 
 ## Configurability
-The last visited date is calculated based on the number of days since an action was taken for that household, and the number of visits reflects the actions taken for that household in the current month. What constitutes as an action for a household, along with the start date for the reporting period, [are configurable]({{< relref "building/guides/forms/uhc-mode" >}}) to CHT app developers.
+The last visited date is calculated based on the number of days since an action was taken for that household, and the number of visits reflects the actions taken for that household in the current month. What constitutes as an action for a household, along with the start date for the reporting period, [are configurable]({{< relref "building/forms/configuring/uhc-mode" >}}) to CHT app developers.
diff --git a/content/en/building/concepts/forms.md → content/en/building/forms/_index.md b/content/en/building/concepts/forms.md → content/en/building/forms/_index.md
@@ -1,16 +1,12 @@
 ---
-title: "Forms"
-linkTitle: "Forms"
-weight: 3
+title: Forms
+linkTitle: Forms
+weight: 7
 description: >
   Building block for all CHT apps
-keywords: app-forms contact-forms collect-forms json-forms
-relatedContent: >
-  building/concepts/care-guides
-  building/guides/forms
-  building/reference/forms
-  building/reference/app-settings/forms
 aliases:
+   - /building/reference/forms
+   - /building/concepts/forms
    - /apps/concepts/forms
 ---
 
@@ -19,9 +15,8 @@ Forms are a building block of all CHT apps. They are used when creating or editi
 When a completed form is submitted, it is treated as a Report in the app. All reports can be viewed in the [Reports tab]({{< ref "building/features/reports" >}}) by those with the proper access within the [hierarchy]({{< ref "building/workflows/hierarchy" >}}).
 
 There are four different types of forms:
-- [**Contact Forms**]({{< ref "building/reference/forms/contact" >}}): used to create and edit contacts. Defined as CHT-enhanced XForms.
-- [**App Forms**]({{< ref "building/reference/forms/app" >}}): serve as actions within the app, such as a task or an action. Defined as CHT-enhanced XForms.
-- [**Collect Forms**]({{< ref "building/reference/forms/collect" >}}): used to render forms in Medic Collect. Defined as ODK XForms and need a corresponding JSON form to receive data in CHT.
-- [**JSON Forms**]({{< ref "building/reference/app-settings/forms" >}}): used for data coming from external channels such as SMS, or via interoperability with other tools. Defined according to a JavaScript Object Notation schema.
+- [**Contact Forms**]({{< ref "building/forms/contact" >}}): used to create and edit contacts. Defined as CHT-enhanced XForms.
+- [**App Forms**]({{< ref "building/forms/app" >}}): serve as actions within the app, such as a task or an action. Defined as CHT-enhanced XForms.
+- [**Collect Forms**]({{< ref "building/forms/collect" >}}): used to render forms in Medic Collect. Defined as ODK XForms and need a corresponding JSON form to receive data in CHT.
 
 Forms that can be completed in the app are built using a CHT-enhanced version of [ODK XForms](https://opendatakit.github.io/xforms-spec/) notation -- a XML definition of the structure and format for a set of questions. Since writing raw XML can be tedious, the [XLSForm standard](http://xlsform.org/) is commonly used to define forms. The [cht-conf](https://github.com/medic/cht-conf) command line tool can be used to convert to the XForm format and include the form in a CHT application. The instructions on this site assume some knowledge of XLSForm.
diff --git a/content/en/building/reference/forms/app.md → content/en/building/forms/app.md b/content/en/building/reference/forms/app.md → content/en/building/forms/app.md
@@ -1,16 +1,17 @@
 ---
 title: "app"
 linkTitle: "app"
-weight: 5
+weight: 1
 description: >
   **App Forms**: Used to complete reports, tasks, and actions in the app
 relevantLinks: >
   docs/building/concepts/workflows
   docs/design/best-practices
 relatedContent: >
-  building/guides/forms/form-inputs
+  building/forms/configuring/form-inputs
 keywords: workflows app-forms
 aliases:
+   - /building/reference/forms/app
    - /apps/reference/forms/app
 ---
 
@@ -21,7 +22,7 @@ App forms are defined by the following files:
 - A XML form definition using a CHT-enhanced ODK XForm format
 - A XLSForm form definition, easier to write and converts to the XForm (optional)
 - Meta information in the `{form_name}.properties.json` file (optional)
-- Media files in the `{form_name}-media` directory (optional). How to [include multimedia files]( {{< ref "building/guides/forms/multimedia" >}} ).
+- Media files in the `{form_name}-media` directory (optional). How to [include multimedia files]( {{< ref "building/forms/configuring/multimedia" >}} ).
 
 ## XForm
 
@@ -91,7 +92,7 @@ Some XForm widgets have been added or modified for use in CHT applications. The
 ### Bikram Sambat Datepicker
 
 Calendar widget using Bikram Sambat calendar, which is used by default for appropriate languages. The CHT documentation includes a [conversion tool](https://docs.communityhealthtoolkit.org/bikram-sambat/) to check the conversion between Gregorian and Bikram Sambat dates.
-{{< see-also page="building/reference/forms/app" title="`to-bikram-sambat` XPath function" anchor="to-bikram-sambat" >}}
+{{< see-also page="building/forms/app" title="`to-bikram-sambat` XPath function" anchor="to-bikram-sambat" >}}
 
 ### Countdown Timer
 
@@ -109,7 +110,7 @@ The `trigger` implementation of the countdown timer is only supported for CHT ve
 
 
 ### Contact Selector
-A dropdown field to search and select a person or place, and save their UUID in the report. The contact's data will also be mapped to fields with matching names within the containing group. If the contact selector's appearance includes `bind-id-only`, the associated data fields are not mapped. See [the form input guide]({{< ref "building/guides/forms/form-inputs#contact-selector" >}}) for an example.
+A dropdown field to search and select a person or place, and save their UUID in the report. The contact's data will also be mapped to fields with matching names within the containing group. If the contact selector's appearance includes `bind-id-only`, the associated data fields are not mapped. See [the form input guide]({{< ref "building/forms/configuring/form-inputs#contact-selector" >}}) for an example.
 
 ### Rapid Diagnostic Test Capture
 Take a picture of a Rapid Diagnotistic Test and save it with the report. Works with [rdt-capture Android application](https://github.com/medic/rdt-capture/). To use create a string field with appearance `mrdt-verify`.
@@ -312,7 +313,7 @@ _Added in 3.14.0._
 
 This function converts a `date` to a `string` containing the value of the date formatted according to the [Bikram Sambat](https://en.wikipedia.org/wiki/Vikram_Samvat) calendar.
 
-See also: [Bikram Sambat Datepicker]({{< ref "building/reference/forms/app#cht-xform-widgets" >}})
+See also: [Bikram Sambat Datepicker]({{< ref "building/forms/app#cht-xform-widgets" >}})
 
 ### `z-score`
 
@@ -349,17 +350,17 @@ The data used by this function needs to be added to CouchDB. The example below s
 
 ## Input data
 
-`app` forms have access to a variety of [input data]({{< ref "building/guides/forms/form-inputs#app-forms" >}}) depending on the source of the form.
+`app` forms have access to a variety of [input data]({{< ref "building/forms/configuring/form-inputs#app-forms" >}}) depending on the source of the form.
 
 ## CHT Special Fields
 
 Some fields in app forms control specific aspects of CHT Apps, either to bring data into forms or for a feature outside of the form.
 
 ### Quintiles
-The `NationalQuintile` and `UrbanQuintile` fields on a form will be assigned to all people belonging to the place. This is helpful when household surveys have quintile information which could be used to target health services for individuals. {{< see-also prefix="Read More" page="building/guides/forms/wealth-quintiles" >}} 
+The `NationalQuintile` and `UrbanQuintile` fields on a form will be assigned to all people belonging to the place. This is helpful when household surveys have quintile information which could be used to target health services for individuals. {{< see-also prefix="Read More" page="building/forms/configuring/wealth-quintiles" >}} 
 
 ### UHC Mode
-When the `visited_contact_uuid` field is set at the top level of a form, this form is counted as a household visit in [UHC Mode]({{< relref "building/features/uhc-mode" >}}). This field must be a `calculate` field with the place UUID of the visited contact. You may run into performance issues if you configure this to look at forms submitted very frequently. {{< see-also prefix="Read More" page="building/guides/forms/uhc-mode" >}} 
+When the `visited_contact_uuid` field is set at the top level of a form, this form is counted as a household visit in [UHC Mode]({{< relref "building/features/uhc-mode" >}}). This field must be a `calculate` field with the place UUID of the visited contact. You may run into performance issues if you configure this to look at forms submitted very frequently. {{< see-also prefix="Read More" page="building/forms/configuring/uhc-mode" >}} 
 
 ## Uploading Binary Attachments
 

diff --git a/...nt/en/building/reference/forms/collect.md → content/en/building/forms/collect.md b/...nt/en/building/reference/forms/collect.md → content/en/building/forms/collect.md
@@ -1,11 +1,12 @@
 ---
 title: "collect"
 linkTitle: "collect"
-weight: 5
+weight: 3
 description: >
   **Collect Forms**: Served to the Medic Collect application
 keywords: collect-forms collect
 aliases:
+   - /building/reference/forms/collect
    - /apps/reference/forms/collect
 ---
 

diff --git a/content/en/building/forms/configuring/_index.md b/content/en/building/forms/configuring/_index.md
@@ -0,0 +1,10 @@
+---
+title: Configuring
+linkTitle: Configuring
+weight: 4
+description: >
+ Configuring and using forms in the CHT
+aliases:
+   - /building/guides/forms/
+   - /apps/guides/forms/
+---
diff --git a/.../building/guides/forms/additional-docs.md → ...ding/forms/configuring/additional-docs.md b/.../building/guides/forms/additional-docs.md → ...ding/forms/configuring/additional-docs.md
@@ -5,11 +5,11 @@ weight:
 description: >
   Integration for sending and receiving SMS
 relatedContent: >
-  building/guides/forms/app-form-sms
-  building/guides/forms/multimedia
-  building/reference/forms/contact
-
+  building/forms/configuring/app-form-sms
+  building/forms/configuring/multimedia
+  building/forms/contact
 aliases:
+   - /building/guides/forms/additional-docs
    - /apps/guides/forms/additional-docs
 ---
 In version 2.13.0 and higher, you can configure app forms to generate additional docs upon submission. You can create one or more docs using variations on the configuration described below. One case where this can be used is to register a newborn from a delivery report, as shown below. First, here is an overview of what you can do and how the configuration should look in XML:

diff --git a/...s/additional-docs/linked_docs_xlsform.png → ...g/additional-docs/linked_docs_xlsform.png b/...s/additional-docs/linked_docs_xlsform.png → ...g/additional-docs/linked_docs_xlsform.png
diff --git a/...additional-docs/repeated_docs_xlsform.png → ...additional-docs/repeated_docs_xlsform.png b/...additional-docs/repeated_docs_xlsform.png → ...additional-docs/repeated_docs_xlsform.png
diff --git a/.../en/building/guides/forms/app-form-sms.md → ...uilding/forms/configuring/app-form-sms.md b/.../en/building/guides/forms/app-form-sms.md → ...uilding/forms/configuring/app-form-sms.md
@@ -5,10 +5,11 @@ weight:
 description: >
   Trigger calls and SMS from within the form, or send an SMS once submitted.
 relatedContent: >
-  building/guides/forms/additional-docs
-  building/guides/forms/multimedia
-  building/reference/forms/contact
+  building/forms/configuring/additional-docs
+  building/forms/configuring/multimedia
+  building/forms/contact
 aliases:
+   - /building/guides/forms/app-form-sms
    - /apps/guides/forms/app-form-sms
 ---
 

diff --git a/...rms/contact/place-contact-form-survey.png → ...ing/contact/place-contact-form-survey.png b/...rms/contact/place-contact-form-survey.png → ...ing/contact/place-contact-form-survey.png
diff --git a/...t/en/building/guides/forms/form-inputs.md → ...building/forms/configuring/form-inputs.md b/...t/en/building/guides/forms/form-inputs.md → ...building/forms/configuring/form-inputs.md
@@ -5,11 +5,11 @@ weight:
 description: >
   Data accessible from within CHT forms
 relatedContent: >
-  building/reference/forms
+  building/forms
   building/contact-summary/contact-summary-templated
-  building/tasks/managing-tasks/pass-data-to-form
-  
+  building/tasks/managing-tasks/pass-data-to-form  
 aliases:
+   - /building/guides/forms/form-inputs
    - /apps/guides/forms/form-inputs
 ---
 
@@ -38,7 +38,7 @@ Forms for adding contacts have access to a small group of fields contained in a
 
 #### Edit forms
 
-Forms for editing contacts have access to _all the contact's current data_. These fields are contained in a top-level group that is named for the contact_type id of the contact being added (so `person`, `clinic`, etc). If fields in the top-level group are [edited by the form]({{< ref "building/reference/forms/contact" >}}), these changes will be saved to the contact's doc.
+Forms for editing contacts have access to _all the contact's current data_. These fields are contained in a top-level group that is named for the contact_type id of the contact being added (so `person`, `clinic`, etc). If fields in the top-level group are [edited by the form]({{< ref "building/forms/contact" >}}), these changes will be saved to the contact's doc.
 
 In addition, the contact's `parent` data is hydrated so that the form has access to the data stored on the parent contact doc in the `parent` group.
 

diff --git a/.../en/building/guides/forms/google-drive.md → ...uilding/forms/configuring/google-drive.md b/.../en/building/guides/forms/google-drive.md → ...uilding/forms/configuring/google-drive.md
@@ -5,8 +5,9 @@ weight:
 description: >
   Using cht-conf to obtain form files stored in Google Drive
 relatedContent: >
-  building/guides/forms/
+  building/forms/configuring/
 aliases:
+   - /building/guides/forms/google-drive
    - /apps/guides/forms/google-drive
 ---