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
| Attribute | Description |
|---|---|
| id | Unique identifier of the menu |
| alias | Alias of the menu |
| text | Header text visualised on top of the menu |
| disable_back_button | Defaults to false, when set to true the back button will be disabled on the question. |
| 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: The parameters in the menuitem overrule the definition in the menu tag.
| Attribute | Description |
|---|---|
| id="<num>" | Unique identifier of the menu item |
| label="<string>" | The text of the menuitem. |
| 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, endsurvey(), or one of the actions described below. |
| 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
| Attribute | Description |
|---|---|
| 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, endsurvey(), or one of the actions described below. |
| visible="<true / false>" | Set the visibility of the menuitem in state id. Default value is true. |
Note: If you have added one or several menu states under a menu item, the label and target of the state will be used, not those of the menu item.
Actions
The following actions can be executed in a condition within the sub-survey or as a parameter of the target (see above).
| Action | Description |
|---|---|
| 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. Note! Only works after the menu state has been set with setmenustate first. |
| 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). |
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:
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>
Example
You can download an example project below.