Edit Menus and Questions about Menus

[stuckless]

This is not meant to be the "user guide" for editing menus, but for now, it hopefully it will serve as guidance for those wishing to customize the menus in Phoenix.

Phoenix menus are currently stored in STVs/Phoenix/Menus/ and there are number of menu files there. The names of the files are not important, but we've logically grouped them into

• ContextSensitiveMenus.xml - The menus that show up in 'context' to an operation
• GlobalMenu.xml - Main menu you see when you first hit 'home'
• LandingMenu.xml - The landing zone menus
• OptionsMenu.xml - Main options menu (ie, admin tools, etc)
• StatusMenu.xml - Menu that shows in the Info screen.

Take some time and browse the menus just to see a bit about the organization.

Never edit the menus in the main STVs/Phoenix/Menus/ area, instead create a new menu file in the userdata/Phoenix/Menus/ area. For example, if you wanted to modify the LandingMenu, then you can copy the existing STVs/Phoenix/Menus/LandingMenu.xml to userdata/Phoenix/Menus/LandingMenu.xml, and edit that file. We will constantly update and overwrite the main xml files, so never edit those, but rather copy to the userdata area, and edit from there. I can't stress this enough

If you are familiar with nielm's Dynamic Menus, then our menus are similar, but NOT the same.

Each menu is defined in a <menu> tag, and menu can contain <menuItem>, <menu> and <view> children. When you define a <menu> or <view> as a child then it becomes a submenu.

<menu> Attributes

• name - unique name for the menu. Must be unique for ALL menus
• label - is shown in the UI
• background - background image (optional)
• visible - true|false if you want to show/hide a menu

A <menu> can have <menuItem> or <menu> children.

<menuItem> Attributes

• name - unique name for the item.
• label - is shown in the UI
• icon - icon to use for the menu
• visible - true|false if you want to show/hide a menu item

A <menuItem> can have several actions. Actions are perfomed on a <menuItem> when a user selects an item. The following actions are supported

• <screen> - go to to defined SageTV screen name (commonly referred to as Menus in SageTV, but not to be confused with our menus)
• <eval> - evaulate a sagetv expression, normally used to setup some variables before calling <screen>
• <sageCommand> - issue a sage command, such as Back.
• <exec> - execute a command

Adding New Menu Items
Phoenix uses "fragments" to contribute menu items (or complete menus) to other existing menus. So, if you needed to add a new menu to the landing zone, you'd create a fragment that contributes a new item. If you want to replace an item in the landing zone, for example, "TV", then create a new fragment for your new menu item, and then hide the core one.

A menu fragment must be stored in an xml file in the userdata/Phoenix/Menus/ directory. The filename is not important, but the structure must be like the following...

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE menus SYSTEM "menus.dtd">
<menus>
      <fragment parentMenu="phoenix.menu.lz.videos" insertBefore="phoenix.menu.lz.videos.blueraydefaultbrowser">
            <menuItem name="MC_Movie_Archive_Menu" label="Archived Movies" visible="true">
                  <description>Archived Movies</description>
                  <eval>AddGlobalContext("DefaultView","MC_Movie_Archive")</eval>
                  <screen name="Phoenix Universal Media Browser" />
            </menuItem>
      </fragment>
</menus>

parentMenu is the menu id of the menu that will receive this new item. insertBefore (or insertAfter) is the menu item id before/after you want to insert your new item. If you don't specify insertBefore or insertAfter, then the item goes at the end, and you use the menu editor buit into phoenix to move the item where you need it.

the <menuItem> is your complete menu item definition.

After you add new menu items, you must reload the menus for the new file to be picked up.

You can have multiple <fragment> elements per menu file.

Some Examples

Menu Item that launches the Phoenix UMB for a given view name (view names are defined in the vfs.xml)

    <menuItem name="browse" label="Browse TV" visible="true" icon="gTVMenuIcon">
         <eval>AddGlobalContext( "DefaultView" , "tvrecentactivity" )</eval>
         <screen name="Phoenix Universal Media Browser" />
    </menuItem>

Menu Item that launches an external program

<menuItem name="customitem.command.firefox" label="Run Firefox">
     <exec cmd="C:\Program Files\Mozilla Firefox\firefox.exe" />
