[% pagetitle = 'Skin Creation' %] [% techinfo = '1' %] [% lefttoright = '1' %] [% PROCESS helpheader.html %] [% TAGS star %]

Overview

WARNING: This documentation is substantially out of date.

The web interface to the Logitech Media Server makes use of customizable html templates collected together into a skin. These skins reside in the html subfolder of the folder where the server software was installed. The skin subfolders are presented for selection in the additional server settings setup page based on the name of the skin subfolder. The default skin is in the EN subfolder. Each skin can have a subfolder named html which can contain static content such as this documentation, or images for use with the dynamic content of the skin.

When a page not in the html subfolder of either your skin or the default skin is requested, the server builds the page dynamically based on the templates within the skin subfolder. This building is accomplished by gathering information relevant to the requested page in a perl subroutine, then using that information to complete the template.


Directory Structure

Logitech Media Server

Template Syntax

The template files in the skin directory are primarily html, with some server-side processing directives added. In some cases they are complete pages, in others fragments which are meant to be included into a surrounding page. The interrelationships of the files are discussed below in the Template Dependencies section of this document.

Logitech Media Server uses the freely available Template Toolkit version 2.13 for its templates. Full documentation is available at the linked web site. Some of the simpler directives are detailed in the Template Directives section.

When a dynamic page is requested, the server builds a parameter hash which is used along with the template to create the final html which is returned to the requestor. The server-side directives contain references to the keys of this parameter hash. For practical purposes this means that each template has a list of variables available to it (corresponding to the keys of that parameter hash) which it uses with the directives to produce the desired final text. The list of variables available to each template is discussed below in the Template Variables section.


Template Directives

The following are some of the simpler directives made available through the Template Toolkit. Note that directives may be nested as needed. For more advanced uses, please read the documentation at the Template Toolkit website.

All directives under Template Toolkit are bracketed by [% and %].

[% GET param %]
[% param %]
This directive is replaced by the value of param
[% SET param = value %]
[% param = value %]
This directive sets param to value.
[% IF expression %]text[% END %]
[% UNLESS expression %]text[% END %]
[% IF expression %]text1[% ELSE %]text2[% END %]
[% IF expression1 %]text1[% ELSIF expression2 %]text2[% ELSE %]text3[% END %]
The IF directive evaluates expression according to standard perl rules. If expression evaluates true, the directive is replaced by the contents of text, which may itself contain directives. If expression evaluates false, the directive is replaced by the empty string. expression can be almost any valid perl expression, for example it could take the form of param comparator value, where comparator is one of <, <=, ==, !=, =>, >, lt, le, eq, ne, ge, gt.
The UNLESS is the opposite, replacing with the empty string if expression is true, and with text if expression is false.
If an ELSE directive is present the text2 replaces the entire IF/UNLESS block instead of the empty string. The ELSIF directive provides a means of chaining together multiple expressions to control the replacement text.
[% FILTER filtername %] filtertext [% END %]
[% filtertext | filtername %]
The FILTER directive takes filtertext and processes it using the filter filtername. For more info see the Template Filters section.
[% INSERT file %]
[% INCLUDE file %]
[% PROCESS file %]
These directives allow you to build the output using multiple files. The INSERT directive adds the contents of file to the output without any additional processing. The INCLUDE directive makes a copy of the parameter hash and uses this copy in processing file with Template Toolkit. The PROCESS directive is the same as INCLUDE, except that the parameter hash is not copied first. This means that if the template is processed using a PROCESS directive, any SET directives in that template will be able to change parameters in the current template, whereas if the INCLUDE directive were used the current parameters would not be able to be changed by the processed template.

Template Plugins

Template Toolkit supports the use of plugins to add functionality. These are different from server plugins. There are currently no server specific plugins implemented. The standard Template Toolkit plugins are available, except for those that require the use of other CPAN modules that have not already been included with server.


Template Filters

