Creating Jive Menus

[James]

Is the set of options that Jive accepts to create menus documented anywhere? I couldn't find it on the wiki - would it be useful to document there?

So I have some questions on the options I've seen and used:
1) what's the difference between actions->do and actions->go?
2) what's the difference between ___INPUT___ and ___TAGGEDINPUT___?
3) If showing radio buttons, is the item with radio=>1 supposed to show up already checked? (If so, it seems to be broken)
4) what's 'offset' for? (It always seems to be zero)
5) what does params => {menu => 'nowhere'} do?
6) what does itemsParams => 'params' do?

James

[erland]

Is the set of options that Jive accepts to create menus documented anywhere? I couldn't find it on the wiki - would it be useful to document there?

Here is some documentation:
http://svn.slimdevices.com/*checkout*/trunk/jive/src/pkg/jive/doc/html/jiveMLON.html?root=Jive




1) what's the difference between actions->do and actions->go?

See the link above



2) what's the difference between ___INPUT___ and ___TAGGEDINPUT___?

See the link above



3) If showing radio buttons, is the item with radio=>1 supposed to show up already checked? (If so, it seems to be broken)

No idea



4) what's 'offset' for? (It always seems to be zero)

When the Jive remote requests a menu it adds two parameter to the CLI command. An offset and a number of items parameter.
If you have a menu that contains a lot of items, you will see that Jive will first request it as:
xxx yyy 0 100
And then:
xxx yyy 100 100

That is, it requests 100 each time. To make it work this way it is also important that you send back the total number of items in the count variable even though the item_loop just contain 100 items. If the item_loop contains the same amount of items as the count result parameter, it will only do one request.

I'm guessing that the purpose is to make a 10000 item list visible on the remote after the first 100 items has been retrieved and then retrieve the next 9900 items in the background.



5) what does params => {menu => 'nowhere'} do?

I'm not completely sure, but I think this is just a parameter that SqueezeCenter CLI command understands. The CLI handlers in SqueezeCenter browse commands checks if a "menu" parameter exists to decide if they should return a Jive CLI response or a normal response. So all SqueezeCenter browse menus needs a "menu" parameter to return a CLI response that Jive understands. I think "nowhere" is just used when you like to indicate that you wan't a Jive response but doesn't want to set the menu parameter to something special.



6) what does itemsParams => 'params' do?

It's explain in the link I mentioned above.

I believe it's used together with the "base" block to make it possible to put things that are similar for all returned items in one place and just define additional things for each item. itemsParams=>'params' means that it will look for additional parameters in a result parameter called 'params' for each item in the item_loop.

[bklaas]

Is the set of options that Jive accepts to create menus documented anywhere? I couldn't find it on the wiki - would it be useful to document there?

So I have some questions on the options I've seen and used:
1) what's the difference between actions->do and actions->go?
2) what's the difference between ___INPUT___ and ___TAGGEDINPUT___?
3) If showing radio buttons, is the item with radio=>1 supposed to show up already checked? (If so, it seems to be broken)
4) what's 'offset' for? (It always seems to be zero)
5) what does params => {menu => 'nowhere'} do?
6) what does itemsParams => 'params' do?

James

There is documentation in your jive checkout--

src/pkg/jive/doc/html/jiveMLON.html
(I have no idea what jiveMLON stands for)

1) do is an action that is executed without pushing the Jive UI to a new window. go is an action that executes and pushes the Jive UI to the next window.

2) Two different ways of formatting data sent to SC cli.

from jiveMLON.html

params
Hash of parameters, f.e. {sort = new}. Passed to the server in the form "key:value", f.e. 'sort:new'.

* The value "__INPUT__" is replaced by any user entered data.
* The value "__TAGGEDINPUT__" is replaced by user entered data in a "key:value" format. For example, the param foo = "__TAGGEDINPUT__" would be replaced by 'foo:<user-entered input>'

3) Yes, that's how it's supposed to work, and you are right-- it's broken. Opened bug 6045 on it http://bugs.slimdevices.com/show_bug.cgi?id=6045

4) I don't know what "offset" means either and it isn't covered in the JiveMLON doc. Maybe if Fred is lurking on this thread he can clear that up. I'd like to know the answer to that too.

5) everything I've tried to type for an answer here has come out convoluted and not helpful. Perhaps someone else can pipe in on that one.

