Description

As of version 1.2 Alpha, MediaPortal plugins are able to be started with an optional parameter. This parameter can be either set by the skin with a button's hyperlinkParameter property or if the plugin is opened by another plugin by calling

GUIWindowManager.ActivateWindow((int)_hyperLinkWindowId, _hyperLinkParameter);

with the parameter set in the variable _hyperlinkParameter.

Parameter format

The startup parameter is a string value and the format of this string is entirely up to the author of the plugin. The string can be a single-worded parameter, a list of parameters (par1|par2|...), a key/value pair of parameters (key1=value1|key2=value2|...) or everything else as long as both, the caller and the receiver know the correct format.

Parameterized startup

The plugin that is started with a specific parameter has access to this parameter as soon as the OnPageLoad method is called, so it is recommended to use the parameter within this method (or at a later stage in the plugin's life-circle).

How to access the parameter

The parameter that was set from skin with the hyperlinkParameter property or a plugin in the ActivateWindow method (see Description above) can be acces with the GUIWindow (from which every windows plugin derivates) field _loadParameter. So all the plugin needs to do (e.g. in the OnPageLoad method) is call

String myParam = _loadParameter

to save the startup parameter in the local variable myParam.

Backwards compatibility

The field _loadParameter was introduced in MediaPortal 1.2 Alpha, so accessing this field when the plugin was installed with an older version of MediaPortal (e.g. MediaPortal 1.1) will crash MediaPortal because the plugin accesses a variable that doesn't exist. This can be prevented by using Reflection to check if the field exists in the running version of MediaPortal. See the following code example for a way to make your plugin backwards compatible with older versions of MP:

// check if running version of mediaportal supports loading with parameter
System.Reflection.FieldInfo fi = typeof(GUIWindow).GetField("_loadParameter", System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance);
if (fi != null)
{
    string loadParam = (string)fi.GetValue(this);
    //site:<sitename>|category:<categoryname>|search:<searchstring>|return:<locked|root>|view:<list|smallthumbs|largethumbs>
    //add bool option on search to popup VK if nothing found or not
}

Popular Plugins

Here is an overview of how some plugins have implemented this feature to allow parameterized startup, for a more detailled description refer to the plugin documentation.

MovingPictures

Moving Pictures allows skins or other plugin to start it with a parameter to
Directly go to a movie by given id  If the parameter movieid is set, MovingPictures will directly go to the details page of this movie. The movie details level is also set as top-level, so when the user presses back it will directly take him back to the previous window. The movie position is not stored when MovingPictures is opened in details view. Go to category by given id If the parameter categoryid is set, MovingPictures will start with this specified id. This category is also set as top-level so when the user presses back at this level he will be returned to the previous window. Exiting MovingPictures with another method (e.g. pressing h to return to the homescreen) will save the current position and when MovingPictures is opened the next time will be taken to this position. Go to category by given name If the parameter categoryname is set, MovingPictures will try to find this category and show it on startup. Other than that the category is specified by name this option behaves the same as Go to category by given id

If more than one parameter is specified, MovingPictures will assume the following priorities:

1. movieid
2. categoryid
3. categoryname

Examples:

Open MovingPictures with specific Movie (with id=10) in details view:

<control>
    <description>home BM Video</description>
    <type>button</type>
    <hyperlink>96742</hyperlink>
    <hyperlinkParameter>movieid:10</hyperlinkParameter>
</control>

Open MovingPictures with specific category (with id=10):

<control>
    <description>home BM Video</description>
    <type>button</type>
    <hyperlink>96742</hyperlink>
    <hyperlinkParameter>categoryid:10</hyperlinkParameter>
</control>

Open MovingPictures with specific category (with "AllMovies" category):

<control>
    <description>home BM Video</description>
    <type>button</type>
    <hyperlink>96742</hyperlink>
    <hyperlinkParameter>categoryname:${AllMovies}</hyperlinkParameter>
</control>

MP-TvSeries (since version 2.6.5)

MP-TvSeries has added support for this feature in version 2.6.5 (https://forum.team-mediaportal.com/my...tml#post673771). You can use the feature by simply adding the non-translated name of a view as a load parameter and the plugin will open with this view. If you open MP-TvSeries without a parameter, the last used view will be shown.

For developers of skin-editors/basichome editors, MP-TvSeries offers the helper method DBView.GetSkinViews() to get a list of all available parameters. The function will return a list of keyvaluepairs where the key is the view name (used in hyperlinkParameter) and value which is the translated name as presented to the user in MediaPortal. The skin editor can load that into a list for users to choose views to add to there user home menu (See screenshot 1).