App menus

When a user opens one of our apps and has logged in, they will see a main menu laid out in tiles, and a collapsed menu. These menus allow the user to navigate all of the content in the app, and initiate every journey possible.

The main menu is often called tile menu. And the collapsed menu is often called secondary menu, side menu or hamburger menu 🍔. They look like this:

The tile menu, with its sleek design, offers a great UI and in turn contributes to a better user experience. This menu is also highly customisable. Each tile can span several cells in the grid, vertically or horizontally, and they all have a background image and a text that can be easily branded. This means each of the apps we build have a tile menu that looks unique.

The collapsed menu on the top left of our mobile apps is visually more standard: it's 3 horizontal lines that expand into a vertical menu. We often use this collapsed menu for things that are less unique to each of our apps. For example, this is where users will find their account settings or the app's T&Cs and FAQs.

See for yourself

• You can download the iOS or Android app on your phone to follow this journey along. And you can also log in or sign up to the web app here
• You can also follow along by checking out the images or code snippets in this guide
• And you will find the relevant endpoints linked and explained in this guide, but the full API is documented in Swagger UI

Prerequisites

• The createClientAppMenuReferences endpoint is used to attach the menus to the client settings. So when the user enters the journey, there is content for the app to work with
• If the user is a visitor, the app needs a visitor token to display the relevant menu (see point 1b of the journey). This token is in the response of the first endpoint of the journey, getClientParameters. In there, there's a property called attributes, which holds a visitorAuthTokenId key, if applicable

Journey explained

1. Top-level menus load
   1. The getClientParameters endpoint is called. It returns information about the client, like its T&Cs, privacy policy and menu IDs. This information might change from time to time, so the app fetches it periodically to keep it up to date in the app.
   2. This endpoint contains the IDs for the 4 possible menus an app can display: a main and secondary menu for a member (or authenticated user) plus a main and secondary menu for a visitor (non authenticated user). This endpoint might also just return 2 menu IDs if the client doesn't have visitor menus set up. If it does, that part of the response looks like this:

   3. "menus": {
              "memberMainMenuId": "",
              "memberSecondaryMenuId": "",
              "visitorMainMenuId": "",
              "visitorSecondaryMenuId": ""
          }

   4. The app will display the relevant set of menus for the user. So if the user is authorised their app will display the menus referenced in memberMainMenuId and memberSecondaryMenuId. If the user is a visitor, their app will display the menus referenced in visitorMainMenuId and visitorSecondaryMenuId. These menus are set up and controlled via our Content Management System.
2. All menus and submenus are called
   1. The getAppMenuCollection endpoint is called. This returns the full list of menus and submenus for a client, with their associated actions and display settings like size, colour or background image
   2. Each item within a menu can do very different actions. Some tiles will take the user to an external site, others will take the user to another part of the app like the home feed or a specific group/padoq, and other tiles will open a submenu with more options for the user to choose from. Here are 3 examples of what menu items can do (if you click each example title, you'll find more details about how the example works):
   3. Tile taking to an external site

      A very common type of tile is the one that takes the user to an external site.
      
      One of the properties in the response of the getAppMenuCollection endpoint contains menu item types and the parameters they need to perform an action. In this case, the menu item type that takes the user to an external site only needs one parameter, which is the location of that external site (a URI).
      
      Here's the code:

                     {
                          "title": "Link",
                          "width": 1,
                          "action": {
                              "type": "URI",
                              "params": {
                                  "uri": "https://healthservicediscounts.com/"
                              }
                          },
                          "colour": "#ff3300",
                          "height": 1,
                          "position": 1,
                          "subtitle": "go to URI (in app browser)",
                          "showTitle": true,
                          "foregroundColour": "#000000"
                      }

      Tile launching a specific padoq or group

      Another common type of tile is the one that takes the user directly to a padoq.
      
      One of the menu item types handled by the getAppMenuCollection endpoint is PADOQ_FEED, which takes a padoqName as a parameter.
      
      With the padoqName, the getPosts endpoint is called. This takes one compulsory parameter (the padoqName) and allows for a bunch of other optional parameters.
      
      So, for example, if only the padoqName is provided, this tile will take the user to the full feed of that padoq. So the user can browse every post in that padoq, ordered by most recent. If another parameter is provided, the feed will only show filtered results. Some of the parameters to filter are date (to only show posts from a specific date range) and tag (to only show posts with a specific tag).
      
      Here's the code:

                     {
                          "title": "A padoq",
                          "width": 1,
                          "action": {
                              "type": "PADOQ_FEED",
                              "params": {
                                  "padoqName": "A padoq"
                              }
                          },
                          "colour": "#ff3300",
                          "height": 1,
                          "position": 2,
                          "subtitle": "go to a padoq",
                          "showTitle": true,
                          "foregroundColour": "#000000"
                      }

      Tile to explore padoqs

      Another common type of tile is the one that allows the user to explore new padoqs.
      
      One of the menu item types handled by the getAppMenuCollection endpoint is EXPLORE, which takes one of two parameters: padoqs or padoqCategory.
      
      - padoqs contains a list of padoq names for the user to explore
      - padoqCategory contains a category name that can be used to find relevant padoqs
      
      The EXPLOREaction calls the getPadoqs endpoint, passing one of the two parameters above.
      
      Here's the code:

   4.                 {
                          "title": "Explore",
                          "width": 1,
                          "action": {
                              "type": "EXPLORE"
                          },
                          "colour": "#ff3300",
                          "height": 1,
                          "position": 3,
                          "subtitle": "Explore Padoqs",
                          "showTitle": true,
                          "foregroundColour": "#000000"
                      }

How menus are managed

The design and content of the items in each menu is set and managed through a content management system or CMS. The CMS interacts with the API as a client making requests. Through the CMS, we can detail how we want tiles to look like, which items we want in the secondary menu and what we want to happen when the user taps each menu item. Access our CMS.