App menu configuration in Dynamic resources/Experience Builder
Experience Builder
Summary
This article gives you a detailed description of configuration of the app menu in the Dynamic Resources of your app in Purple Manager or Experience Builder, which can be useful during the app menu setup.
Introduction
Each Purple app comes with an app menu (accessible by clicking on the menu icon in the top left corner or with a screen swipe from left to right).
In the dynamic resources of a Purple app, there is always a so-called app_menu.xml file which defines the app menu. You have the option to use it as it is or customize the menu in the app to your needs.
Additionally, to the basic entries such as 'home' or 'e-paper', you can add further menu entries to your app.
Specifications
Location of the app_menu.xml
The app_menu.xml is part of the dynamic resources, to access it, you can either
- download the Dynamic resources from Purple Manager
- enter it via Experience Builder
No matter, if you choose to edit the app onboarding in the Dynamic resources or in the Experience builder, the described systematic works in both ways.
In both cases, the path is: default / app_menu.xml
Preconfigured app menu
Purple provides a "neutral" preconfigured App Menu in the standard dynamic resources. You can use this and/or overwrite or extend it, in order to customize it to your needs. E.g. change icons, links, text or add more menu entries.
You will find it in the app_menu.xml in the "default" folder of the dynamic resources.
Menu icons
The menu icons are located in default/menuicons
Structure of the app_menu.xml
The XML file is usually structured as follows:
The file consists of the following elements:
Frame
This is the container in which the components of the app menu are stored and looks like this
<app_menu>
</app_menu>
Header image
You have the option to place a logo above the entries of the app menu, which will be stored in the app_menu.xml as follows:
<navigationHeader>
<image URL="menulogo.png" paddingTop="10.0" height="100.0" />
</navigationHeader>
You can to specify the exact path to the logo file here, as well as the desired height and a padding.
Menu item
A single entry in the menu (using the "Bookmarks" entry as an example) looks like this:
<navigationNode targetURL="purple://app/bookmarks/open">
<title>Bookmarks</title>
<iconURL>menuicons/bookmarks.png</iconURL>
</navigationNode>
- The "navigationNode" contains a URL. The URL can be a Purple deep link which triggers a certain event (like 'open bookmarks view'), an external URL to a web page or a link to an HTML page in the dynamic content.
- The "title" tag contains the text for the displayed entry. In the example above, this is "Bookmarks". This text will be displayed in your app menu to the users.
- The "iconURL" refers to the icon for this entry in the dynamic content. This entry can also remain empty, in which case no icon is displayed. Icons must be referenced by their file name.
Menu icons
Purple apps offer the option of using custom icons for the menu used in the app.
If you want to use custom icons, you will need them in 3 different versions, so they can be displayed properly on all devices.
Usually the format *.PNG is used, because the icons contain transparent areas. The required formats for the icons are
Requirements
- PNG image with 120x120 pixel dimensions and with the file name: <iconname>@3x.png
- PNG image with 80x80 pixel dimensions and with the file name: <iconname>@2x.png
- PNG image with 40x40 pixel dimensions and with the file name: <iconname>.png
Example
You want to create your own icon for the menu item Imprint. To ensure that the menu entry looks good on all device types, you need to have the following 3 image files in place.
- imprint@3x.png, with the dimensions 120x120 pixels
- imprint@2x.png, with the dimensions 80x80 pixels
- imprint.png, with the dimensions 40x40 pixels
Purple will choose one of the three image versions, depending on the device.
Sample Photoshop icons
You can download sample Photoshop documents here:
URLs
Each menu entry leads to another URL, either inside your app or to an external source.
Examples, are among others:
- Link to an HTML page in the app (in the dynamic content) such as an imprint or the FAQ
- Link to an external website, which will be opened in a browser overlay
- Link to a specific issue in the newsstand
- a Purple deep link which triggers a certain event (like 'open bookmarks view')
An overview of possible deep links can be found in the technical documentation.
Multilanguage for app menu
For Purple apps, it is possible, to display the app's main menu in the users' device language. To enable this function, you have to add the title in the app_menu.xml in each language, that you desire to have a translation for and add a country code.
Example
Let's take a look at one of the menu entries of the app menu in the app_menu.xml.
For the Bookmark Add Entry we want to integrate an English and French version (standard is German)
<navigationNode targetURL="purple://app/bookmarks/open">
<title>Lesezeichen</title>
<iconURL>menuicons/bookmarks.png</iconURL>
</navigationNode>
The only thing that is important for a multilingual menu here, is the tag "title". In this segment, another title entry can be added using the country code and the value "locale".
If you would like to offer English and French versions now, the following entries are required:
- The two letter language codes, in our case "en" and "fr"
- The translated words for the titles ( Bookmarks and Signets )
Your result should look like this
<navigationNode targetURL="purple://app/bookmarks/open">
<title>Lesezeichen</title>
<title locale="en">Bookmarks</title>
<title locale="fr">Signets</title>
<iconURL>menuicons/bookmarks.png</iconURL>
</navigationNode>
By applying the same principle, you can set up all menu items in multiple languages.