OHRI-2070 docs for reusable components

.github/pull_request_template.md

@@ -0,0 +1,12 @@
+## Summary
+<!-- Please describe what problems your PR addresses. -->
+
+## Screenshots / Video Recording
+<!-- Required if you are making UI changes. -->
+
+## Related Issue
+<!-- Paste the link to the Jira ticket here if one exists. -->
+<!-- https://issues.openmrs.org/browse/O3- -->
+
+## Other
+<!-- Anything not covered above -->

pages/docs/core-concepts/components.mdx

@@ -0,0 +1,170 @@
+# Components
+
+There may be situations where you might want to separate commonly-used form logic into separate reusable bits.
+In such cases, you can structure that logic as a component form. Components can therefore be thought of as reusable forms that carry domain-specific information.
+Imagine a situation where you're creating many forms for use in a Point of Care setting. You might find that multiple forms might need to
+have sections for collecting pre-clinic Review information. This pre-clinic Review information could include details such as:
+
+- Current HIV status
+- Whether a visit was scheduled or not
+- Reasons for a visit
+- Current visit type
+- Patient's insurance information
+
+Now imagine having to define all of these sections and their accompanying questions in each of your forms. Components are the perfect
+tool for such situations.
+
+## Creating Components
+
+To create a component, follow the same procedure of [creating a form](https://ohri-docs.globalhealthapp.net/docs/create-new-form) with the exception being at the point of saving.
+ 1. It is advisable to prefix the name of the component with `component_`. For example, if you're creating a component for pre-clinic review,
+ you could name it `component_pre-clinic-review`.
+ 2. From the dropdown of encounters, you MUST select the encounter type `Component` as shown below:
+
+![Save Component](/images/save_component.png)
+
+After saving, the component will be available in the list of forms and you can filter forms if you only want to view saved components.
+
+![View Components](/images/view_components.png)
+
+The resulting component json will be as shown below;
+
+```json copy
+{
+  "name": "component_pre-clinic-review",
+  "uuid": "xxxx",
+  "processor": "EncounterFormProcessor",
+  "pages": [
+    {
+      "label": "Pre-clinic Review",
+      "sections": [
+        {
+          "label": "Pre-clinic Review",
+          "questions": [
+            {
+              "label": "Current HIV status",
+              "id": "currentHivStatus",
+              "type": "obs",
+              "questionOptions": {
+                "rendering": "select",
+                "concept": "9e4d6436-4040-46a3-a0ae-6dbc0acfe593",
+                "answers": [
+                  {
+                    "concept": "a896f3a6-1350-11df-a1f1-0026b9348838",
+                    "label": "HIV positive"
+                  },
+                  {
+                    "concept": "a896d2cc-1350-11df-a1f1-0026b9348838",
+                    "label": "HIV negative"
+                  },
+                  {
+                    "concept": "a899b50a-1350-11df-a1f1-0026b9348838",
+                    "label": "Unknown"
+                  }
+                ]
+              },
+              "validators": []
+            },
+            {
+              "label": "Was the visit scheduled?",
+              "id": "wasVisitScheduled",
+              "type": "obs",
+              "questionOptions": {
+                "rendering": "select",
+                "concept": "a89c4220-1350-11df-a1f1-0026b9348838",
+                "answers": [
+                  {
+                    "concept": "a899b35e-1350-11df-a1f1-0026b9348838",
+                    "label": "Yes"
+                  },
+                  {
+                    "concept": "a899b42e-1350-11df-a1f1-0026b9348838",
+                    "label": "No"
+                  }
+                ]
+              },
+              "validators": []
+            },
+            ....
+          ]
+        }
+      ]
+    }
+  ]
+}
+
+```
+
+## Referencing Components
+
+You can reference components that have already been saved in the system by adding it the `referencedForms` key to your json form.
+
+```json copy
+"referencedForms": [
+  {
+    "formName": "component_preclinic-review",
+    "alias": "pcr"
+  },
+  {
+    "formName": "component_art",
+    "alias": "art"
+  }
+]
+```
+
+### Available visual options
+
+- `form` : The alias of the referenced component form as defined in the `referencedForms` key
+- `page` : The page label of the referenced component form
+- `section` : The section label of the referenced component form to be displayed
+- `excludeQuestions` : An array of question id(s) to be excluded from the referenced section of component form
+
+
+### Example
+Below is the complete json form with 2 components referenced;
+
+```json copy
+{
+  "name": "ART Enrollment Form",
+  "uuid": "xxxx",
+  "encounterType": "xxxx",
+  "processor": "EncounterFormProcessor",
+  "referencedForms": [
+    {
+      "formName": "component_preclinic-review",
+      "alias": "pcr"
+    },
+    {
+      "formName": "component_art",
+      "alias": "art"
+    }
+  ],
+  "pages": [
+    {
+      "label": "Pre-Clinic Review",
+      "sections": [
+        {
+          "reference": {
+            "form": "pcr",
+            "page": "Pre-clinic Review",
+            "section": "Pre-clinic Review"
+          }
+        }
+      ]
+    },
+    {
+      "label": "ART History",
+      "sections": [
+        {
+          "reference": {
+            "form": "art",
+            "page": "ART ",
+            "section": "ART History",
+            "excludeQuestions": ["currentArtRegimen"]
+          }
+        }
+      ]
+    }
+  ]
+}
+```

pages/docs/core-concepts/pages.mdx

@@ -152,8 +152,8 @@ A page is a collection of related sections. A typical page definition consists o
 
 Here's how this page definition gets rendered:
 
-![Single-page form layout](/single-page-layout.png)
+![Single-page form layout](/images/single-page-layout.png)
 
 In practice, your form will likely have more than one page. You can cycle through the pages by infinitely scrolling or selecting the desired page from the left sidebar. Here's how a form with multiple pages would look like:
 
-![Multiple-page form layout](/multi-page-layout.png)
+![Multiple-page form layout](/images/multi-page-layout.png)

pages/docs/core-concepts/questions.mdx

@@ -87,7 +87,7 @@ Here's a reference of the various properties you can specify in a question defin
 
   - `answers`: An array of answers scoped to a question. An answer definition consists of a concept UUID or mapping and label pair. If no label is specified, the "display" value of the concept is used. Below is an example of answers to a `Current HIV status` question:
 
-    ![Answers](/answers.png)
+    ![Answers](/images/answers.png)
 
 - `questionInfo`: A property that recieves a string containing additional information regarding the field. When hovered over, it displays a tooltip containing the information passed.
 
@@ -97,7 +97,7 @@ Here's a reference of the various properties you can specify in a question defin
   }
   ```
 
-  ![Tooltip](/tooltip.png)
+  ![Tooltip](/images/tooltip.png)
 
 - `isHidden`: A boolean value that determines field visibility. In most cases, this value is driven by hide expressions.
 

pages/docs/create-new-form.mdx

@@ -14,7 +14,7 @@ The React Form Engine (RFE) form builder platform simplifies and partially autom
 
 ## What is the RFE form builder?
 
-The RFE form builder is found at the following addresses: 
+The RFE form builder is found at the following addresses:
 
 - OHRI: https://ohri-dev.globalhealthapp.net/openmrs/spa/form-builder
 - Reference Application: https://dev3.openmrs.org/openmrs/spa/form-builder
@@ -29,63 +29,63 @@ Requirements:
 
 - Make sure the Google Chrome browse is installed. Any other browser can also be used.
 
-![Form builder URL in address bar](/form-builder-url.png)
+![Form builder URL in address bar](/images/form-builder-url.png)
 
 In the address bar, enter the form builder URL: OHRI https://ohri-dev.globalhealthapp.net/openmrs/spa/login or RefApp https://dev3.openmrs.org/openmrs/spa/form-builder
 
-![Form builder URL](/form-builder-url.png)
+![Form builder URL](/images/form-builder-url.png)
 
 The main login form will open:
 
-![Login page](/login-page.png)
+![Login page](/images/login-page.png)
 
 After the login form is loaded, enter all the required details in the inputs:
 
 - **OpenMRS server URL**: This is the OpenMRS backend server installation where your concepts are stored.
 - **Username**: Use the default i.e. `admin`
 - **Password**: Use the default i.e. `Admin123`
 
-![Login credentials](/login-credentials.png)
+![Login credentials](/images/login-credentials.png)
 
 With the correct details entered above, the platform will log you in. You will land on the dashboard illustrated below:
 
-![Forms dashboard](/forms-dashboard.png)
+![Forms dashboard](/images/forms-dashboard.png)
 
 Now, click on `Create New Form` in the top left corner to create a new Form schema.
 
-![Create new form button](/create-new-form-button.png)
+![Create new form button](/images/create-new-form-button.png)
 
 Clicking the button will land you in the interface shown below. Note the  `preveiw` and the `Interactive Builder` tabs.
 
-![Create new form](/create_new_form.png)
+![Create new form](/images/create_new_form.png)
 
 Click on the `Interactive Builder` tab to open the builder page shown below:
 
-![Interactive Builder](/interactive_builder.png)
+![Interactive Builder](/images/interactive_builder.png)
 
 Click on the `Start building` text link. and a popup window asking for the form details will show as below:
 
-![Form name](/form_name.png)
+![Form name](/images/form_name.png)
 
 Click on the `add page` text link below to add a page to your form
 
-![Add page](/add_page.png)
+![Add page](/images/add_page.png)
 
 Add the page name in the pop up text box.
 
-![Page](/page_name.png)
+![Page](/images/page_name.png)
 
 Click on the `Save` button to successfully save the page and proceed.
 
-![Save page](/save_page.png)
+![Save page](/images/save_page.png)
 
 Next, click on the `Add section`  text link to add a section to your form.
 
-![Create section](/create_section.png)
+![Create section](/images/create_section.png)
 
 Click `save` to save the section added to form.
 
-![Save section](/save_section.png)
+![Save section](/images/save_section.png)
 
 Click on `Add question` text link to add a question to your form. A question has several metadata which you must add on the popup form entry. These include:
 - `Label`
@@ -96,24 +96,24 @@ Click on `Add question` text link to add a question to your form. A question has
 - `Mappings`: Auto generate from concept selected
 
 
-![Question](/question.png)
+![Question](/images/question.png)
 
 Click `Save` to save the question
 
-![Save question](/save_question.png)
+![Save question](/images/save_question.png)
 
 Click on `Preview Form` tab to view how the form will look like when rendered.
 
-![Preview form](/preview_form.png)
+![Preview form](/images/preview_form.png)
 
 Click on the `Save` to save your final form. A popup form entry will appear to allow you enter details that include:
 - `Form name`
 - `Version`
 - `Encounter Type`
 - `Description`
 
-![Save form](/save_form.png)
+![Save form](/images/save_form.png)
 
 Finally, the form is ready for adding to the backend for rendering.
 
-![Preview form](/preview_form.png)
+![Preview form](/images/preview_form.png)

pages/docs/developer-guide/contributing-guide.mdx

@@ -8,5 +8,5 @@ import { Callout } from 'nextra-theme-docs'
 
 ## Dependencies
 
-Requires [Node.js v14](https://nodejs.org/download/release/v14.21.3/) or higher.
+Requires Node.js v18 or higher.