Template Toolkit makes use of perl functions called filters to perform processing of text. The server includes all the standard Template Toolkit filters, plus some additional ones described here.

nbsp
This filter converts all spaces in the filter text to &nbsp; to prevent the filtered text from wrapping.
string
This filter uses Slim::Utils::Strings::string to localize the filter text.
uri
This filter replaces the standard Template Toolkit uri filter with URI::Escape::uri_escape.
unuri
This filter uses URI::Escape::uri_unescape to change from uri escaped text to normal text.

Template Dependencies

Only a subset of the templates used are directly requestable from the web interface. The others are used to fill in parameters for the requestable ones. The requestable templates and the templates subordinate to them are listed below. All templates can be requested as either *.htm or *.html.

index.html
home.html
status.html
browse.html
browsedb.html
songinfo.html
search.html
setup.html
*.html under html directory

Non-Template Requestable Items

Certain requests made to the server HTTP server are fulfilled outside of the template mechanism. Some items are generated dynamically, while others are served up as the file exists on the server. The static item requests are satisfied by following the mechanism of checking for the requested file first in the selected skin directory, then in the default skin directory (EN).

Dynamic Items

status.txt
Returns the text displayed on the currently selected player.
status.m3u
Returns the current playlist of the currently selected player in m3u format.
stream.mp3
Returns an Icecast/Shoutcast style stream.

Static Items

slimserver.css
Arguably the most important file to modify to make a skin your own.
skin.css
Useful for custom styles for a skin, where the bulk of the default styles are already acceptable. Anything in this file overrides slimserver.css. Anything not inclucded is taken from slimserver.css.
favicon.ico
Serves up skin/html/mypage.ico
non-html content in the html directory
Currently supported types (suffixes):

Template Functions

Pages::browser
Call tree
  • Pages::browser_addtolist_done
    • Pages::pagebar
Templates used
  • badpath.html
  • browse_pwdlist.html
Pages::browser_addtolist_done
Call tree
  • Pages::pagebar
Templates used
  • browse_playlist_list.html
  • browse_list.html
  • browse_playlist.html
  • browse.html
Pages::pagebar
Call tree
no subroutines called
Templates used
  • pagebarheader.html
  • pagebar.html
  • pagebarlist.html
Pages::alphapagebar
Call tree
no subroutines called
Templates used
  • pagebar.html
  • alphapagebarlist.html
Pages::status
Call tree
  • Pages::pagebar
Templates used
  • status.html
  • status_list.html
Pages::home
Call tree
no subroutines called
Templates used
  • home.html
  • homeplayer_list.html
Pages::search
Call tree
  • Pages::pagebar
  • Pages::alphapagebar
Templates used
  • search.html
  • browsedb_list.html
Pages::songinfo
Call tree
no subroutines called
Templates used
  • songinfo.html
Pages::browsedb
Call tree
  • Pages::pagebar
  • Pages::alphapagebar
Templates used
  • browsedb.html
  • browsedb_list.html
  • browsedb_pwdlist.html

Template Variables

There are three types of variable available. The first are Template Toolkit provided, the second are provided to all pages by the server, and the third are provided to specific pages by Logitech Media Server.

Template Toolkit variables
template
A reference to the main template being processed. It contains metainformation about the template, such as the name of the template, and when it was last modified.
component
Like template but refers to the current template component being processed.
global
A reference to a repository for global information.
dec
inc
Apparently the amount to decrement and increment in a loop, not sure though.
loop

A reference to the implicit iterator object created for the FOREACH directive. It is only available within each FOREACH loop. Contains these variables:

count
Current interation count
first
True for first iteration of the loop, false other times.
index
Number of the current item
last
True on the last iteration of the loop, false other times.
max
Maximum index number
next
A reference to the next item in the set being iterated through
prev
A reference to the previous item in the set being iterated through
size
The number of elements in the set being iterated through.
content
Used in wrapper templates to refer to the wrapped content
Server General Variables
Content-Type
The content type of the requested page, will usually be text/html.
path
The virtual path to the requested page. Excludes the portion in webroot.
host
The host name pulled from the HTTP request header
player
The client id of the currently selected player. This is typically sent in the GET request for a page. If not in the request, the first client is used.
playermodel
The type of player (Squeezebox, Transporter or SLIMP3) currently selected.
myClientState
The client object of the currently selected player.
url_query
The query portion of the HTTP request, everything after the "?"
webroot
Portion of the path used to determine the virtual root. This includes the skin name when a skin other than the "skin" server preference is requested. Logitech Media Server also allows a pseudo-root of /slimserver/ to be used, which also ends up in webroot. When creating absolute URLs webroot should be used as the root rather than simply using "/".
skinOverride
When a skin other than the "skin" server preference is requested, skinOverride will contain the name of that skin.
userAgent
The user-agent string from the client browser
Page Specific Variables
index.html
General Variables only
home.html
General variables
Server provided variables:
additionalLinks

Hash of additional links to display. Divided into subhashes by link category. Each subhash consists of page title - URL pairs. The page titles should be run through the string filter before display. The link categories are as follows:

browse
Pages for the various Browse By categories.
search
Pages for the various Search types.
help
The documentation.
plugins
Pages related to installed plugins.
settings
Pages related to setup of the installed plugins.
album_count
Count of unique albums in library. Includes the word album or albums after the number.
artist_count
Count of unique artists in library. Includes the word artist or artists after the number.
newVersion
Indicates the latest version of the server. Not defined if the checkVersion server parameter is false.
nofolder
Set to 1 if the audiodir server parameter is undefined. Not defined otherwise.
nosetup
Set to 1 if setup is disabled. Not defined if setup is enabled.
player_list
Links to player setup pages, one link per player, built using homeplayer_list.html.
playercount
Count of players.
song_count
Count of songs in library. Includes the word song or songs after the number.
Expected user provided parameters:
forget
If this parameter is set in the HTTP request, the server will delete all information about the client refered to by the player parameter.
browse.html
General variables
Server provided variables:
album_count
Count of unique albums in library. Includes the word album or albums after the number.
artist_count
Count of unique artists in library. Includes the word artist or artists after the number.
browse_list
List of items in the container being browsed, formatted into a string using browse_list.html and the raw list of items.
browselist_header
Header built using pagebarheader.html. Typically used to indicate the range of items being displayed.
browselist_pagebar
List of pages of items in the container being browsed, formatted into a string using pagebar.html.
nopagebar
Set to 1 to suppress the generation of the pagebar. Typically set in the include.html file.
pwd_list
List of containers leading to the current container, formatted into a string using browse_pwdlist.html.
song_count
Count of songs in library. Includes the word song or songs after the number.
Expected user provided parameters:
dir
Virtual path to current container.
start
Starting item number for current page.

older info, the following is somewhat out of date and is in the process of being updated

