Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 13 Next »

We have several different tools for controlling what is seen during menu navigation in CommCare (everything between the Start screen and the Form itself). This page should help clarify the different options available.  

There are three key things that control which screens show up during the menu navigation:

  1. Menu Mode (menu Settings tab)

  2. Whether or not it is a "Case List" menu

  3. Parent Child Selection (menu Case List tab)

The controls for these are outlined in red in the first 3 of the following screenshots:

To turn on menu mode, make sure the "Menu Mode" add-on is enabled on the application settings page.

  1. Access the application settings page by clicking the gear icon next to the application name on the upper-left corner. 

  2. On the settings page, select the Add-ons tab, then select the button with three-lines in the upper right hand corner and make sure the Mobile Experience is checked.

  3. Scroll down to the Mobile Experience block and select the Register from case list checkbox and hit save.

Once the screen navigation has been determined, there are filters that you can apply to only see desired choices (availability depends on the screen navigation):

  1. ♣ Menu Filter (Case List Menu > Settings tab)

  2. ♥ Form Display Condition (form settings > settings tab)

  3. ♦ Case List Filter (Case List Menu > Case List tab)

The controls for these filters are marked in the above screenshots using the symbols indicated.

This page is not intended to teach you everything about how to access and use these filters - please refer to the linked pages to learn more.

In the below flows, you will see the appropriate symbols for each of the filter types when they are available.  Note that they are not all available for all navigation paths.  Both the ♦ and ♦♦ symbols indicate Case List Filters.  However, the ♦ filter is the one for the current menu while the ♦♦ filter is the one on the menu that we are using for the Parent Case List.

The parenthesis are used around Case Lists because if you select a Registration form in the Form List, there will be no Case List selection and the navigation will skip immediately to the Form content.

  1. Parent Child Selection Off

    1. Menu Mode = Show Menu then Form

      1. Menu without Registration
        Start → ♣ Menu List → ♦ Case List → ♥ Form List → Form

      2. Menu with Registration
        Start → ♣ Menu List → ♥(warning) Form List → (♦ Case List) → Form

    2. Menu Mode = Display Only Forms
      Start → Form List → (♦ Case List) → Form

  2. Parent Child Selection On

    1. Menu Mode = Show Menu then Form

      1. Menu without Registration
        Start → ♣ Menu List → ♦♦ Parent Case List → ♦ Case List → ♥ Form List → Form

      2. Menu with Registration
        Start → ♣ Menu List → ♥(warning) Form List → (♦♦ Parent Case List) → (♦ Case List) → Form

    2. Menu Mode = Display Only Forms
      Start → Form List → (♦♦ Parent Case List) → (♦ Case List) → Form

  1. ♣ Menu Filters:  You will notice that Menu filters are always applied before a case has been selected.  Therefore, they cannot depend on any of the case properties associated with the case.  Menu filters can only be used to filter on properties from the user-case or on constants, such as false().

  2. ♥ Form Display Conditions:  

    1. For paths 1.a.i and 2.a.i above, the Form Display Condition is executed after a case has already been selected from the case list.  Therefore, the Form Display Condition can depend on the case properties, any user-case properties, or on constants, such as false().

    2. (warning) For paths 1.a.ii and 2.a.ii above, the Form Display Condition is executed before any case has been selected from the case list.  Therefore, the Form Display Condition cannot depend on any regular case properties.  In these paths, the display condition can only be used to filter on properties from the user-case or on constants, such as false().  If the application is not using user-case, the Form Display Condition will not be available at all.  The (warning) symbol should alert you that Form Display Conditions are limited in these paths and you should be careful to understand these limitations before using one.

    3. Form display conditions are not currently available when Menu Mode = Display Only Forms. 

  3. ♦ Case List Filter:  Case list filters are always available to filter the case list.

See https://dimagi.atlassian.net/wiki/x/OinKfw more information about the User-Case feature referenced above.

Form Navigation

When you build your CommCare application, you can define the screen that will direct users after they submit a form instead of returning to the home screen. This feature is called End of Form Navigation, and it offers four options for users to choose from, depending on the application configuration: Home Screen, First Menu, Previous Screen, and Link to another form or menu.