6) from jiveMLON doc, though this may not make it any clearer, as it doesn't for me...

itemParams
In base level commands, this defines the name of the field in the item <actions_fields> that must be used to complete the command for a particular item. See the example below.

#!/ben

[erland]

1) do is an action that is executed without pushing the Jive UI to a new window. go is an action that executes and pushes the Jive UI to the next window.


This morning I was trying to open a menu with play-hold action, I posted also a message in the Developers forum regarding it since I didn't get it to work.

Is the "go" action the only one that pushes Jive into a new window ?
Does this mean that I can use different remote keys to open different menus from the same item ?
I'm trying to do something similar as the "play.hold" key in the player interface that launches the mixer menu.

[bklaas]

3) Yes, that's how it's supposed to work, and you are right-- it's broken. Opened bug 6045 on it http://bugs.slimdevices.com/show_bug.cgi?id=6045


I fixed bug 6045 in Jive checkin r821
#!/ben

[bklaas]

This morning I was trying to open a menu with play-hold action, I posted also a message in the Developers forum regarding it since I didn't get it to work.

Is the "go" action the only one that pushes Jive into a new window ?
Does this mean that I can use different remote keys to open different menus from the same item ?
I'm trying to do something similar as the "play.hold" key in the player interface that launches the mixer menu.

Erland, sorry I didn't respond to your dev thread, but I'm afraid the short answer to your problem is that at this time there is no facility for doing what you want to do. Right now we have "go" and we have "do".

#!/ben

[James]

Very helpful - thanks guys!

James

[erland]

Erland, sorry I didn't respond to your dev thread, but I'm afraid the short answer to your problem is that at this time there is no facility for doing what you want to do. Right now we have "go" and we have "do".

It would be good if it was possible to specify if a new window should be opened or not with a result parameter instead of hardcoding it to specific key codes.

[erland]

This morning I was trying to open a menu with play-hold action, I posted also a message in the Developers forum regarding it since I didn't get it to work.

Is the "go" action the only one that pushes Jive into a new window ?
Does this mean that I can use different remote keys to open different menus from the same item ?
I'm trying to do something similar as the "play.hold" key in the player interface that launches the mixer menu.

Just for information, I wrote an enhancement request regarding this:
http://bugs.slimdevices.com/show_bug.cgi?id=6055

[Fred]

Maybe if Fred is lurking on this thread...

I am :)


I have no idea what jiveMLON stands for

At some point there were intense debates about which markup to use, OPML or JSON. The data model was the same however, so I started to document stuff in a document called jiveMLON (i.e. jive OPML JSON) and it stuck (mainly because nobody cares what this is called - if anyone did, it would get a better name :).


I don't know what "offset" means either and it isn't covered in the JiveMLON doc

erland did a good job explaining it, but it's basically the index of the first item in the current data block in the overall complete list, whose cardinality is given by "count". In other terms, it's used for paging in long lists.


5) what does params => {menu => 'nowhere'} do?

We needed a way to indicate to queries the format of the output (since the same request can be used for CLI and JSON calls). I arbitrarily decided on "menu" as an indicator JSON was required. Depending on the query, the value of the menu param may or not be significant. Its used by DB queries to capture the next step in the descent (genres->artists->albums->tracks, genres has menu:artists). The best is to check the query called.



6) what does itemsParams => 'params' do?

It's "data compression". The JiveMLON format can describe a regular menu, in which the action is potentially different for each menu item. However in a typical descent (genres->artists->...), you're doing the exact same thing for each genre, the only difference is the id acted upon.

From that comes the "base" command idea, which indicates what to for each item. In general, it must be completed by one particular parameter specific to each item. Rather than arbitrarily decide on a name for an item value that would constitute extra parameters for a base command, I have allowed the jiveMLON writer to provide in param "itemsParams" the name of the field in each item that constitutes parameters for the base command (the intention was to avoid name clashes).

So when you click on an item, Jive checks for an action defined in the item, if not it looks for one in the header. If an action is defined in the header and a value A is provided in itemsParams, Jive looks for a key A in the item and adds its value to the command hash before sending it.


It would be good if it was possible to specify if a new window should be opened or not with a result parameter instead of hardcoding it to specific key codes.

There have been numerous debates on the approach to use for Jive, how much of it was under SC control, how much of it it did "by itself". What you're asking here is for SC to have even more control, so that an interface that would open a window when clicking on pause would be possible. Holding volume down would naturally close it :)