index.html
Server provided parameters
General Variables only
Expected user provided parameters
none
browse.html
Server provided parameters
playlist
pwd_list
playlistname
titled
browse_list
browselist_header
browselist_pagebar
Expected user provided parameters
dir
newname
delete
start
browse_playlist.html
Server provided parameters
playlist
pwd_list
playlistname
titled
browse_list
browselist_header
browselist_pagebar
RENAME_WARNING
warn
Expected user provided parameters
dir
newname
delete
start
browse_pwdlist.html
Server provided parameters
player
myClientState
dir
shortdir
Expected user provided parameters
none
browse_playlist_list.html
Server provided parameters
descend
title
artist
album
itemobj
odd
player
anchor
Expected user provided parameters
none
browse_list.html
Server provided parameters
descend
title
artist
album
itemobj
odd
player
anchor
Expected user provided parameters
none
pagebarheader.html
Server provided parameters
start
end
itemcount
Expected user provided parameters
none
pagebar.html
Server provided parameters
pagesstart
pagesprev
pagesend
pagesnext
pageprev
pagenext
otherparams
pageslist
Expected user provided parameters
none
pagebarlist.html
Server provided parameters
currpage
itemnum0
itemnum1
pagenum
otherparams
Expected user provided parameters
none
alphapagebarlist.html
Server provided parameters
currpage
itemnum0
itemnum1
pagenum
otherparams
fragment
Expected user provided parameters
none
status.html
Server provided parameters
currentsong
thissongnum
songcount
songtitle
artist
album
player_name
cansave
player_chooser_list
playlist
start
playlist_header
playlist_pagebar
shuffle
repeat
modeplay
modepause
modestop
volume
Expected user provided parameters
player
refresh
p0
p1
p2
p3
p4
status_list.html
Server provided parameters
player
myClientState
num
odd
currentsong
title
artist
album
start
Expected user provided parameters
none
home.html
Server provided parameters
additionalLinks
album_count
artist_count
nofolder
nosetup
path
player_list
playercount
song_count
Expected user provided parameters
forget
homeplayer_list.html
Server provided parameters
playername
playerid
player
Expected user provided parameters
none
search.html
Server provided parameters
browse_list
numresults
searchlist_header
searchlist_pagebar
Expected user provided parameters
query
type
start
browsedb_list.html
Server provided parameters
player
genre
artist
album
song
itemobj
title
descend
odd
anchor
Expected user provided parameters
none
songinfo.html
Server provided parameters
composer
conductor
title
filelength
duration
year
tagversion
comment
bitrate
url
itemobj
Expected user provided parameters
itemobj
genre
artist
album
track
browsedb.html
Server provided parameters
warn
itunes
pwd_list
browseby
browselist_pagebar
browse_list
descend
Expected user provided parameters
song
genre
artist
album
start
browsedb_pwdlist.html
Server provided parameters
player
song
artist
album
genre
pwditem
Expected user provided parameters
none

Old Template Syntax

The template files in the skin directory are primarily html, with some server-side processing directives contained in square brackets added. In some cases they are complete pages, in others fragments which are meant to be included into a surrounding page. The interrelationships of the files are discussed below in the Template Dependencies section of this document. The directives are discussed below in the Template Directives section.

When a dynamic page is requested, the server builds a parameter hash which is used along with the template to create the final html which is returned to the requestor. The server-side directives contain references to the keys of this parameter hash. For practical purposes this means that each template has a list of parameters available to it which it uses with the directives to produce the desired final text. The list of parameters available to each template is discussed below in the Template Parameters section.


Old Template Directives

Template directive outline conditions for text replacement. The directives are evaluated in the order below, one at a time, starting at the beginning of the template and proceeding to the end, starting over for the next directive type at the beginning. The mechanism used is regular expression search and replace, so certain restrictions apply.