</menuItem>

Menu that sets a configuration property

	<menuItem label="Horizontal" visible="true">
		<eval>phoenix_config_SetUserProperty("LandingZone", "Horizontal")</eval>
		<screen name="Phoenix Landing Zone"/>			
	</menuItem>

Menu that has a child menu

  <menu name="PhoenixUMB-SingleList" label="Universal Media Browser Options" background="OptionsMenuBackground.jpg" type="TV">
    <description>"Context Sensitive Menu"</description>
    <menuItem label="${&quot;List Search Mode: &quot; + phoenix_api_GetUserProperty( &quot;listSearchMethod&quot; , &quot;Percent&quot; )}" visible="true">
      <eval>phoenix_api_SetUserProperty( "listSearchMethod", If(phoenix_api_GetUserProperty( "listSearchMethod" , "Percent" ) == "Percent" , "RegEx", "Percent") )</eval>
      <eval>Refresh()</eval>
    </menuItem>
	  <menu name="DefaultUMB" label="Select Default Browser"  background="OptionsMenuBackground.jpg" type="TV" visible="true">
		<menuItem label="Single List" visible="true">
			<eval>AddStaticContext( "DefaultView" , CurrentViewName )</eval>
			<eval>phoenix_config_SetUserProperty("DefaultUMB", "SingleList")</eval>
			<screen name="Phoenix Universal Media Browser"/>			
		</menuItem>
		<menuItem label="Double List" visible="true">
			<eval>AddStaticContext( "DefaultView" , CurrentViewName )</eval>
			<eval>phoenix_config_SetUserProperty("DefaultUMB", "DoubleList")</eval>
			<screen name="Phoenix Universal Media Browser"/>			
		</menuItem>
		<menuItem label="Horizontal List" visible="true">
			<eval>AddStaticContext( "DefaultView" , CurrentViewName )</eval>
			<eval>phoenix_config_SetUserProperty("DefaultUMB", "HorizontalList")</eval>
			<screen name="Phoenix Universal Media Browser"/>			
		</menuItem>
	  </menu>
    <menuItem label="Change Media View" visible="true">
      <eval>AddGlobalContext( "OptionsSubmenu" , "View Selector" )</eval>
      <eval>Refresh()</eval>
    </menuItem>
  </menu>

MenuItem that uses a Sage Expression

<menuItem label="${&quot;List Search Mode: &quot; + phoenix_api_GetUserProperty( &quot;listSearchMethod&quot; , &quot;Percent&quot; )}" visible="true"/>

MenuItem that is conditional based on a client property

<menuItem lable="Advanced Views" visible="prop:client:phoenix/vfs/advancedViewsEnabled"/>

NOTE: Most menu/menuItem attributes will accept a Sage Expression, ie ${Expression}, or a property reference, ie, "prop:SCOPE:PROPERTY" where SCOPE is 'client', 'server' or 'user', and PROPERTY is a property key.


Menu that built using a view

	<view name="lz_featuredfavorite" label="Featured" contextVar="MediaFile" preload="true" limit="6">
		<eval>Watch(phoenix_media_GetSageMediaFile(MediaFile))</eval>
		<screen name="Phoenix MediaPlayer OSD" />
	</view>

Again, this is not a complete guide, but just a reference to get started. I'll try to do the same for the VFS. Be sure to check out the existing menu files, since they already will contain lots of examples of how to do things.

Also, keep in mind that for now, if you change the menus, then you'll need to use BMT (Configure -> Refresh Configurations) to reload the menus. We will, at some point offer in STV editing of menus, but you can see it's hard to allow for complete editing of menus, since the menus do so much.


Advanced Menu Features

Conditionally show a menu ONLY for a given client

<menu name="..." visible="${GetUIContextName()==&quot;00e04c77e4ee&quot;}">
...
</menu>

The above fragment assumes that you know your extender id (in this case 00e04c77e4ee). You can also use != instead of == to indicate 'not equal'.

The visible attribute on any menu or menuItem can accept an expression as along as it is enclosed in ${...}. Using expressions you can conditionally show/hide menus/menuItems for just about any case.

