From 589022a43f93c1d3689d95cdf11a31dc2d135632 Mon Sep 17 00:00:00 2001 From: Rahul chaurase Date: Sat, 12 Oct 2024 10:03:57 +0530 Subject: [PATCH 1/2] Add manual saving instruction in gettting-started-2 --- src/_templates/search.html | 2 +- src/getting-started-2-architect.rst | 81 ++++++----------------------- 2 files changed, 18 insertions(+), 65 deletions(-) diff --git a/src/_templates/search.html b/src/_templates/search.html index 6e33d4bf..e445b8fb 100644 --- a/src/_templates/search.html +++ b/src/_templates/search.html @@ -9,7 +9,7 @@ jQuery(function() { Search.loadIndex("{{ pathto('searchindex.js', 1) }}"); }); {# this is used when loading the search index using $.ajax fails, - such as on Chrome for documents on localhost #} + such as on Chrome for documents on localhost #} {{ super() }} {% endblock %} diff --git a/src/getting-started-2-architect.rst b/src/getting-started-2-architect.rst index 1652e39f..0f05b112 100644 --- a/src/getting-started-2-architect.rst +++ b/src/getting-started-2-architect.rst @@ -1,7 +1,7 @@ Getting Started Building an Application ========================================================== -Now that we have seen how a device can join an already-configured application, and synchronize its view of the data with the ODK-X Sync Endpoint server hosting the application, it is time to set up our own ODK-X application. +Now that we have seen how a device can join an already-configured application and synchronize its view of the data with the ODK-X Sync Endpoint server hosting the application, it is time to set up our own ODK-X application. .. contents:: :local: @@ -9,13 +9,12 @@ Now that we have seen how a device can join an already-configured application, a Prerequisites ------------------ -This guide continues the tour where :doc:`survey-sample-app` left off. If you haven't yet completed that tour, do it first. When you have concluded the tour of the :doc:`survey-using` example application's screens, return to this guide and we will turn to setting up our own application. +This guide continues the tour where :doc:`survey-sample-app` left off. If you haven't yet completed that tour, do it first. When you have concluded the tour of the :doc:`survey-using` example application's screens, return to this guide, and we will turn to setting up our own application. .. _architect-odk-x-config-setup-app-designer: Setting up ODK-X Application Designer ----------------------------------------- - Read the :ref:`Intro ` and :ref:`Overview ` sections to get a sense of the features and functionality of the ODK-X Application Designer environment (we will install it below). Follow this guide to :doc:`app-designer-setup`. Finally, follow this guide to :doc:`app-designer-launching`. @@ -32,7 +31,7 @@ And a :program:`Chrome` browser window should open to display: If a :program:`Chrome` browser does not open, try manually launching it and opening http://localhost:8000/index.html. -You can further verify that the Application Designer works by clicking on the :guilabel:`exampleForm` button, then clicking on :guilabel:`Follow link`. This opens the *Example Form* on your computer, and simulates all the features available to you on your device. +You can further verify that the Application Designer works by clicking on the :guilabel:`exampleForm` button, then clicking on :guilabel:`Follow link`. This opens the *Example Form* on your computer and simulates all the features available to you on your device. You can also try other things, like choosing different device dimensions to see how the form renders on different screen geometries. @@ -40,7 +39,6 @@ You can also try other things, like choosing different device dimensions to see Modifying an ODK-X application ------------------------------------- - The next task is to modify the *Example Form* application by adding a new data field to it. Return to your :program:`cmd` window and once again launch the ODK-X Application Designer environment (and a :program:`Chrome` browser) by typing: @@ -80,9 +78,21 @@ You should now see some JSON in the output window. Hit the :guilabel:`Save to Fi 4. Writing the updated `ODK-X Survey `_ form definition into the :file:`formDef.json` file in the same location as the :file:`exampleForm.xlsx` file. .. note:: + **Manual Saving (When Automatic Saving Fails)** + + .. this instruction is needed when automatic saving fails in this case these . + + In case you encounter an error with the :guilabel:`Save to File System` button (e.g., "Something went wrong! Please save the file manually"), follow these steps to manually save the generated JSON: + + 1. Copy the JSON output displayed in the output window. + 2. Open a text editor (like Notepad, VSCode, or Sublime Text). + 3. Paste the JSON into a new file. + 4. Save the file with the name `formDef.json` in the same location as the `exampleForm.xlsx` file (typically :file:`app/config/tables/exampleForm/forms/exampleForm`). + 5. Repeat this process for any other files that failed to save (e.g., :file:`definition.csv`, :file:`properties.csv`), if needed. The :file:`definition.csv` and :file:`properties.csv` files are updated because the *form_id* is the same as the *table_id*. + On the :program:`Chrome` Browser, click on the :guilabel:`Preview` tab. Click on :guilabel:`Purge Database`. This will delete the earlier *Example Form* data table -- a necessary step because we are adding a :th:`Color` column to that data table. Select :guilabel:`exampleForm` if you do not already have that form open. Create a new instance of the *Example Form* and advance through it (this will create the data table with the new :th:`Color` column). Confirm that the new question is displayed as shown below. @@ -96,17 +106,15 @@ You have successfully modified the form. We will now walk through how to deploy Deploying to the Device ----------------------------------------------- - Now that we have the design environment installed and have successfully modified the Example Form application, we can work through the steps of deploying that application to your device. .. _architect-odk-x-deploy-prepare: Preparing the Device ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - If you followed along with the :doc:`survey-sample-app`, you should already have all the necessary tools installed on your device. If not, follow the :doc:`basics-install` instructions to install ODK-X Services, `ODK-X Survey `_, and ODK-X Tables. -First, open the :guilabel:`Files by Google` app on the device. Delete the whole :guilabel:`opendatakit` folder by clicking the folder and holding it until it becomes highlighted in blue. Then press the delete icon, and click :guilabel:`OK` in the resulting window. +First, open the :guilabel:`Files by Google` app on the device. Delete the whole :guilabel:`opendatakit` folder by clicking the folder and holding it until it becomes highlighted in blue. Then press the delete icon and click :guilabel:`OK` in the resulting window. .. image:: /img/getting-started-2/file-manager-delete-folder.* :alt: Delete opendatakit folder in OI File Manager @@ -130,59 +138,4 @@ Finally, confirm that your device has :guilabel:`USB debugging` enabled inside y Pushing the Application to the Device ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Return to the :program:`cmd` window on your computer. :kbd:`Control-C` to stop the :program:`grunt` command that popped-open the :program:`Chrome` browser. On Windows, you will be asked to confirm this ``Terminate batch job (Y/N)?``. Enter ``Y`` to confirm. - -Connect your device to your computer via USB. Wait for the storage connection to be established (on Windows, this will generally pop up a file browser or an options box that enables you to select a file browser). Be sure you trust your computer on your Android device, or it will cause unexpected errors. - -At the command prompt, navigate to the Application Designer folder and type: - -.. code-block:: console - - $ grunt adbpush - -.. warning:: - - This command will force-close ODK-X Services, Survey, and Tables, and it will clear all ODK-X data from the device. The data you are pushing will overwrite any existing application or collected data you might have. Be sure to make backups and be sure you are ready before running this command. - -This pushes the configured ODK-X application within this ODK-X Application Designer directory to your device. When you issue this command, the cmd window will display a long series of commands and conclude with a display of overall progress and timings: - -.. image:: /img/getting-started-2/geotagger-cmd-gruntpush.* - :alt: Geotagger Grunt Push - -Now, on your device, launch `ODK-X Survey `_. - -This will initiate the configuration of `ODK-X Survey `_ and conclude with a :guilabel:`Configuration Summary` pop-up reporting that everything was imported successfully. Click :guilabel:`OK`. - -Scroll to and select the *Example Form*. Create a new instance of the survey, and click :guilabel:`Go to next prompt`. You should now be looking at the question you added to the form. - -You have now successfully deployed a modified ODK-X application onto a device. - - -Next Steps ------------------------ - -Survey and Tables each have a basic sample application that walks through their features: - - - :doc:`survey-sample-app` - - :doc:`tables-sample-app` - - -To get started building applications, first set up the :doc:`app-designer-intro`. After you have familiarized yourself with that tool, you can try building and deploying an application: - - - :doc:`build-app` - -A more complete guide to using ODK-X XLSX Converter is provided in the :doc:`xlsx-converter-intro` documentation. More details about Tables web views are available in :doc:`tables-web-pages` and :doc:`injected-interfaces`. - -For examples of real world applications and details about they are implemented, try out the: :doc:`reference-apps`. - -We also provide guides for setting up your own ODK-X application for each of the Android and Desktop tools. - - - :doc:`survey-using` - - :doc:`tables-managing` - - :doc:`services-managing` - - :doc:`scan-managing` - -However, the user guides for these tools are also useful for everyone. - -Finally, to expand your knowledge of the more advanced features of the platform, such as data permission filters, read the :doc:`advanced-topics-architect`. +Return to the :program:`cmd` window on your computer. :kbd:`Control From 34c1bdff8e7646983536f3d781f3c30306a99afd Mon Sep 17 00:00:00 2001 From: Rahul chaurase Date: Sun, 13 Oct 2024 22:36:15 +0530 Subject: [PATCH 2/2] Add manual instructrion for saving to file system --- src/getting-started-2-architect.rst | 92 ++++++++++++++++++++++++----- 1 file changed, 77 insertions(+), 15 deletions(-) diff --git a/src/getting-started-2-architect.rst b/src/getting-started-2-architect.rst index 0f05b112..4aa10e94 100644 --- a/src/getting-started-2-architect.rst +++ b/src/getting-started-2-architect.rst @@ -1,7 +1,7 @@ Getting Started Building an Application ========================================================== -Now that we have seen how a device can join an already-configured application and synchronize its view of the data with the ODK-X Sync Endpoint server hosting the application, it is time to set up our own ODK-X application. +Now that we have seen how a device can join an already-configured application, and synchronize its view of the data with the ODK-X Sync Endpoint server hosting the application, it is time to set up our own ODK-X application. .. contents:: :local: @@ -9,12 +9,13 @@ Now that we have seen how a device can join an already-configured application an Prerequisites ------------------ -This guide continues the tour where :doc:`survey-sample-app` left off. If you haven't yet completed that tour, do it first. When you have concluded the tour of the :doc:`survey-using` example application's screens, return to this guide, and we will turn to setting up our own application. +This guide continues the tour where :doc:`survey-sample-app` left off. If you haven't yet completed that tour, do it first. When you have concluded the tour of the :doc:`survey-using` example application's screens, return to this guide and we will turn to setting up our own application. .. _architect-odk-x-config-setup-app-designer: Setting up ODK-X Application Designer ----------------------------------------- + Read the :ref:`Intro ` and :ref:`Overview ` sections to get a sense of the features and functionality of the ODK-X Application Designer environment (we will install it below). Follow this guide to :doc:`app-designer-setup`. Finally, follow this guide to :doc:`app-designer-launching`. @@ -31,7 +32,7 @@ And a :program:`Chrome` browser window should open to display: If a :program:`Chrome` browser does not open, try manually launching it and opening http://localhost:8000/index.html. -You can further verify that the Application Designer works by clicking on the :guilabel:`exampleForm` button, then clicking on :guilabel:`Follow link`. This opens the *Example Form* on your computer and simulates all the features available to you on your device. +You can further verify that the Application Designer works by clicking on the :guilabel:`exampleForm` button, then clicking on :guilabel:`Follow link`. This opens the *Example Form* on your computer, and simulates all the features available to you on your device. You can also try other things, like choosing different device dimensions to see how the form renders on different screen geometries. @@ -39,6 +40,7 @@ You can also try other things, like choosing different device dimensions to see Modifying an ODK-X application ------------------------------------- + The next task is to modify the *Example Form* application by adding a new data field to it. Return to your :program:`cmd` window and once again launch the ODK-X Application Designer environment (and a :program:`Chrome` browser) by typing: @@ -78,19 +80,22 @@ You should now see some JSON in the output window. Hit the :guilabel:`Save to Fi 4. Writing the updated `ODK-X Survey `_ form definition into the :file:`formDef.json` file in the same location as the :file:`exampleForm.xlsx` file. .. note:: - **Manual Saving (When Automatic Saving Fails)** - .. this instruction is needed when automatic saving fails in this case these . - - In case you encounter an error with the :guilabel:`Save to File System` button (e.g., "Something went wrong! Please save the file manually"), follow these steps to manually save the generated JSON: + **Manual Saving (When Automatic Saving Fails)** + + .. this instruction is needed when automatic saving fails. - 1. Copy the JSON output displayed in the output window. - 2. Open a text editor (like Notepad, VSCode, or Sublime Text). - 3. Paste the JSON into a new file. - 4. Save the file with the name `formDef.json` in the same location as the `exampleForm.xlsx` file (typically :file:`app/config/tables/exampleForm/forms/exampleForm`). - 5. Repeat this process for any other files that failed to save (e.g., :file:`definition.csv`, :file:`properties.csv`), if needed. + In case you encounter an error with the :guilabel:`Save to File System` button (e.g., "Something went wrong! Please save the file manually"), follow these steps to manually save the generated JSON: - The :file:`definition.csv` and :file:`properties.csv` files are updated because the *form_id* is the same as the *table_id*. + 1. Copy the JSON output displayed in the output window. + 2. Open a text editor (like Notepad, VSCode, or Sublime Text). + 3. Paste the JSON into a new file. + 4. Save the file with the name `formDef.json` in the same location as the `exampleForm.xlsx` file (typically :file:`app/config/tTables/exampleForm/forms/exampleForm`). + 5. Repeat this process for any other files that failed to save (e.g., :file:`definition.csv`, :file:`properties.csv`), if needed. + +.. note:: + + The :file:`definition.csv` and :file:`properties.csv` files are updated because the *form_id* is the same as the *table_id*. On the :program:`Chrome` Browser, click on the :guilabel:`Preview` tab. Click on :guilabel:`Purge Database`. This will delete the earlier *Example Form* data table -- a necessary step because we are adding a :th:`Color` column to that data table. Select :guilabel:`exampleForm` if you do not already have that form open. @@ -106,15 +111,17 @@ You have successfully modified the form. We will now walk through how to deploy Deploying to the Device ----------------------------------------------- + Now that we have the design environment installed and have successfully modified the Example Form application, we can work through the steps of deploying that application to your device. .. _architect-odk-x-deploy-prepare: Preparing the Device ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + If you followed along with the :doc:`survey-sample-app`, you should already have all the necessary tools installed on your device. If not, follow the :doc:`basics-install` instructions to install ODK-X Services, `ODK-X Survey `_, and ODK-X Tables. -First, open the :guilabel:`Files by Google` app on the device. Delete the whole :guilabel:`opendatakit` folder by clicking the folder and holding it until it becomes highlighted in blue. Then press the delete icon and click :guilabel:`OK` in the resulting window. +First, open the :guilabel:`Files by Google` app on the device. Delete the whole :guilabel:`opendatakit` folder by clicking the folder and holding it until it becomes highlighted in blue. Then press the delete icon, and click :guilabel:`OK` in the resulting window. .. image:: /img/getting-started-2/file-manager-delete-folder.* :alt: Delete opendatakit folder in OI File Manager @@ -138,4 +145,59 @@ Finally, confirm that your device has :guilabel:`USB debugging` enabled inside y Pushing the Application to the Device ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Return to the :program:`cmd` window on your computer. :kbd:`Control + +Return to the :program:`cmd` window on your computer. :kbd:`Control-C` to stop the :program:`grunt` command that popped-open the :program:`Chrome` browser. On Windows, you will be asked to confirm this ``Terminate batch job (Y/N)?``. Enter ``Y`` to confirm. + +Connect your device to your computer via USB. Wait for the storage connection to be established (on Windows, this will generally pop up a file browser or an options box that enables you to select a file browser). Be sure you trust your computer on your Android device, or it will cause unexpected errors. + +At the command prompt, navigate to the Application Designer folder and type: + +.. code-block:: console + + $ grunt adbpush + +.. warning:: + + This command will force-close ODK-X Services, Survey, and Tables, and it will clear all ODK-X data from the device. The data you are pushing will overwrite any existing application or collected data you might have. Be sure to make backups and be sure you are ready before running this command. + +This pushes the configured ODK-X application within this ODK-X Application Designer directory to your device. When you issue this command, the cmd window will display a long series of commands and conclude with a display of overall progress and timings: + +.. image:: /img/getting-started-2/geotagger-cmd-gruntpush.* + :alt: Geotagger Grunt Push + +Now, on your device, launch `ODK-X Survey `_. + +This will initiate the configuration of `ODK-X Survey `_ and conclude with a :guilabel:`Configuration Summary` pop-up reporting that everything was imported successfully. Click :guilabel:`OK`. + +Scroll to and select the *Example Form*. Create a new instance of the survey, and click :guilabel:`Go to next prompt`. You should now be looking at the question you added to the form. + +You have now successfully deployed a modified ODK-X application onto a device. + + +Next Steps +----------------------- + +Survey and Tables each have a basic sample application that walks through their features: + + - :doc:`survey-sample-app` + - :doc:`tables-sample-app` + + +To get started building applications, first set up the :doc:`app-designer-intro`. After you have familiarized yourself with that tool, you can try building and deploying an application: + + - :doc:`build-app` + +A more complete guide to using ODK-X XLSX Converter is provided in the :doc:`xlsx-converter-intro` documentation. More details about Tables web views are available in :doc:`tables-web-pages` and :doc:`injected-interfaces`. + +For examples of real world applications and details about they are implemented, try out the: :doc:`reference-apps`. + +We also provide guides for setting up your own ODK-X application for each of the Android and Desktop tools. + + - :doc:`survey-using` + - :doc:`tables-managing` + - :doc:`services-managing` + - :doc:`scan-managing` + +However, the user guides for these tools are also useful for everyone. + +Finally, to expand your knowledge of the more advanced features of the platform, such as data permission filters, read the :doc:`advanced-topics-architect`. \ No newline at end of file