Skin development

Skin Development

The heart of skins on SqueezeCenter is the Template Toolkit. SlimServer builds all of the web interface using a set of templates called a skin.

Inheritance

If a skin is missing a particular template, it uses the template from its parent instead. Currently, all skins have only the EN skin as their parent. To specify another skin as a parent (in addition to EN), create a file named /skinconfig.yml/. /Skinconfig.yml must begin with — (three dashes) on the first line. To specify inheritance, add the following (this case adds Default skin as a parent):

skinparents: - Default

---

Components

In order for plugins to more readily fit in with a skin without specifically targeting it, a set of standard components is defined by each skin. These components are contained in a few basic files, which are made available to every other template through the use of the PRE_PROCESS configuration option.

hreftemplates (perhaps /commoncomponents.html/ is a better name?)

This file contains the basic href elements that are used for browsing and control within skins. It should be general enough for all skins to use unmodified to allow for easier maintenance and reduced chances of broken links. If for some reason a skin requires a slightly different version of a few of the hrefs in this file, but not all, the BLOCKs in this file can be overridden by placing a different BLOCK with the same name in the cmdwrappers file.

It contains the following href variables, which will most likely be eliminated in favor of BLOCKs after the switch to looping in TT as opposed to Pages.pm is made.

• /albumHRef/
• /yearHRef/
• /songinfoHRef/
• /browseDbHRef/
• /coverArtHRef/
• /browseTreeHRef/
• /browsePlaylistHRef/

There are also some utility non-href variables:

• /playerURI/ = the player variable passed through the uri filter
• /MoveUp/ = "-1" uri encoded for use with /cmdMoveHRef/
• /MoveDown/ = "+1" uri encoded for use with /cmdMoveHRef/

It also contains the following BLOCKs, which must be either PROCESSed or INCLUDEd

• /homeLink/ - duplicated in cmdwrappers, should eliminate one
• /savePlaylistLink/
• /downloadPlaylistLink/
• /clearPlaylistLink/
• /thumbnailImg/
• /statusImg/
• /coverImg/
• /cmdRemoteURLQuery/ = the query portion of the href used for commands on RemoteURLs
• /cmdLocalQuery/ = the query portion of the href used for commands on local files
• /cmdNumericQuery/ = the query portion of the href used for commands using the playlist item number
• /cmdHRef/ = the href used to perform playlist commands
• /albumItemHRef/ = the href used to access the item's album in browsedb
• /songinfoItemHRef/ = the href used to access the info for an item
• /coverArtItemHRef/ = the href used to access the cover art for an item
• /browsePlaylistItemHRef/ = the href used to access a particular playlist in browse_playlist.html
• /browseDbItemHRef/ = the href used to access a specific level in a hierarchy in browsedb
• /browseUpnpItemHRef/ = the href used to access items delivered from a UPnP server
• /browseTreeItemHRef/ = the href used to access a specific path in the music directory tree
• /ItemHRef/ = a generic item which either returns the href key of the item, or the item itself

There is also a couple of variables which are used to change generic command types (play, add, insert, remove) into the specific commands to be used:

• /urlcmdFor/ maps to the commands used for remote URLs (or paths)
• /cmdFor/ maps to the commands used for local database items
• /numcmdFor/ maps out the numeric based commands (jump, move, delete)

---

cmdwrappers

This file contains the look and feel portions of a skins use of commands, so that plugins can blend in to the general look of a skin. Each skin should implement all the BLOCKs defined below, as errors will occur if a plugin attempts to use a BLOCK which isn't defined. IF you do not need all of the BLOCKs for your own skin, you may implement a subset in a file called /cmdwrappers_<skinname>/. This will override any !BLOCKS using what you provide, and fall back to using the /cmdwrappers/ file from EN for the rest. To activate this file, add the following to your /skinconfig.yml/ file:

preprocess: - cmdwrappers_<skinname>

Variables:

• /statusroot/ - declares whether this skin uses 'status.html' or 'status_header.html' as the target page for commands.
• /noHomeLink/ - declares whether the home link should appear in bread crumb link trails.
• /setting_chooser_noHome/ - indicate the desire to include the skins homepage as an option in the settings pulldown menus (new for Slimserver 6.5)
• /controlGraphics/ - specify if you wish to have the standard list controls using graphics. If this is not set, then your skin will use text for controls links that aren't specifically defined in your own /cmdwrappers/ file.
• /browserTarget/ - specify the name of the frame your skin uses for browsing the music library. If not set, the server will assume that your skin does not use frames or that your skin expects all browse links to open in the current frame.
• /useAJAX/ - select if you wish to support various javascript controls and effects via XMLHttpRequest

BLOCKs:

• /playlink/ = wrapper for links which play something
• /addlink/ = wrapper for links which add something
• /insertlink/ = wrapper for links which insert something
• /removelink/ = wrapper for links which remove something
• /descendlink/ = wrapper for links which descend in a hierarchy
• /infolink/ = wrapper for links which show song info
• /listitem/ = wrapper TBD
• /homelink/ - duplicated in hreftemplate (except for capitalization), should eliminate one
• /moveuplink/ = wrapper for links which move something up
• /movedownlink/ = wrapper for links which move something down
• /editlink/ = wrapper for links to edit a list item
• /favaddlink/ = wrapper for links to add a list item to favorites
• /favdellink/ = wrapper for links to remove a list item from favorites
• /dummylink/ = wrapper for filling space, while doing nothing
• /scanwarning/ = shows the warning if we are still scanning
• /crumblist/ - processes the pwd_list array into a formatted bread crumb link trail, possibly move to the containers file
• /crumblistitem/ - formats the individual items in the crumb list, should move with crumblist
• /playlistcontrols/ = controls for the playlist, possibly move to the containers file
• /trackinfo/ = formatted information (title - album - artist) for the playlist item, possibly move to the containers file