Here's an overview of each option:

  • Home Screen: This takes the user to the start screen on Android or the module list on feature phones.

  • First Menu: The user will be directed to the module menu within the application they are working on.

  • Menu: If the user selects this option, the screen they would see when clicking on a module name will be displayed. 

    • If the application is configured such that the case list comes before the form list, this will take the user to the case list. 

    • If the application is configured such that the form list comes before the case list, this will take the user to the form list. However, if the menu mode of the module is set to "Display only forms," the user will be returned to the home screen, not the module screen.

    • Previous Screen: This option returns the user to the last screen before the form was opened. Depending on the application's configurations, this could be a case details screen, a form list, or a child case list.

  • Link to other form or menu:  This allows for conditionally linking another form or menu, which we'll call target. This means when the user submits a form, let's refer to this as the source form, another screen in the app will be automatically loaded.

Below are the steps to configure the end of form navigation:

Step-1: While editing your form, select the option to manage a case. 

select Manage case.png

Step-2: Activate the option to show the logic, allowing you to configure the end of form navigation..

step2.png

Step-3: Select the desired option from the menu.

step3.png

If you select "Link to another form or menu" you will need to specify a target form and may need to set up a conditional expression to determine whether the form should be presented to the user. Here's how:

form_link_setup.png

Target Form - Specify the form that will open once the user submits the current form.

Linking Data - If the target form is located in a module that caters to a different case type than the current form, you may need to specify the case_id of the case that Commcare will need to load. In most scenarios, if the case_id is the same as the current form, Commcare can manage this independently, and no user intervention is required.

Conditional expression -If the decision to link to the target form is dependent on a condition being met, you will need to specify a conditional expression. This expression must return a boolean value (true or false). Note that in the context of the form link conditional expression, form content is unavailable, so the expression must rely solely on case properties.

In the context of the form link conditional expression, form content is not available, so something like /data/some_question=’yes’ wouldn’t work. The expression below is an example of a expression that could be accepted if the property link_form is saved to the case. This expression gets the case from the case database (casedb), based on the ID stored in the user session, and verifies whether the property link_form is equal to ‘Yes’. If the expression returns 'true', the target form will be presented to the user, otherwise Commcare will move to the next condition, if applicable, or fallback to one of the default options.

conditional_expression_example.png

Navigation fallback - select where the user should navigate to if that form is not available (for example, if the form is hidden for that case, if the form is hidden for that user, or if the the data needed for the form to open has not been provided). For example, let's say there's a registration form that links to a follow-up form right after it. But only supervisor can do follow-up. If there is a display condition that hides the follow-up form form the normal user and the normal user finishes a registration form, CommCare can’t follow through with the end of form navigation, so it sill fall back on any menu or page you specified in the Navigation Fallback setting. If a supervisor finishes a registration, the form is accessible and end of form navigation happens.

Note: The Case ID is not always referenced in the session as case_id, this varies depending on the form and module configurations. 

Form linking is conditional on a case property being met, the XPath Expression must reference the specific case from the casedb.

  • The default XPath reference to a case_id that's been loaded into a form context is instance('commcaresession')/session/data/case_id. You can reference case properties from this case by using the following example syntax:

    • instance('casedb')/casedb/case[@case_id = instance('commcaresession')/session/data/case_id]/link_form = 'yes'

  • It's possible to load multiple cases into the same form. This means that there is no default syntax for referencing these cases. To see what data exists in your session hash, you can: 1) Go to App Preview, 2) Open the form you're linking from, 3) Click on "Menu" and select "Evaluate XPath", 4) Type instance('commcaresession')/session. This will display all the data that you can reference from the session hash. See the following example syntax:

    • instance('casedb')/casedb/case[@case_id = instance('commcaresession')/session/data/case_id_new_qi_report_0]/next_step = 'indicateurs'

There are some limitations to End of Form Navigation:

  • Menus and Linking Data - Menus typically do not require data. The few that do, like menus with a parent menu, do not allow you to customize what data is passed. Even more rarely, a menu may not be available because it requires data, and HQ cannot determine what data it needs. This is likely to happen only with parent-child menu workflows that use different case types than the form you're linking from.

  • Registration from the Case List - It is not recommended to set up End of Form Navigation anywhere except the home screen for forms being used as Case List Registration forms. This can lead to unexpected behavior in the Case List Registration workflow. However, despite the warning message displayed when form linking is attempted, it can still work for most use cases. Just make sure to thoroughly test it on Formplayer and mobile.

image2019-8-20_18-1-11.png

  • Display Only Forms - If you're linking to a menu, not a form, the menu cannot use the display-only forms setting. This is because these menus do not have their own dedicated "screen," and their forms are displayed in the home screen or their parent menu's screen (if there is a parent).

  • Formplayer - There have been reports of form linking not fully working on FormPlayer (live preview or webapps), especially when manual form linking is used. Make sure to test it on mobile and report any inconsistencies.

  • No labels