PluginSettings

This page needs editing. Needs to be updated to Squeezebox Server 7.0 way of handling preferences

Squeezebox Server plugins have the option to include settings to be accessed from the web interface through the plugins settings page. To do this, include a function called "setupGroup" which returns a hash reference to the Group parameters, and another to the preference parameters. These two hash may contain any or all of the following keys:

Group hash ref keys

PrefOrder  list of prefs to appear in group, in orderPrefsInTable  set if prefs should appear in a tableGroupHead  Name of the group, usually set to string('SETUP_GROUP+$groupname'), no defaultGroupDesc  Description of the group, usually set to string('SETUP_GROUP_$groupname_DESC'), no defaultGroupLine  set if an---- should appear after the groupGroupSub  set if a submit button should appear after the groupSuppress_PrefHead  set to prevent the heading of preferences in the group from showingSuppress_PrefDesc  set to prevent the descriptions of preferences in the group from showingSuppress_PrefLine  set to prevent----'s from appearing after preferences in the groupSuppress_PrefSub  set to prevent submit buttons from appearing after preferences in the group

Prefs hash's' keys

onChange  sub ref taking $client, $changeref, $paramref, $pageref, $key, $ind as parameters, fired when a preference changesisArray  exists if setting is an array type preferencearrayAddExtra  number of extra null entries to append to end of arrayarrayDeleteNull  indicates whether to delete undef and '' from arrayarrayDeleteValue  value signifying a null entry in the arrayarrayCurrentPref  name of preference denoting current of arrayarrayBasicValue  value to add to array if all entries are removedarrayMax  largest index in array (only needed for items which are not actually prefs)validate  reference to validation function (will be passed value to validate) (default validateAcceptAll)validateArgs  array of arguments to be passed to validation function (in addition to value) (no default)options  hash of value => text pairs to be used in building a list (no default)optionSort  controls sort order of the options, one of K (key), KR (key reversed), V  (value) VR (value reversed) - (default K)dontSet  flag to suppress actually changing the preferencecurrentValue  sub ref taking $client,$key,$ind as parameters, returns current value of  preference. Only needed for preferences which don't use Slim::Utils::PrefsnoWarning  flag to suppress change informationexternalValue  sub ref taking $client,$value, $key as parameters, used to map an internal value to an external onePrefHead  friendly name of the preference (defaults to string('SETUP_$prefname')PrefDesc  long description of the preference (defaults to string('SETUP_$prefname_DESC')PrefChoose  label to use for input of the preference (defaults to string('SETUP_$prefname_CHOOSE')PrefSize  size to use for text box of input (choices are 'small','medium', and  'large', default 'small'). Actual size to use is determined by the  setup_input_txt.html template (in EN skin values are 10,20,40)ChangeButton  Text to display on the submit button within the input for this preference. Defaults to string('CHANGE')inputTemplate  template to use for the input of the preference (defaults to  setup_input_sel.html for preferences with 'options', setup_input_txt.html otherwise)changeIntro  template for the change introductory text (defaults to  'string('SETUP_NEW_VALUE') string('SETUP_prefname'):') for array prefs the  default is 'string('SETUP_NEW_VALUE') string('SETUP_prefname') %s:' sprintf'd  with array indexchangeMsg  template for change value (defaults to %s), this will be sprintf'd to stick in the valuechangeAddlText  template for any additional text to display after a change (default '')rejectIntro  template for the rejection introductory text (defaults to  'string('SETUP_NEW_VALUE') string('SETUP_prefname')  string('SETUP_REJECTED'):')(sprintf'd with array index for array settings) for  array prefs the default is 'string('SETUP_NEW_VALUE') string('SETUP_prefname')  %s string('SETUP_REJECTED'):' sprintf'd with array indexrejectMsg  template for rejected value message (defaults to  'string('SETUP_BAD_VALUE')%s'), this will be sprintf'd to stick in the valuerejectAddlText  template for any additional text to display after a rejection (default '')

The default values are used for keys which do not exist() for a particular preference for most preferences the only values to set will be 'validate', 'validateArgs', and 'options'

Strings

Settings use strings extensively, for many values it defaults to a certain combination of the preference name with other characters. For this reason it is important to follow the naming convention when adding strings for preferences in your plugins. In the following $groupname is replaced by the actual key used in the Groups hash and $prefname by the key from the Prefs hash.

SETUP_GROUP_$groupname  the name of the group, such as would be used in a menu to select the group or in the heading of the group in the web page. Should be < 40 charsSETUP_GROUP_$groupname_DESC  the long description of the group, used in the web page, so length unimportantSETUP_$prefname  the friendly name of the preference, such as would be used in a menu to  select the preference or in the heading of the preference in the web page.  Should be < 40 chars. Also used when the preference changes and no change  intro message was specified.SETUP_$prefname_DESC  the long description of the preference, used in the web page, so length unimportantSETUP_$prefname_CHOOSE  the label used for presentation of the input for the preferenceSETUP_$prefname_OK  the change intro message to use when the preference changes

Example 4:

sub setupGroup { my %setupGroup = ( PrefOrder => ['plugin-pluginName-pref-one', 'plugin-pluginName-pref-two'], 
                                                      GroupHead => string('SETUP_GROUP_PLUGIN_PLUGINNAME'), 
                                                      GroupDesc => string('SETUP_GROUP_PLUGIN_PLUGINNAME_DESC'), 
                                                      GroupLine => 1, 
                                                      GroupSub => 1, 
                                                      Suppress_PrefSub => 1, 
                                                      Suppress_PrefLine => 1, ); 
my %setupPrefs = ( 'plugin-pluginName-pref-one' => { 'validate' => \&Slim::Web::Setup::validateInt, 
                                                                                'validateArgs' => [1, undef, 1] 
                                                                                            } 
                                  'plugin-pluginName-pref-two' => { 'validate' => \&Slim::Web::Setup::validateTrueFalse, 
                                                                                    'options' => { '0' => string('SETUP_PLUGIN-PLUGINNAME_PREFTWO_NO'), 
                                                                                                             '1' => string('SETUP_PLUGIN-PLUGINNAME_PREFTWO_YES'), 
                                                                                                                  }, 
                                                                                          }, 
                                ); 
return (\%setupGroup,\%setupPrefs); }

|}

• Next Page