You could write an expression that only make a menu visible about 9:00pm at night. Or an expression that only shows a menu item when the current user is 'bill', etc. Expressions, while requiring some programming knowledge, are a very cool way to make your menus even more dynamic. And if you master expressions here, then the vfs uses the exact same syntax and expressions.

Some more common expressions that you might use...
Conditional based on a property

visible="${phoenix_config_GetProperty("SOME_PROPERTY_FROM_SAGE_PROPERTIES")}"

or

visible="prop:client:SOME_PROPERTY_FROM_SAGE_PROPERTIES"

[bialio]

From any of the landing zones you can hit Home twice and it will reload the menus (and VFS as well).

btl.

[stuckless]

Originally Posted by bialio

From any of the landing zones you can hit Home twice and it will reload the menus (and VFS as well).

btl.

Cool... I did not know that

[stuckless]

Rather than copying a complete menu xml file and then just editing it to add a new item, you can use the new menu fragment tag to simply insert your custom menu/menuItem into any of our system menus. For this to work, you'll need to open our menu xml file (ie, LandingMenu.xml) and know the menu to which you want to add, and the menu item that you want to insert next to.

For example, if you wanted to add your own menu item before the "All Movies" item in the "Videos" section of the Landing Zone, your fragment might look like this.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE menus SYSTEM "menus.dtd">
<menus>
   <fragment parentMenu="phoenix.menu.lz.videos" insertBefore="phoenix.menu.lz.videos.alltitlesdefaultbrowser">
      <menuItem name="beachbody" label="Beach Body Insanity" visible="${GetUIContextName()==&quot;00085c53c6a9&quot;}">
         <description>Beach Body Insanity</description>
         <eval>AddGlobalContext("DefaultView","sls_beachbody")</eval>
         <screen name="Phoenix Universal Media Browser" />
      </menuItem>
   </fragment>
</menus>

Basically the concept behind a fragment is that you want to add to an existing menu but you don't want to replace the entire menu. Today, if you copy the LandingMenu.xml and then add a single item, then you'll never see another update from the core LandingMenu, since your copy will replace it. Using fragments, you can easily just insert items before or after existing items in any given menu.

[ellweber]

Originally Posted by stuckless

<menuItem> Attributes
name - unique name for the item.
label - is shown in the UI
icon - icon to use for the menu
visible - true|false if you want to show/hide a menu item

A <menuItem> can have several actions.  Actions are perfomed on a <menuItem> when a user selects an item.  The following actions are supported
<screen> - go to to defined SageTV screen name (commonly referred to as Menus in SageTV, but not to be confused with our menus)
<eval> - evaulate a sagetv expression, normally used to setup some variables before calling <screen>
<sageCommand> - issue a sage command, such as Back.
<exec> - execute a command

Some Examples

Hi Stuckless,

Would you mind posting an example of a menu item the includes an executable. I would like to be able to call a batch file from the UI.

Thanks,

Lynn

Nevermind! I figured it out now. Lynn

[stuckless]

@Lynn - This would be an example...

<menuItem name="lynn.command.firefox" label="Run Firefox">
     <exec cmd="C:\Program Files\Mozilla Firefox\firefox.exe" />
</menuItem>

There is an optional os="Windows|Linux" attribute on the <exec> element as well but you shouldn't need that.

EDIT: Sorry I took too long...I'm at work

[ellweber]

Thanks for the pronto response, Stuckless. I was stuck in a syntax hole but I climbed out just about when you responded. I have Sage working better than ever, thanks for all of your efforts. I hope it lasts!

I am a bit confused about when the Phoenix UI reloads the menu from the User directory, I have tried stimulating it from BMT and just waiting but a restart of Sage Client seems to be the most consistent way.

Lynn

[stuckless]

Originally Posted by ellweber

Thanks for the pronto response, Stuckless. I was stuck in a syntax hole but I climbed out just about when you responded. I have Sage working better than ever, thanks for all of your efforts. I hope it lasts!

I am a bit confused about when the Phoenix UI reloads the menu from the User directory, I have tried stimulating it from BMT and just waiting but a restart of Sage Client seems to be the most consistent way.

Lynn

Lynn, if you hit home twice on your remote, then it will reload all menus/vfs. Or you can do it from the bmt web ui as well.

