RE: plugin XML files

["John B" <home-automation@xxxxxxxxxxxxxxxx>]

Hi Gerry,

> 1) Root node agnosticism
> I really don't think it's a biggie, but it would be nice if
> the root node was not "<xplhalmgr-plugin>".  I know it
was
> originally created for xPLHAL, but as the role of this file
> grows as high level definer of xPL capabilities, a more
> generic root node would have been nice.  That said, there
> doesn't seem like much point in changing it now.

I have no problem with this - I was thinking the same thing only
recently.

It appears that xPLHal currently ignores the name of the root node
anyway, so how about we change it to just <xpl-plugin>.

> 2) Device information
> I was surprised at how little information about a device
> there is (well, demographic info -- there is plenty of other
> info).  I know this was part of the xPLDiag discussion and
> such, so rehashing here isn't worth it.  However, it would be
> nice to eventually add a "friendly" description, a current
> version, and a URL for the device in.

OK - how about:

<device id="johnb-winamp"
description="An xPL plug-in for the Winamp Media Player"
version="1.3"
url="http://www.xpl.myby.co.uk/info/xplwinamp/";>
...
</device>

>
> 3) Config item regular expressions
> Big fan of regular expressions myself.  However, it's not
> clear which set of regular expressions are supported here.

Whatever .NET supports :-)

Remember this file was only ever intended for use with xPLHal, so there
was never an issue with differing implementations of regex.

> 4) controltype, menuItem & conditionalvisibility These items
> seem very specific to a GUI like xPLHAL but not what a more
> generic GUI (or non-GUI app) may need.

They're all pretty generic, and easy enough to implement in any GUI (or
non-GUI) environment.

> I can see controltype
> a little easier because it's a single item and easy to
> understand (and ignore, if not needed).  But the menuItems
> and conditionalvisibility items really get specific about
> being GUI (or UI in general) oriented.

But the whole file is UI-oriented - that was the point of making them in
the first place - to provide a user interface to help the user get the
most out of what the device can do.

> I'm guessing this has to do with the historical side of
> things -- that this was originally just meant for xPLHAL.

Yep.

> Ideally, user interface items would either be in a separate
> xml file that would only be needed by interfaces that needed
> them or would be in a separate section of the XML file with a
> more generic name than menuItem.

But as UI stuff is such an important part of the file, I think it
deserves to remain as part of the main file.

We also need to consider compatibility - there's a lot of users out
there, and a lot of apps out there, that rely on the format of the XML
file.

We're lucky in that xPLHal doesn't bother what the root node is called,
but we won't be so lucky when changing other aspects of the file.

>
> I'm really not carping here -- I understand the genesis of
> how this file came into being (well, at least in broad
> strokes).  And again, I think we need to live with this for
> compatibility-sake.

Let me demonstrate how you could implement the <menuItem> feature in
your Java device config manager:

For each device that you detect, look through the XML file for a
matching <device> element, and use the <menuItem> tags to build
a popup
menu.

Here's an example of a <menuItem> element:

<menuItem name="Play">
<xplMsg>
audio.basic
{
command=play
}
</xplMsg>
</menuItem>

Use the name attribute as the text for the menu item in the popup menu.
When clicked, use the contents of the xplMsg element to create an xPL
message and send it to the device (it's always an xpl-cmnd message).

When the user right-clicks on a device, they can receive a popup menu of
all supported commands.

These menu items are really useful - especially in something like a
config manager, as they let the user quickly try out the device after
configuring it.
They also help to show the user what commands are supported by the
device, and if the user has an xPL monitor, they can see what xPL
messages are being generated.

There is another feature of <menuItem> elements:

Suppose we want Winamp to play a particular track. Consider the
following:

<menuItem name="Play File">
<xplMsg>
audio.winamp
{
command=none
extended=playfile %Enter the filename or playlist to be played:%
}
</xplMsg>
</menuItem>

When the user clicks this item, you need to detect the presence of the %
characters in the xPL message.
Use the text between the % marks to create a prompt, and ask the user to
enter a value.
Then substitute this value in the xPL message.
So:
extended=playfile %Enter the filename or playlist to be played:%
Would become:
extended=playfile c:\songs\my_song.mp3

And that's all there is to menu items.

You could basically do away with menu items and achieve the same thing
using the <command> elements, but command elements are more complex
in
terms of their UI specification, and for something like a config
manager, menu items are ideal.

HTH,

John