Menus with advanced logic

Created: - Updated:

Structure

A menu is divided into a number of menu items, each of them pointing to different sub surveys. Every menu item can have several statuses, which can be used to control the icon, the text and the action of the menu item, as well as its visibility.

Every item in a menu is linked to a folder (see adding a new folder), which can contain any number of questions. When the respondent selects a specific item, the app will go through the questions contained in the folder linked to that menu item, starting from the first question in your folder. Logic can also be inserted within the folder, with the exception that logic jumps should never point outside the folder. Once the respondent reaches the end of the folder, the data will be sent to the server and a confirmation message will be displayed within the app. Please note that the confirmation message is customizable or can be hidden (see the notes below on upload-msg-txt and upload-header-txt to customize this message).

A menu is divided into a number of menuitems, each of them pointing to different sub surveys. Every menuitem can have several statuses, which can be used to control the icon, the text and the action of the menuitem, as well as its visibility.

Menus can also be nested, for instance when the first item of a menu connects to another menu. The function gotopreviousmenu() can be used to go to the parent menu from a child menu.

The image below describes the example shown at the beginning of this section.

In the example above, M3 is the main menu that contains a menuitem for each day of the week. Every menuitem points to a different folder, which contains the questions for that subfolder. For example, the first item of M3 points to folder F1, which contains an initial question (Q1) followed by a loop (F8). 

Note: In menus, the folders are treated as containers that hold the questions that should be accessible within that menu item. For that reason, you cannot perform the usual functions of folders on them (e.g. loop piping). If that is required, you need to have another folder inside the container. For example, to loop the questions inside a menu item Monday (folder F1), you need to create another folder (F8).

The code structure is as follows:

<menu id="1" type="menu" alias="M3" text="Please complete the task for every day of the week:" upload-msg-txt="Thanks for completing your task today!" upload-header-txt="Great job!">

  <menuitem id="1">
    <state id="1" label="Monday" icon="1" target="goto(F1)"/>
    <state id="2" label="Monday" target="" icon="2"/>
  </menuitem>
  <menuitem id="2">
    <state id="1" label="Tuesday" target="goto(F2)" icon="1"/>
    <state id="2" label="Tuesday" target=""/>
  </menuitem>

</menu>

Attributes

The following tables describe all the attributes in a menu:

menu

AttributeDescription
id Unique identifier of the menu 
alias Alias of the menu
text Header text visualised on top of the menu
upload-header-txt="<string>" Header of the confirmation popup that is displayed at the end of every sub-survey (applies to menu)
upload-msg-txt="<string>" Text of the confirmation popup that is displayed at the end of every sub-survey (applies to menu)

Note: if both of the above attributes are not defined, the confirmation popup will display the default upload message "Thank you: Your responses have been received."

menuitem

The upload header and text can also be defined differently for each menuitem, allowing a higher personalisation of the diary experience (e.g. you could prompt "Thanks for completing Monday" when the first menu item is completed")

Note: these parameters overrule the definition in the menu tag.

 

AttributeDescription
id Unique identifier of the menu item 
upload-header-txt="<string>" Header of the confirmation popup that is displayed at the end of a specific menuitem sub-survey (applies to a specific menuitem)
upload-msg-txt="<string>" Text of the confirmation popup that is displayed at the end of a specific menuitem sub-survey (applies to a specific menuitem)

state

AttributeDescription
id="<num>" The number of the state (by default, a menu has all the menuitem set to state 1).
label="<string>" The text of the menuitem in state id.
icon="<num>" The icon of the menuitem in state id.
target="<function>" The function that needs to be executed when the respondent hits on the menuitem on state id. It could be either a goto() function that points to a folder, one of the actions described below, or any other function.
visible="<true / false>" Set the visibility of the menuitem in state id. Default value is true.

Actions

The following actions can be executed in a condition within the sub-survey or as a parameter of the target (see above).

ActionDescription
setmenustate(menu_id,item_id,state_id) Sets the state for a specific menu item. menu_id can be either an alias or the ID (like in setans() for example).
setallmenustates(menu_id,state_id)

Sets the states for all items within menu_id to the specified state.

getmenustate(menu_id,item_id) Fetches the current state for a item in the menu, e.g. could be used in conditions.
gotopreviousmenu() Takes you to the previous menu (parent menu).

 

Note: if you are executing an action that refers to a menu_id outside the menu you are currently in, you must include a hash-sign before the menu_id, i.e. setmenustate(#menu_id,item_id,state_id).
This only applies when menu_id is used. If alias is used, the hash-sign should not be included.

Using a menu as the app first screen

When the app is used for a single diary, the diary can be set to launch automatically as respondents open the app. In this way, the first screen respondents see can be completely personalized. In order to launch the diary automatically, simply add the attribute open_directly="true" to the survey tag, as shown below:

<survey wave="1" status="live" name="LS Demo" description="" type="diary" track_gps="false" id="4" start_publish="" stop_publish="" open_directly="true">

 

Note: this feature is only available when respondents don't have more than one diary downloaded in the app.

Menu tips and tricks

  • When testing, it is always good to have an extra item in the menu that resets all menu items to the initial state:

    <menuitem id="8">
      <state id="1" label="Reset all menu items" target="setallmenustates(1,1)"/> </menuitem>
  • For diaries that have a specific duration, it is good practice to always consider what is going to happen at the end of the diary (i.e. when the respondent has completed all the tasks). For instance, you may want to automatically display a menu item that allows respondents to go back to the home screen when all the tasks are completed:

    <menuitem id="9">
      <state id="1" label="Not visible" visible="false"/>
      <state id="2" label="Diary complete, back to home" target="gotopreviousmenu()"/>
    </menuitem>

 

Note: the switch between state1 and state2 will be driven by logic in each sub-diary (e.g. variables could be used to keep track of the completed tasks).

Example

You can find an example in !linkthis attached page.