[SET pageicon help] [SET title Skin Creation] [SET techinfo 1] [INCLUDE helpheader.html]

Overview

The web interface to the SLIMP3 server makes use of customizable html templates collected together into a skin. These skins reside in the html subfolder of the folder where the SLIMP3 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 SLIMP3 server builds the page dynamically based on the templates within the skin subfolder. This building is accomplished by replacing items either contained in square brackets [ ] or framed with bracketed directives with the appropriate text.


Directory Structure

SLIMP3 server

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.


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".
{%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.
{&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.
{param}
This directive is replaced with the value of param. If param is undefined, the directive is replaced with the empty string.
[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.
[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.
[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 ("").
[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.
[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.
[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.
[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.
[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.
[NB]text[/NB]
The NB directive replaces spaces in text with &nbsp; in order to prevent line wrapping in the middle of text.
[E]text[/E]
The E directive replaces text with its URL escaped equivalent.
&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.


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
browseid3.html
songinfo.html
search.html
setup.html
*.html under html directory

Non-Template Requestable Items

Certain requests made to the SLIMP3 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

slimp3.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):

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
title
filelength
duration
year
tagversion
comment
bitrate
url
itempath
Expected user provided parameters
songurl
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
[INCLUDE helpfooter.html]