[% 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

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

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 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 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 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 Filters

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 &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
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
    - 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
    - browseid3_list.html
Pages::songinfo
  Call tree
    no subroutines called
  Templates used
    - songinfo.html
Pages::browseid3
  Call tree
    - Pages::pagebar
    - Pages::alphapagebar
  Templates used
    - browseid3.html
    - browseid3_list.html
    - browseid3_pwdlist.html

#### Template Parameters

index.html
  Server provided parameters
    path
    player
    myClientState
    webroot
  Expected user provided parameters
    none
browse.html
  Server provided parameters
    path
    player
    myClientState
    webroot
    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
    path
    player
    myClientState
    webroot
    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
    path
    myClientState
    webroot
    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
    path
    player
    myClientState
    player_list
    nofolder
  Expected user provided parameters
    forget
homeplayer_list.html
  Server provided parameters
    playername
    playerid
    player
  Expected user provided parameters
    none
search.html
  Server provided parameters
    path
    player
    myClientState
    webroot
    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
    path
    player
    myClientState
    webroot
    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
    path
    player
    myClientState
    webroot
    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

#### 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 %]