[EVAL] text [/EVAL]
The EVAL directive executes the perl code which it frames (the text). The code should set a variable named $out to a string which will replace the directive. It is acceptable to not set $out to anything, in which case the directive will be replaced by an empty string. If the code should fail, the directive will be replaced with the word "ERROR".
Replaced by [% PERL %] text [% END %] under Template Toolkit. Using this definitely will require reading the Template Toolkit documentation thoroughly.
{%param}
The % directive is replaced with the URL escaped value of param (for example, spaces become %20, / becomes %2f, etc.). If param is undefined, the directive is replaced with the empty string.
Replaced by [% param | uri %] under Template Toolkit.
{&param}
The & directive is replaced with the HTML encoded value of param (for example, < becomes &lt;, > becomes &gt;, etc.). If param is undefined, the directive is replaced with the empty string.
Replaced by [% param | html %] under Template Toolkit.
{param}
This directive is replaced with the value of param. If param is undefined, the directive is replaced with the empty string.
Replaced by [% param %] under Template Toolkit.
[S string]
The S directive is replaced by the language specific string defined for string in strings.txt. If string is not defined for the current language, the default language definition is used. If string is also not defined for the default language the directive is replaced by the empty string.
Replaced by [% string | string %] under Template Toolkit.
[SET name value]
Using the SET directive will set the parameter with the given name to the given value. This is useful with the INCLUDE directive for setting values in subsequently included files, as well with IF and other conditional directives for changing the HTML dynamically.
Replaced by [% param = value %] under Template Toolkit.
[IF param] text [/IF]
The IF directive evaluates param according to standard perl rules. If param evaluates to true, then text is included in the final output, otherwise the directive is replaced by an empty string. Under the standard perl rules, param is false if it has a value of 0 (or "0"), is undefined (does not exist), or is the empty string ("").
Replaced by [% IF param %] text [% END %] under Template Toolkit.
[IFN param] text [/IFN]
The IFN directive works the same as the IF directive, except that text is included if param evaluates to false instead of true.
Replaced by [% IF not param %] text [% END %] under Template Toolkit.
[EQ param value] text [/EQ]
The EQ directive evaluates param to see if its value is equal to value. If so, text is included in the final output, otherwise the empty string replaces the directive. If param is undefined, it is considered to be not equal to value.
Replaced by [% IF param == value %] text [% END %] or [% IF param eq value %] text [% END %] (depending on whether you are comparing numbers or strings) under Template Toolkit.
[NE param value] text [/NE]
The NE directive works the same as the EQ directive, except that text is included if the value of param is not equal to value. Once again, if param is undefined, it is considered to be not equal to value, so text would be included in that case.
Replaced by [% IF param != value %] text [% END %] or [% IF param ne value %] text [% END %] (depending on whether you are comparing numbers or strings) under Template Toolkit.
[GT param value] text [/GT]
The GT directive evaluates param to see if its value is greater than value. If so, text is included in the final output, otherwise the empty string replaces the directive. If param is undefined, it is considered to be not greater than value.
Replaced by [% IF param > value %] text [% END %] or [% IF param gt value %] text [% END %] (depending on whether you are comparing numbers or strings) under Template Toolkit.
[LT param value] text [/LT]
The LT directive evaluates param to see if its value is less than value. If so, text is included in the final output, otherwise the empty string replaces the directive. If param is undefined, it is considered to be not less than value.
Replaced by [% IF param < value %] text [% END %] or [% IF param lt value %] text [% END %] (depending on whether you are comparing numbers or strings) under Template Toolkit.
[INCLUDE html/path/here.html]
Using the INCLUDE directive will include the parsed contents of the file in html/path/here.html in the output. Useful for sharing content across several html template files.
Replaced by [% PROCESS html/path/here.html %] under Template Toolkit.
[STATIC html/path/here.html]
Using the STATIC directive will include the parsed contents of the file in html/path/here.html in the output, but will not parse the file for template directives.
Replaced by [% INSERT html/path/here.html %] under Template Toolkit.
[NB]text[/NB]
The NB directive replaces spaces in text with &nbsp; in order to prevent line wrapping in the middle of text.
Replaced by [% FILTER nbsp %]text [% END %] under Template Toolkit.
[E]text[/E]
The E directive replaces text with its URL escaped equivalent.
Replaced by [% FILTER uri %]text [% END %] under Template Toolkit.
&lsqb;
&rsqb;
&lbrc;
&rbrc;
Not really directives, but also not standard html. These strings are replaced by [ (for &lsqb;), ] (for &rsqb;), { (for &lbrc;), and } (for &rbrc;). They are used to avoid having normal text interpreted as a directive. The use of &#91; for [, &#93; for ], &#123; for {, and &#125; for } would also work, and would be standard html.
Not needed under Template Toolkit.


[* TAGS template *] [% PROCESS helpfooter.html %]