This document illustrates the basic framework upon which to build a Plugin or module compatible with the SlimServer software. The SlimServer provides a method to load custom modules at startup which are then made available to the user via remote control menus. Each plugin serves as an area within SlimServer remote menu system, available from within the Plugins menu. Plugin files are stored in the "Plugins" folder which is in the same folder as the SlimServer software. The Plugin interface can provide a very powerful control and has complete access to the functionality of the SlimServer. As with the rest of the SlimServer, plugin modules are created using the Perl language.
+This document illustrates the basic framework upon which to build a Plugin or module compatible with the SlimServer software. +The SlimServer provides a method to load custom modules at startup which are then made available to the user via remote control menus. +Each plugin serves as an area within SlimServer remote menu system, available from within the Plugins menu. Plugin files are stored in +the "Plugins" folder which is in the same folder as the SlimServer software. For simple plugins, a single file in this folder will suffice. + For more complex plugins, you can store an entire set of files in a sub-folder, naming the main plugin file: Plugin.pm. The Plugin interface can + provide a very powerful +control and has complete access to the functionality of the SlimServer. As with the rest of the SlimServer, plugin modules are created +using the Perl language.
Here are a couple of basic calls that should be made at the beginning of the Plugin code:
@@ -27,13 +34,18 @@ return \%functions; } - sub getDisplayName { return "My Plugin Name")} + sub getDisplayName { return "MY_PLUGIN_STRING_TOKEN")} + + sub strings { return ' + MY_PLUGIN_STRING_TOKEN + <tab> EN <tab> My Plugin English Name +'};The remote buttons are context sensitive, meaning that they can serve different roles when the SlimServer is in different modes. The setMode() +
If you wish for your plugin to have a player display interface, then you will need to set up what is called a Mode. The remote buttons are context sensitive, meaning that they can serve different roles when the SlimServer is in different modes. The setMode() subroutine defines this mode. Within this subroutine, there must be a definition for $client->lines, which is the text to be displayed on the Slim client while in this plugin mode. Typically, this is labeled just as above, though it can be any name you wish. The lines subroutine, or other name if you have chosen one, returns two strings. One for each line of the display. They can be updated at any time from any point in the plugin module by using the @@ -100,8 +112,25 @@ function calls such as:
$client->showBriefly(, $line1, $line2);
Examples of remote control functions include: 'up','down','play,'add' (REC button),'left','right','numberScroll' and 'stop' The full button to function map is found in the Default.map file, which is in the IR directory under the SlimServer directory.
-By default, plugins will appear in the Plugins menu on the player. However, some plugins may be similar to others, and could be better organised into submenus. The addMenu function allows a +plugin to choose its submenu location:
+ +The simple line subroutine, below, is taken from Picks.pm.
+++This will make the plugin appear in a submenu with the string token RADIO. This submenu string can then be localized by the server to the chosen language. Each submenu can, as an option, be added to the top level +menus for any player via the player settings. + + +Example 3
+sub addMenu { + return "RADIO"; +}; +
The lines subroutine returns the text that the Slim Client will display while using your plugin. The setMode() function creates the reference for the lines subroutine, and your lines subroutine name must match that. Each mode may have its own set of lines, and each is named after the reference created in each setMode. The input for this function is the current client information, and the return is two strings for main display and optionally a pair of strings which may need to be overlayed on top of the first pair, right justified. The lines are sent to the display at any time using the command:
@@ -109,7 +138,7 @@ $client->update();
The simple line subroutine, below, is taken from Rescan.pm.
-+Example 3
+Example 4
sub lines { my $client = shift; my ($line1, $line2); @@ -179,7 +209,7 @@ $client->update();SETUP_$prefname_OK the change intro message to use when the preference changes -+ +Some plugins may wish to operate as a per-client setup. The server allows for plugin settings to be a player settings +page instead of a server settings page by setting the isClient parameter like so: +Example 4
+Example 5
sub setupGroup { my $client = shift; @@ -187,8 +217,8 @@ sub setupGroup { my %setupGroup = ( PrefOrder => ['plugin-pluginName-pref-one','plugin-pluginName-pref-two'] - ,GroupHead => Slim::Utils::Strings::string('SETUP_GROUP_PLUGIN_PLUGINNAME') - ,GroupDesc => Slim::Utils::Strings::string('SETUP_GROUP_PLUGIN_PLUGINNAME_DESC') + ,GroupHead => $client->string('SETUP_GROUP_PLUGIN_PLUGINNAME') + ,GroupDesc => $client->string('SETUP_GROUP_PLUGIN_PLUGINNAME_DESC') ,GroupLine => 1 ,GroupSub => 1 ,Suppress_PrefSub => 1 @@ -202,36 +232,38 @@ sub setupGroup { 'plugin-pluginName-pref-two' => { 'validate' => \&Slim::Web::Setup::validateTrueFalse ,'options' => { - '0' => Slim::Utils::Strings::string('SETUP_PLUGIN-PLUGINNAME_PREFTWO_NO) - ,'1' => Slim::Utils::Strings::string('SETUP_PLUGIN-PLUGINNAME_PREFTWO_YES) + '0' => $client->string('SETUP_PLUGIN-PLUGINNAME_PREFTWO_NO) + ,'1' => $client->string('SETUP_PLUGIN-PLUGINNAME_PREFTWO_YES) } }, ); return (\%setupGroup,\%setupPrefs); }+return (\%setupGroup,\%setupPrefs,1); +
The plugin API also allows you to add in your own localization. The format of the strings list follows the same format as the strings.txt file used by the SlimServer for localization. The function strings() can be used within the plugin to extract a strings for the user's specified language. Defining the strings is done as follows:
-and to use your strings in your module, you make the call to strings in any place where you would use a text string. For example, referring to the getDisplayName() call from Example 1: -Example 5
+Example 6
sub strings { return ' PLUGIN_STRING_ONE <tab> EN <tab> English version of line one <tab> FR <tab> Version française de la ligne une '}; -
- sub getDisplayName { return "My Plugin Name" }
-
-can be changed to
-
- sub getDisplayName { my $client = shift; return $client->strings('PLUGIN_NAME') }
+and to use your strings in your module, you make the call to strings in any place where you would use a text string. For example:
+ $client->string('MY_STRING');
where your strings function contains:
sub strings { return '
-PLUGIN_NAME
-<tab> EN <tab> My Plugin Name
+MY_STRING
+<tab> EN <tab> Useful text
'};
One special note, the format of the strings list is very strict. The whitespace must be a tab, not spaces, which is why the tabs are shown above.
@@ -258,7 +290,7 @@ expression keys nor the index URL path n into account.-Example 6
+Example 7
sub webPages { my %pages = ( "index\.(?:htm|xml)" => \&handleIndex, @@ -309,6 +341,18 @@ sub screenSaver {leaveScreensaverMode subroutine to execute before the mode exits $client->string('SCREENSAVER_NAME') SCREENSAVER_NAME should be change to a unique identifier for your plugin name. This can be the same as your plugin, or something different. This allows for future nationalisation for the other languages supported by SlimServer. + +
+Other Functions
+There are several other optional plugin functions that allow you to control how you plugin will integrate with the server:
++
+- initPlugin()
- subroutine to handle any operations that your plugin needs to execute on startup, on when the plugin becomes enabled.
+- shutdownPlugin()
- subroutine to handle any operations that need to be performed to shut down the plugin cleanly, or to be run when disabled. This is particularly useful in cases +where external processes need to be informed or resources need to be freed when the plugin is shut down
+- enabled()
- a subroutine to test the conditions required for the plugin to be enabled. returns a logical true/false indicating whether the plugin can be enabled.
+- defaultMap()
- automatically loaded by the server if this is present, this routine can override the IR button mapping found in IR/Default.map for your plugin mode see Button Mapping for details on mapping.
+
Summary
Using the existing plugins as examples (one appears below) and this document as an explanation of what each section of the plugin can do, you should now be able to start working on a plugin of your own. Remember that this is only a framework to allow you to hook into the SlimServer. There are always many other ways to implement the features of a plugin. As long as your provide the lines from the examples above, the server will try to work with your Plugin. The rest can be just about anything you want, including using any of functions and subroutines within the SlimServer. Remember, there's more than one way to do it.
@@ -342,9 +386,7 @@ use Slim::Player::Playlist; use Slim::Utils::Strings qw (string); sub getDisplayName { - my $client = shift; - - return $client->string('PLUGIN_RESCAN_MUSIC_LIBRARY') + return 'PLUGIN_RESCAN_MUSIC_LIBRARY' }; sub strings { return '