Add a few explanatory comments.

hotosm · Mar 18, 2024 · 4af83e7 · 4af83e7
1 parent 75eb6c5
commit 4af83e7
Show file tree

Hide file tree

Showing 2 changed files with 20 additions and 1 deletion.
diff --git a/collect_app/src/main/AndroidManifest.xml b/collect_app/src/main/AndroidManifest.xml
@@ -123,6 +123,11 @@ the specific language governing permissions and limitations under the License.
             android:theme="@style/Theme.Collect.FormEntry"
             android:windowSoftInputMode="adjustResize"
             android:exported="true">
+            <!--
+              This intent-filter enables the launching of FormFillingActivity
+              on a specific form via in-browser links in the format
+              "odkcollect://form/<form_id>" (see FormLoaderTask for details).
+            -->
             <intent-filter>
                 <action android:name="android.intent.action.VIEW"/>
                 <data android:scheme="odkcollect" android:host="form" />

diff --git a/collect_app/src/main/java/org/odk/collect/android/tasks/FormLoaderTask.java b/collect_app/src/main/java/org/odk/collect/android/tasks/FormLoaderTask.java
@@ -182,7 +182,10 @@ protected FECWrapper doInBackground(Void... ignored) {
              */
             instancePath = loadSavePoint();
         } else if (uri.getScheme().equals("odkcollect") && uri.getHost().equals("form")) {
-            // Launch a form from a browsable web link in the format: odkcollect://form/<form_id>
+            // When the FormFillingActivity is started via a browsable link in
+            // the format "odkcollect://form/<form_id>", we want to launch and
+            // load the form with the specified Form ID.  (<form_id> is the
+            // form ID in the form definition, not the local form ID.)
             String formId = uri.getPathSegments().get(0);
             List<Form> forms = new FormsRepositoryProvider(Collect.getInstance()).get().getAllByFormId(formId);
             if (forms.size() == 0) {
@@ -283,21 +286,32 @@ protected FECWrapper doInBackground(Void... ignored) {
             }
         }
 
+        // Preselect the entity specified in a URI query parameter, if any.
         preselectEntity(fc, uri);
 
         data = new FECWrapper(fc, usedSavepoint);
         return data;
     }
 
+    /**
+     * Prefills top-level select-one fields in the form, according to query
+     * parameters given in the intent URI.
+     */
     private void preselectEntity(FormController fc, Uri uri) {
+        // We need to save the current form index in order to restore it
+        // after iterating through the form.
         FormIndex saved = fc.getFormIndex();
         try {
+            // We assume that entity selection happens in a top-level question,
+            // so no need to step into groups, i.e. stepToNextEvent(false).
             for (int event = fc.jumpToIndex(FormIndex.createBeginningOfFormIndex());
                  event != FormEntryController.EVENT_END_OF_FORM;
                 event = fc.stepToNextEvent(false)) {
                 FormIndex index = fc.getFormIndex();
                 TreeReference ref = fc.getFormDef().getChildInstanceRef(index);
                 if (ref != null) {
+                    // If there's a query parameter matching this question,
+                    // we prefill the question using the parameter value.
                     String value = uri.getQueryParameter(ref.getNameLast());
                     if (value != null) {
                         try {