[bialio]

Actually home twice doesn't work any more. But there is a menu option in the Global Options Menu: "Options & Configuration -> Reload Menus, Views, Config" that will reload them.

btl.

[ellweber]

I thought I had tried that Bialio but perhaps it was while I was still tangled up in my syntax problems! Again, thaks for the support...

[HokiePerogi]

Is it possible to use menu fragments to override the view of an out of the box (OOTB) menu or hide an OOTB menu? This would be might helpful!

[PiX64]

U can hide menus from the default ui by going to the options screen. U can also add fragments for sub menus and "override" the default menu. U can pretty much customize ever aspect of the landing zone.

[PiX64]

Post an example or idea of what u want to do and we can walk you through how to do it.

[stuckless]

Originally Posted by HokiePerogi

Is it possible to use menu fragments to override the view of an out of the box (OOTB) menu or hide an OOTB menu? This would be might helpful!

Yes, you can.

In the latter case, you can simply hide the menu using the menu editor that is built into phoenix (just hit Options, then select Options, and then Confgure Landing Zone).

In the first case, just create a new menu fragment and give the menu "name" the same as the menu that you want to override. When you do this, you are basically creating a new menu/menuItem that replaces the standard one. Peronally what I'd do is create a new menu fragment and inject it into an existing menu, and then use the menu editor to show/hide the new/old menu item. That way you can still have access to the old menu item.

If the menu that you want to configure is not in the landing zone, then you can use the menu fragements to hide a menuItem as well. Simply create a menu fragment and define a menu/menuItem with same name as the menu that you want to override and use visible="false", which will hide the menu/menuItem.

Hope this makes sense.

[HokiePerogi]

Originally Posted by stuckless

Yes, you can.

In the latter case, you can simply hide the menu using the menu editor that is built into phoenix (just hit Options, then select Options, and then Confgure Landing Zone).

In the first case, just create a new menu fragment and give the menu "name" the same as the menu that you want to override. When you do this, you are basically creating a new menu/menuItem that replaces the standard one. Peronally what I'd do is create a new menu fragment and inject it into an existing menu, and then use the menu editor to show/hide the new/old menu item. That way you can still have access to the old menu item.

If the menu that you want to configure is not in the landing zone, then you can use the menu fragements to hide a menuItem as well. Simply create a menu fragment and define a menu/menuItem with same name as the menu that you want to override and use visible="false", which will hide the menu/menuItem.

Hope this makes sense.

That makes complete sense. I hadn't yet played around with the hiding of menus via the UI. Now that I've done that, I think I'll just hide the OOTB menus and display the ones that I want. Thanks!

[eopian]

Originally Posted by stuckless

<menuItem name="lynn.command.firefox" label="Run Firefox">
     <exec cmd="C:\Program Files\Mozilla Firefox\firefox.exe" />
</menuItem>

I used this code to Launch PowerDVD on my main client, but how do I add the native Sage command for PowerOff (so it will minimize Sage while I am using PowerDVD). I already have PowerDVD setup so that when I exit, it will PowerOn Sage.

[MeInMaui]

Originally Posted by eopian

I used this code to Launch PowerDVD on my main client, but how do I add the native Sage command for PowerOff (so it will minimize Sage while I am using PowerDVD). I already have PowerDVD setup so that when I exit, it will PowerOn Sage.

Try adding this:

<sageCommand name="Power Off" />

I haven't tested it but it should work.

[stuckless]

As Mike said

So the complete entry should look like this...

<menuItem name="lynn.command.firefox" label="Run Firefox">
     <exec cmd="C:\Program Files\Mozilla Firefox\firefox.exe" />
     <sageCommand name="Power Off" />
</menuItem>

[eopian]

Awesome, thanks guys!

[JonTom]

I'm trying to pass a parameter to a batch file but it's not working.

<exec cmd="C:\Program Files (x86)\SageTV\SageTV\userdata\Phoenix\RipConvert.bat" />

works fine but

<exec cmd="C:\Program Files (x86)\SageTV\SageTV\userdata\Phoenix\RipConvert.bat NicholasVideos" />

never triggers the script.

Any ideas?