Content
Description
The SnomIPPhoneMenu (or IPPhoneMenu) tag displays a Menu of selectable items. These items can either be sub-menus, containing items themselves, or items with a specific target (like URLs, key-events or internal callbacks)
See examples for this tag below.
Valid Attributes
- SnomIPPhoneMenu can contain any of the attributes from the Main Attributes list
- has_scrollbar: Display a scrollbar. Valid values: true, false, yes, no, on, off.
- speedselect: If enabled, an item or line can be selected by entering the according number. If set to enter, the item is directly entered, as if the user pressed the OK button. If set to select, the item/line is only preselected. Valid values: off, select, enter.
- show_menu_arrow_right - By default, an arrow is displayed on the right side of the Menu subtags to indicate the user that a submenu is available. By setting show_menu_arrow_right="No" the phone no longer shows this arrow. You can also override this arrow with a custom icon, see the ExtraIconType subtag below.
- IconSize: size of the icons that will be used with the IconType subtag. Valid Values: XXS, XS, S, M, L, XL, XXL, XXXL. Default value: S. The meaning of the values refers to icon height in pixels and translates as follows:
XXS = 18
XS = 24
S = 36
M = 48
L = 60
XL = 72
XXL = 84
XXXL = 96
See an example of using the IconSize here.
Valid Subtags
The SnomIPPhoneMenu can contain any of the subtags from the Main Subtags list.
In addition, it contains the following subtags:
Menu
A sub-menu containing menu elements.
Valid Attributes
A Menu tag supports the following attributes:speedselect
- Description: If enabled, an available item or line can be selected by entering the according number. If set to enter , the item is directly entered, as if the user pressed the OK button. If set to select , the item/line is only preselected.
- Valid values: off, select, enter
- has_scrollbar
- Description: Display a scrollbar.
- Valid Values: true, false, yes, no, on, off
- name
Description: Name that is displayed for this menu entry in the parent menu. This is also the default title for menu elements, if none is specified. This attribute is required.
Valid Values: Any text.
Don't use line break inside this attribute.
- Description: Arbitrary id to make alternative (via if clause) menu entries with different names identifiable. This can be necessary for the internal XPath-based navigation mechanism in nested menus.
- Valid Values: Any text.
- on_selected
- on_deselected
Valid Subtags
Below are the tags that a Menu tag can contain.
- Title
Description: Title of the sub-menu.
Valid Values: Any text.
Don't use line break inside this attribute.
- InputField
- Description: Show an input field as first line of the menu. See an InputField example below.
- Valid Attributes
Here are the valid attributes for InputField:- on_selected: Execute fragment URL when this element is selected. This will not fetch any external URLs, it only works to execute fragments (if trusted).
- on_deselected: Execute fragment URL when this element is selected. This will not fetch any external URLs, it only works to execute fragments (if trusted).
- Valid Subtags
Here are the valid tags that can be nested into InputField:- If, Elif, Else: see Conditional blocks
- Handler: Name of handler of the input.
- an InputField can have one Handler subtag with one of the events (keypress or timeout) or two Handler subtags handling both events (see example in the Examples section below).
- If a Handler with keypress event is present inside an InputField, the Key subtag must also present to determine which key will be used as confirmation key.
- If a Handler with timeout event is present inside an InputField, the Timeout subtag must also present to determine how long the timeout will be, and the Minimum subtag must also be there to determine the minimum input to activate the timeout.
- Key: Key that triggers the handler.
- Timeout: Time in ms after which the handler is called. If the current InputField is unselected before the timeout is over, the handler will be executed immediatly
- Minimum: Minimum number of characters to enable timeout.
- Prompt: Prompt for the input field.
- Notes
- It is recommended to set the speedselect attribute to off in parent Menu to prevent the selection bar from jumping around when the user inputs the text.
- The input mode can be changed with long press * key.
- If the selection bar is placed in one of the Menuitem elements, it will jump to InputField if the user enters an input.
- The input will be passed with the callback $[current_input]
- The input mode will not be shown.
- No function key will be used as backspace (unlike SnomIPPhoneInput). But a SoftKeyItem can be used as workaround.
- With the D8xx series (new PhoneUI) it is possible have multiple InputFields. InputFields on D8xx with new UI MUST have a Timeout handler to store the input data to the cache. They must also have a SoftKey that flushes the cache (see example below). If SoftKeyItem1 is not defined a EditMode will automatically added. If SoftKeyItem3 is not defined a Backspace will automatically added.
- Description: Show an input field as first line of the menu. See an InputField example below.
- SoftKeyItem
See SoftKeyItem - Menu
The Menu tag can contain another Menu tag - MenuItem
See below MenuItem - Repeat
See Repeats - <If>,<Elif>,<Else>
See Conditional blocks - IconType - this subtag allows the option to use pre-defined icons existent on the phone by using their internal names.
- Here is simple usage example: <IconType>$(icon_type_enum:kIconTypeContactStateAvailableAtDesk)</IconType> . See here for a full example.
- The icon will change color when the menu item is selected.
- The IconType icon will only work correctly if the used icon exists in the size given by the IconSize subtag for the parent menu. For example, if the IconSize is not set (meaning it will default to S = 36 pixels), you can only use an IconType for which the icon height in pixel is 36, otherwise the phone will display a default image showing the Snom logo. You can find details regarding the Snom internal icons here: Phone Interface Icons, from this page you can click on each icon category and then you can check the icon height column to see if the chosen icon exists in the needed size.
- ExtraIconType and ExtraIconType2 - these subtags can be used to display icons on the right side of a MenuItem. If both ExtraIconType and ExtraIconType2 are present, they will be shown next to each other, with ExtraIconType2 being shown in front of ExtraIconType. See example here
- By default, an arrow is displayed on the right side of the Menu subtags to indicate the user that a submenu is available. By using ExtraIconType, this arrow can be replaced by a custom icon. Also see the show_menu_arrow_right attribute which deactivates this default arrow. Click here to see the difference between default and customized Menu.
- The ExtraIconType and ExtraIconType2 icons will only work correctly if the used icon exists in size 18, otherwise the phone will display a default image showing the Snom logo. You can find details regarding the Snom internal icons here: Phone Interface Icons, from this page you can click on each icon category and then you can check the icon height column to see if the chosen icon exists in the needed size.
- SubText
- Description: display a subtext in addition to the Menu title. This only works for deskphones with color display running version 10.x. See example here.
- Valid Value: Any text
- ExtraText
- Description: display an extra text in addition to the Menu title. This only works for deskphones with color display running version 10.x. See example here.
- Valid Value: Any text
- ExtraText2
- Description: display a second extra text (under the ExtraText). This only works for deskphones with color display running version 10.x.
- Valid Value: Any text
- Title
MenuItem
Describes a menu entry that targets to either an URL, a key event or an internal callback.
Valid Attributes
A MenuItem tag can contain the following attributes:- sel
- Description: Preselect this MenuItem
- Valid Values: true, false
- scroll_always (since 10.1.49.0)
- Description: If this attribute is enabled, activate the scrolling of the menu line text that doesn't fit, regardless of the common scrolling behavior. If the attribute is disabled the common scrolling behavior is used.
- Valid Values: off, on
- name
- Description: Name that is displayed for this menu entry in the parent menu. This attribute is required.
Valid Values: Any text.
Don't use line break inside this attribute.
- id
- Description: Arbitrary id to make alternative (via if clause) menu entries with different names identifiable. This can be necessary for the internal XPath-based navigation mechanism in nested menus.
- Valid Values: Any text.
- on_selected
- on_deselected
- sort_key
- Description: Key by which the items get sorted if the main attribute sort is enabled. If this attribute is omitted the items will not be sorted (they will be displayed in the order in which they were entered in the XML code)
- sel
Valid Subtags
Here are the tags that a MenuItem tag can contain:
- <If>,<Elif>,<Else>
See Conditional blocks - Icon
- Description: Show an existing phone icon beside the menu text.
All the Snom phones with branding features can use the internal icons available under file://snom/bmp/colored . The available icons can be found inside the customizing archive (Firmware → click on your version → Customization Files)
To display an external icon/image use image instead. - Valid Values: Any valid internal icon from ' file://snom/bmp/colored '
See an Icon example below.
- Description: Show an existing phone icon beside the menu text.
- URL
- Description: URL of the file that should be fetched when the menu entry is selected.
- Valid Attributes
Here are the valid attributes for the URL tag:- new_context: Creates a new minibrowser instance for that URL.
- Valid values: true, false, yes, no, on, off.
- track: Determine if the URL will be loaded as replaceable on top of the minibrowser history stack or not.
- Valid values: true, false, yes, no, on, off.
- new_context: Creates a new minibrowser instance for that URL.
- Valid Subtags
Here are the valid tags that can be nested into URL:- If, Elif, Else:Â see Conditional blocks
- If, Elif, Else:Â see Conditional blocks
- SoftKey
- Description: Identifies a virtual key that is pressed when the menu entry is selected.
- Valid Values: Any valid soft key
- ImageÂ
- Description: Use an external image as icon for the menu entry
- Valid Value: Any valid image URL
The Image supports the attribute default containing the URL of a fallback image to display if the given image fails to load. if no image is given as default, the icon on the left side of the text will be left blank (transparent)
See an Image example below
- IconType - In addition to Icon and Image, the more recently added IconType subtag allows the option to use pre-defined icons existent on the phone by using their internal names. See details about this tag here.
- ExtraIconType and ExtraIconType2 - see details here.
- SubText -Â see details here.
- ExtraText - see details here
- Action
- Description: action to be performed when the menu entry is selected.
- Valid values: admin_mode, backlight_active, backlight_idle, buddies, change_pin, contrast, expansion_module_backlight, expansion_module_backlight_idle, label_backlight_active, label_backlight_idle, label_contrast, ldap, msw, reboot, reset_settings, ringtone, show_status_messages, support, sysinfo, user_mode, uxm_backlight_active, uxm_backlight_idle, uxm_contrast, vlan_id, vlan_qos, vlan_reset, vol_handset, vol_headset, vol_ringer, vol_speaker, webserver_pass, webserver_user, xsi
- See example here
- ItemData
- Description: Define data to be saved beneath this menu-line.
The ItemData can contains the following tags:- Repeat: see Repeats
- If, Elif, Else:Â see Conditional blocks
- Variable: Defines a variable. Allowed 0 or more times. The Variable tag must have a tag called name containing the name of the variable and optionally a tag called value containing the value of the variable. When the value is not set or set as empty (i.e.:value="") the variable will be deleted
- Description: Define data to be saved beneath this menu-line.
- <If>,<Elif>,<Else>
InputField
See InputField above.
Examples
Simple example
Result:XML code:<SnomIPPhoneMenu> <Menu name="name attr menu"> <Title>2nd layer title tag</Title> <MenuItem name="2nd,1st menuitem"/> <MenuItem name="2nd,2nd menuitem"/> </Menu> <MenuItem name="name attr menuitem"/> <MenuItem name="name tag menuitem"/> </SnomIPPhoneMenu>
Image
Result:XML code:<SnomIPPhoneMenu> <MenuItem name="local:snom photo unknown "> <Image default="file:///bmp/colored/snom_photo_unknown.png">file:///bmp/colored/snom_photo_unknown.png</Image> </MenuItem> <MenuItem name="local:conference_one.png"> <Image default="file:///bmp/colored/snom_photo_unknown.png">File:///bmp/colored/input_info_images/conference_one.png</Image> </MenuItem> <MenuItem name="url image1"> <Image default="file:///bmp/colored/snom_photo_unknown.png">http://docs.snom.io/xml_minibrowser/examples/img/Icon_radiation.png</Image> </MenuItem> <MenuItem name="invalid url/image without default"> <Image>http://randomurl.com/random_image.png</Image> </MenuItem> <MenuItem name="invalid url/image"> <Image default="file:///bmp/colored/snom_photo_unknown.png">http://randomurl.com/random_image.png</Image> </MenuItem> </SnomIPPhoneMenu>
Icon
Result:XML code:<SnomIPPhoneMenu> <Title>Icon examples</Title> <MenuItem name="Accept call icon"> <Icon>file:///bmp/colored/fkey_icons/24x24/accept_call.png</Icon> </MenuItem> <MenuItem name="Away icon"> <Icon>file:///bmp/colored/contact_state_icons/36x36/away.png</Icon> </MenuItem> <MenuItem name="Microphone example"> <Icon>file:///bmp/colored/settings_window_icons/30x30/microphone.png</Icon> </MenuItem> </SnomIPPhoneMenu>
IconTypes
This example shows the usage of IconSize and IconType. The example was tested on Snom D375 with firmware version 10.1.64.14.
The last two menu entries will show the default icon (Snom logo) instead of the inserted icon. The reason for this is because the IconSize is set to XXS, meaning the height of the icon used must be 18. But looking at the chosen icons:- kIconTypeContactStateDND exists in size 18, see contact_state_icons. The icon will work correctly
- kIconTypeSymbolHold also exists in size 18, see call_icons. The icon will work correctly
- kIconTypeCallHistoryMissed does not exist in size 18 - see icontype_icons. The icon will not work correctly with size 18, it needs IconSize to be 24 ( =XS)
kIconTypeOverlayHold also does not exist in size 18 - see call_overlay. The icon will not work correctly with size 18, it needs the size to be 96, 84, 72, 60, 48 or 36
<SnomIPPhoneMenu> <IconSize>XXS</IconSize> <MenuItem name="Example with correct IconSize"> <IconType>$(icon_type_enum:kIconTypeContactStateDND)</IconType> </MenuItem> <MenuItem name="Another example with correct IconSize"> <IconType>$(icon_type_enum:kIconTypeSymbolHold)</IconType> </MenuItem> <MenuItem name="Example with incorrect IconSize"> <IconType>$(icon_type_enum:kIconTypeCallHistoryMissed)</IconType> </MenuItem> <MenuItem name="Another example with incorrect IconSize"> <IconType>$(icon_type_enum:kIconTypeOverlayHold)</IconType> </MenuItem> </SnomIPPhoneMenu>
Result:
If we replace "<IconSize>XXS</IconSize>" with "<IconSize>XS</IconSize>", the third menu entry will work:
ExtraIconType and ExtraIconType2
This example shows the usage of Extra IconType and ExtraIconType2. The example was tested on Snom D375 with firmware version 10.1.64.14.
In order for the ExtraIcons to work, the chosen icons must exist in size 18. In the below example, the second ExtraIconType2 ($(icon_type_enum:kIconTypeCallHistoryMissed)) does not work because kIconTypeCallHistoryMissed does not exist in size 18 (see icontype_icons)<SnomIPPhoneMenu name="ExtraIconTypes"> <MenuItem name="Example - correct"> <ExtraIconType>$(icon_type_enum:kIconTypeRinging)</ExtraIconType> <ExtraIconType2>$(icon_type_enum:kIconTypeMenuReboot)</ExtraIconType2> </MenuItem> <MenuItem name="Example - ExtraIconType2 incorrect"> <ExtraIconType>$(icon_type_enum:kIconTypeRinging)</ExtraIconType> <ExtraIconType2>$(icon_type_enum:kIconTypeCallHistoryMissed)</ExtraIconType2> </MenuItem> </SnomIPPhoneMenu>
Result:
SubText and ExtraText
XML code:<SnomIPPhoneMenu> <MenuItem name="Text example"> <ExtraText>ExtraText here</ExtraText> <SubText>SubText here</SubText> </MenuItem> </SnomIPPhoneMenu>
Result:
Menu customizationÂ
<SnomIPPhoneMenu name="Menu customization"> <Menu name="Default Menu"> <MenuItem name="Some MenuItem"> </MenuItem> </Menu> <Menu name="Customized Menu"> <IconType>$(icon_type_enum:kIconTypeContactStateDND)</IconType> <ExtraIconType>$(icon_type_enum:kIconTypeRinging)</ExtraIconType> <ExtraIconType2>$(icon_type_enum:kIconTypeMenuReboot)</ExtraIconType2> <MenuItem name="Some MenuItem"> </MenuItem> </Menu> </SnomIPPhoneMenu>
Result:
InputField
XML code:<SnomIPPhoneMenu> <Menu name="normal menu" speedselect="off"> <Title>normal menu title</Title> <InputField> <Handler event="keypress">file:///xml/text.xml#var:text=$[current_input]</Handler> <Handler event="timeout">file:///xml/text.xml#var:text=TIMEOUT:$[current_input]</Handler> <Timeout>3000</Timeout> <Minimum>3</Minimum> <Prompt>Input:</Prompt> <Key>ENTER</Key> </InputField> <Menuitem name="Judith Bernhardt" /> <Menuitem name="Leigh Vargas" /> <Menuitem name="William Kosinski" /> </Menu> </SnomIPPhoneMenu>- Result:
Action
XML Code<SnomIPPhoneMenu> <MenuItem name="show system information"> <Action>sysinfo</Action> </MenuItem> <MenuItem name="change handset volume"> <Action>vol_handset</Action> </MenuItem> </SnomIPPhoneMenu>Result:
- InputField on D8xx with new PhoneUIXML code
<IPPhoneMenu> <Title>Example InputField</Title> <SoftKeyItem> <Name>F4</Name> <Label>Save</Label> <Url>phone://mb_nop#flush&go_back</Url> </SoftKeyItem> <InputField> <ExtraText>fkey_label1</ExtraText> <DefaultValue>$(set:fkey_label1)</DefaultValue> <Timeout>100</Timeout> <Handler event="timeout">phone://mb_nop#setcache:fkey_label1=$[current_input]</Handler> </InputField> <InputField> <ExtraText>fkey_label2</ExtraText> <DefaultValue>$(set:fkey_label2)</DefaultValue> <Timeout>100</Timeout> <Handler event="timeout">phone://mb_nop#setcache:fkey_label2=$[current_input]</Handler> </InputField> <InputField> <ExtraText>fkey_label3</ExtraText> <DefaultValue>$(set:fkey_label3)</DefaultValue> <Timeout>100</Timeout> <Handler event="timeout">phone://mb_nop#setcache:fkey_label3=$[current_input]</Handler> </InputField> </IPPhoneMenu> - Result
Further Information
Related articles
Overview
Content Tools
Tasks