IMHO, we should use the screen real estate of Jive to the benefit of the user interface and not rush to re-impement on it the obscure shortcuts that the SqueezeBox much more limited interface(s) made necessary. In other terms, the current format forces plugin and SC authors into a coherent approach where only the center button opens windows. That's why I purposefully avoided doing things how bug 6021 proposes when I wrote the format.

I am only explaining this to provide the background. Ben and Dean are the ones to cajole to get it your way :)

HTH

Fred

[erland]

It would be good if it was possible to specify if a new window should be opened or not with a result parameter instead of hardcoding it to specific key codes.

IMHO, we should use the screen real estate of Jive to the benefit of the user interface and not rush to re-impement on it the obscure shortcuts that the SqueezeBox much more limited interface(s) made necessary. In other terms, the current format forces plugin and SC authors into a coherent approach where only the center button opens windows. That's why I purposefully avoided doing things how bug 6021 proposes when I wrote the format.

I'm not sure if you understand what I was trying to say with 6021, because I think we actually want almost the same thing.

I do not want obscure shortcuts which differs for each plugin, where one plugin launches it's context menus with play-hold and another with add-hold and a third with pause-hold.

What I want is a generic context menu that would work on all items. Pretty much the same was as a standard Windows mouse have two buttons. The user know what happens when he clicks on the left button or the right button. A left button click will open a folder while a right button click will open a menu that shows available operations that can be executed on the selected folder.

This way there is no need for obscure shortcuts, we just need two, the "browse into" menu (launched with middle click), the "open context menu" (launched with some other key). The best solution IMO would be if the Jive hardware had a "Menu" or "Functions" button or something similar, but as long as that isn't the case some obscure shortcut like play-hold or middle-hold might be good enough for the play-hold. The important thing is just that it is the same shortcut everywhere in the interface.

[Fred]

The best solution IMO would be if the Jive hardware had a "Menu" or "Functions" button or something similar, but as long as that isn't the case some obscure shortcut like play-hold or middle-hold might be good enough for the play-hold. The important thing is just that it is the same shortcut everywhere in the interface.

I agree. Could we have "play-hold" and "play-hold-go", thus forcing the shortcut to be the same for all plugins ?

[erland]

I agree. Could we have "play-hold" and "play-hold-go", thus forcing the shortcut to be the same for all plugins ?

I'm not sure I understand what you are saying, isn't the idea that we want the behaviour to be the same for all plugins ? If we have both play-hold and play-hold-go it would that mean that the plugin developers can choose what to do when holding play down ?
I assume you with "play-hold-go" mean that the user holds play down for a while.

To me the logical behaviour would be:
- Single click on middle button ("go" or "do") - Either moves into a new window or executes a command in place without opening a new window
- Holding middle button down for a while ("go-hold") - Always open a new window
- Single click on play ("play") - Executes a command in place without opening a window
- Holding play down for a while ("play-hold") - Executes a command in place without opening a window. (I'm not sure "play-hold" is needed though, see more regarding this below.)

The result would be that the user knows that if he single clicks on the middle button he gets the primary action, if he double clicks he always get a list of additional options available (the context menu).

As I see it, the only reason that holding play down should result in this is if we like to keep the previous behaviour where holding play launches mixes. Mixes is almost the same thing as the context menu, especially if there are several different mixers available. I think the logical way to access mixers would actually be as an item in the context menu.

I'm not even sure the "play-hold", "add-hold" event is required at all if we get the context menu functionality. In this case it would make more sense to put the command accessed by holding play or add down a while in the context menu instead. The fwd/rew buttons doesn't really have to be possible to redefine per menu, IMHO they should result in the same thing where ever they are pressed. I think this also might be the case for the pause key which always should mean pause or stop dependent on if you hold it down a while or not, no reason to redefine this for a specific menu I think.

Anyway, the important thing to me is really that I have the possibility to both:
- "move into the currently selected menu item"
- "show a list of available functions" for the currently selected menu item"

It doesn't really matter how these are trigged, but it would be preferable for the user if they were trigged by the same key action in all menus.


As mentioned in 6021, it is also important that there is a way for third party plugins to register it's own menu items on the context menu in the standard browse menus. Mixers is one type of menu item, but I can also see other kinds of items from third party plugins that would be usable.