[% pageicon = 'help' %]
[% pagetitle = 'Skin Creation' %]
[% techinfo = '1' %]
[% PROCESS helpheader.html %]
[% TAGS star %]
Overview
The web interface to the SlimServer makes use of customizable html
templates collected together into a skin. These skins reside in the
html subfolder of the folder where the SlimServer 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 SlimServer 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
SlimServer
- html
- slimserver.exe (or slimserver.pl)
- other items...
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.
SlimServer 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.
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 Toolkit supports the use of plugins to add functionality. These
are different from SlimServer plugins. There are currently no SlimServer
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 SlimServer.
Template Toolkit makes use of perl functions called filters to perform processing
of text. SlimServer includes all the standard Template Toolkit filters, plus
some additional ones described here.
- nbsp
-
This filter converts all spaces in the filter text to 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.
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
-
- pagebarheader.html
- pagebar.html
- status_list.html
- browse.html
-
- badpath.html
- browse_pwdlist.html
- pagebarheader.html
- pagebar.html
- browse_list.html
- browse_playlist.html
- browse_playlist_list.html
- browseid3.html
-
- pagebarheader.html
- pagebar.html
- pagebarlist.html
- alphapagebarlist.html
- browseid3_pwdlist.html
- browseid3_list.html
- songinfo.html
- search.html
-
- pagebarheader.html
- pagebar.html
- pagebarlist.html
- alphapagebarlist.html
- browseid3_list.html
- setup.html
- *.html under html directory
Non-Template Requestable Items
Certain requests made to the SlimServer 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.
- favicon.ico
- Serves up skin/html/mypage.ico
- non-html content in the html directory
-
Currently supported types (suffixes):
- application/pdf (.pdf)
- application/x-java-applet (.class)
- audio/mpeg (.mp3, .mp2)
- audio/x-cue (.cue)
- audio/x-mpegurl (.m3u)
- audio/x-ogg (.ogg)
- audio/x-scpls (.pls)
- image/gif (.gif)
- image/jpeg (.jpg, .jpeg)
- image/png (.png)
- image/x-icon (.ico)
- text/css (.css)
- text/plain (.txt)
Template Functions
- Pages::browser
-
- Call tree
-
- Pages::browser_addtolist_done
- Templates used
-
- badpath.html
- browse_pwdlist.html
- Pages::browser_addtolist_done
-
- Call tree
-
- 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
-
- 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
- browseid3_list.html
- Pages::songinfo
-
- Call tree
- no subroutines called
- Templates used
-
- Pages::browseid3
-
- Call tree
-
- Pages::pagebar
- Pages::alphapagebar
- Templates used
-
- browseid3.html
- browseid3_list.html
- browseid3_pwdlist.html
There are three types of variable available. The first are Template Toolkit
provided, the second are provided to all pages by SlimServer, and the third are
provided to specific pages by SlimServer.
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
SlimServer 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 (SLIMP3 or Squeezebox) 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.
SlimServer 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.
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 SlimServer. Not defined if the
checkVersion server parameter is false.
- noartwork
-
Set to 1 if the lookForArtwork server parameter is false.
Not defined otherwise
- 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, SlimServer 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
- savebuttonname
- 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
- savebuttonname
- 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
- itempath
- odd
- player
- anchor
- Expected user provided parameters
-
none
- browse_list.html
-
- Server provided parameters
-
- descend
- title
- artist
- album
- itempath
- 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
- shuffleon
- shuffleoff
- repeatoff
- repeatone
- repeatall
- 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
- browseid3_list.html
-
- Server provided parameters
-
- player
- genre
- artist
- album
- song
- itempath
- title
- descend
- odd
- anchor
- Expected user provided parameters
-
none
- songinfo.html
-
- Server provided parameters
-
- composer
- conductor
- title
- filelength
- duration
- year
- tagversion
- comment
- bitrate
- url
- itempath
- Expected user provided parameters
-
- itempath
- genre
- artist
- album
- track
- browseid3.html
-
- Server provided parameters
-
- warn
- itunes
- pwd_list
- browseby
- browselist_pagebar
- browse_list
- descend
- Expected user provided parameters
-
- song
- genre
- artist
- album
- start
- browseid3_pwdlist.html
-
- Server provided parameters
-
- player
- song
- artist
- album
- genre
- pwditem
- Expected user provided parameters
-
none
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.
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.
- A directive cannot contain itself (even with a different parameter).
- Different directives can be contained within each other.
- Overlapping directives are also not allowed.
- Line endings within the text portion of directives are allowed, so a directive
may span multiple lines.
- [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.
- {¶m}
-
The & directive is replaced with the HTML encoded value
of param (for example, < becomes <, > becomes >,
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
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.
- [
- ]
- &lbrc;
- &rbrc;
-
Not really directives, but also not standard html. These strings are
replaced by [ (for [), ]
(for ]), { (for &lbrc;),
and } (for &rbrc;). They are used to avoid having normal
text interpreted as a directive. The use of [
for [, ] for ], { for
{, and } for } would also work, and
would be standard html.
-
Not needed under Template Toolkit.
[* TAGS template *]
[% PROCESS helpfooter.html %]