---

Stylesheets

• /slimserver.css/ - contains all the major style information. Skins may create their own version to alter the look and feel while using the default templates.

• /skin.css/ - is an optional stylesheet that skins may use when only some style elements need to be change. Anything in the skin.css will override those in slimserver.css, while still allowing the rest of slimserver.css to apply.

---

standardheader.html

This file handles the most commonly used items in the <head> section. It sets up the links to the page icon, the standard stylesheet, and sets the content-type and charset. The <title> tag is also set using the /pagetitle/ variable.

---

pageheader.html

This file handles the formatting of the page from the DOCTYPE through the <head>, opening of the <body>, putting on a page title, setting up the overall table for layout if using one, showing a bread crumb link trail, to showing item counts. It is used so that your skin will present a uniform appearance across all its pages.

Variables used:

• /pagetitle/ - the title of the page
• /pageHeaderInfo/ - usually the item counts
• /pageHeaderMenu/ - preformatted crumb list, will probably eliminate in favor of having callers build their own pwd_list if not using the one generated by Pages.pm
• /pageHeaderScripts/ - a block to support javascripts to be selected by the body template. Usually used to override the scripts included by default, and can easily include some or all of the standard scripts as well as specific extra scripts relevant to the body template.

---

pagefooter.html

This file handles closing off everything that pageheader opened, for example </body>,</html>, any overall layout table, etc.

Potentially we could replace both pageheader.html and pagefooter.html with a single template which does both, something like pagewrapper.html. This would make it easier to make sure that all the opening tags are paired with closing ones.

---

pagewrapper.html

/Not currently implemented/

This file handles the beginning and the ending of a web page. It is wrapped around the page unique content. It would basically take the place of both pageheader.html and pagefooter.html.

Possibly instead of one pagewrapper.html we could have two, leftside.html and rightside.html.

---

helpwrapper.html

/Not currently implemented/

Much like pagewrapper, this file handles the beginning and end of the help pages. Currently, this is done via helpheader.html and helpfooter.html. As some of the current skins basically process pageheader/footer for this, it might be one option to fold this into pagewrapper.html with a "type" param.

---

containers

/Not currently implemented/

This file sets up the basic containers used by skins. This includes their layout. Additions, subtractions, and comments welcome. Some of these items may end up in cmdwrappers instead.

Containers:

• /contentcontainer/ - The container for the overall content of the page. Other names: /listblock/, /listcontainer/. Include any header, footer, class, or id.
• /contentitem/ - The items in the content.
• /controls/ - set this to the name of the controls block you wish you use within a contentitem
• /leftcontrols/ - set this to the name of the controls block you wish you use within a contentitem, typically designed to be shown on the left of the contentitem text.
• /rightcontrols/ - set this to the name of the controls block you wish you use within a contentitem, typically designed to be shown on the far right of the contentitem text.
• /listitem/ - The layout for an generic item in a list.
• /browsecontrols/ - The layout selecting what controls are supported by a skin in the browse list.
• /playlistcontrols/ - The layout selecting what controls are supported by a skin in the current playlist.
• /radiocontrols/ - The layout selecting what controls are supported by a skin when listing internet radio items.
• /playcontrols/ - The layout for the main playback controls currently used in status.html and status_header.html.
• /crumblist/ - The layout for the bread crumb trail.
• /crumblistitem/ - The items in the bread crumb trail.
• /pagebar/ - The layout for the pagebar.
• /pagebaritem/ - The items in the pagebar.
• /alphapagebar/ - The layout for the alphabetic pagebar, possibly could be handled with an alpha variable used by the pagebar BLOCK.
• /alphapagebaritem/ - An alphabetic pagebar item, possibly could be handled with an alpha variable used by the pagebaritem BLOCK.
• /itemcounts/ - The layout for displaying the album-artist-song counts. Could also use /countblock/.

---

javascript

Useful scripts for handling page reloads, player switching and the like are available in html/common.js. This can be included in the pageheader.html or whereever it may be useful via the pageHeaderScripts block. When using the standard server scripts, you will want to !PROCESS the vars.js script to import some important variables into the javascript environment.

Current scripts implemented:

• /resize/ - Takes a src image reference and optional size. If an image is above the given size, the image is contrained. If no width is given, the image will be constrained to the width of the current frame or window.
• /switchPlayer/ - Takes the player list form as its argument. Handles reloading of all frames for the newly selected player. For browse pages, the script alters all of the links instead so that the current browse location is maintained.
• /to_currentsong/ - Takes no arguments. This is used to have the current playlist load so that the current song is achored at the top of the frame.
• /refresh/ - This javascript implements a location replace for the 'now playing' status page. Uses /statusroot/ to determine which page is to be refreshed.
• /doLoad/ - This is a special case for use during scanning. If the page is currently displaying the scan warning (/warn/ variable is present) then calling this script will refresh the home page every 5 minutes until scanning is complete.