[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
- html
- slimp3.exe (or slimp3.pl)
- other items...
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.
- 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".
- {%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.
- {¶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.
- {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
in order to prevent line wrapping in the middle of text.
- [E]text[/E]
-
The E directive replaces text with its URL
escaped equivalent.
- [
- ]
- &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.
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
-
- 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 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):
- 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
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]