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

#### Overview

The web interface to the Squeezebox Server makes use of customizable html templates collected together into a skin. These skins reside in the html subfolder of the folder where the Squeezebox 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 Squeezebox 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

Squeezebox Server

- html

- EN

- html...

- Bagpuss

- html...

- YourSkin
  - html...

- slimserver.exe (or slimserver.pl)
- other items...

#### 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.

Squeezebox 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 Squeezebox Server plugins. There are currently no Squeezebox 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 Squeezebox Server.

#### Template Filters

Template Toolkit makes use of perl functions called filters to perform processing of text. Squeezebox 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
  - homeplayer_list.html
status.html
  - pagebarheader.html
  - pagebar.html
  - pagebarlist.html
  - status_list.html
browse.html
  - badpath.html
  - browse_pwdlist.html
  - pagebarheader.html
  - pagebar.html
  - pagebarlist.html
  - browse_list.html
  - browse_playlist.html
  - browse_playlist_list.html
browsedb.html
  - pagebarheader.html
  - pagebar.html
  - pagebarlist.html
  - alphapagebarlist.html
  - browsedb_pwdlist.html
  - browsedb_list.html
songinfo.html
search.html
  - pagebarheader.html
  - pagebar.html
  - pagebarlist.html
  - alphapagebarlist.html
  - browsedb_list.html
setup.html
*.html under html directory

#### Non-Template Requestable Items

Certain requests made to the Squeezebox 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):
  - 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
    - 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 Squeezebox Server, and the third are provided to specific pages by Squeezebox 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

##### Squeezebox 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. Squeezebox 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
browserType
  An attempt at guessing what browser is being used. Possibilities are IE, Firefox, Opera, Safari, and unknown.

##### 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 Squeezebox 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, Squeezebox 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.

- 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.
{&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 %]