Live365 Station Page Template System -- SCP Quick-Start Guide

Table of Contents

  1. overview
  2. where things live
    • components
    • stylesheets
    • template files
    • images
    • mini
    • a word on site architecture
  3. making a basic skin
    • CSS
    • [header]
    • [footer]
  4. creating an advanced skin
    • customized templates
    • customized functionality
    • a note on components
  5. other issues
    • player window skinning
    • "friendly" URLs for station & profile pages
    • site takeovers
    • authorization for pro SCP accounts
  6. glossary

Overview

The Live365 Station Page Template System is designed to allow rapid deployment of cobranded station & DJ-profile pages at a variety of customization levels, from a simple color change to full-blown custom page layouts and functionality. The "Live365 cobrand" is utilized as the default look & behaviour for the entire system, which is configured to allow us to layer on additional cobranding schemes in a scaleable manner. The dynamic content used on various pages has been broken down into reuseable, "building block" components, which can be rearranged on customized pages as desired (this also eases maintenance hassles because fixes and upgrades happen in a single file). Cascading stylesheets are used to full potential, with selectors & classes rationally corresponding to the content-components, and by nesting them appropriately to maximize their inheritability.

Where Things Live

A custom skin for a Live365 SCP account involves a combination of CSS files, header and footer files, images files, Mason template files, and Mason components. These building blocks live in the following locations on the file system: 
	/u01/apache_live/htdocs/mc/components -- reuseable Mason components used as 
		"building blocks" for pages within the templating system
	/u01/apache_live/htdocs/scp -- main directory containing all SCPs
	/u01/apache_live/htdocs/scp/live365 -- directory containing the Live365 SCP 
		files; this directory also serves as the generalized/default location for 
		CSS and template files used within the entire template system (more on 
		this later)!
	/u01/apache_live/htdocs/scp/live365/local.css -- the Live365 skin,
		which serves as the default look for the system
	/u01/apache_live/htdocs/scp/live365/stn/station_info.live -- the default
		Live365 Station Page layout template.
	/u01/apache_live/htdocs/scp/live365/stn/dj_profile.live -- the default
		Live365 DJ Profile layout template.	
	/u01/apache_live/htdocs/scp/SCPPATH/local.css -- stylesheet used to define the skin
	/u01/apache_live/htdocs/scp/SCPPATH/images -- image folder containing any local 
		images for the skin
	/u01/apache_live/htdocs/scp/SCPPATH/stn -- folder containing any custom templates, 
		header or footer files, and autohanders
	/u01/apache_live/htdocs/scp/SCPPATH/mini -- folder containing player-window files 
		(mini.css, mini_tmpl.html, /images, etc.)
	/u01/apache_live/htdocs/scp/pro/SCP -- folder containing all pro-only skins 
		(green01, blue01, tan01, etc.)
Note that in the above listing of directories, there is a specified and logical subdirectory nesting order: Generalized SCPs (e.g. site takeovers) live in the htdocs/scp folder, while specialized SCPs (e.g. pro-broadcaster skins) live in a distinct folder (e.g. htdocs/scp/pro). Station-page template files live in their respective htdocs/scp/*/stn folder ("stn" implies "station", get it?), player-window files live in their htdocs/scp/*/mini folders, etc. MAINTAINING THIS ORDER IS CRUCIAL to the functionality of the templating system! It's also neater. The templating system relies on this directory structure to define the order of inheritance for CSS, HTML content-wrapping, and object-oriented features. Note that, regarding CSS and template files, the htdocs/scp/live365 directory serves as the default bucket -- specifically: Suppose we wanted to make a skin for a new SCP partner, Virgin.com. Let's name this SCP 'virgin'. There are a few ways we could go about creating a skin, depending on the requirements and level of commitment (read: $$$) from Virgin.com...

Making A Basic Skin

A basic skin will involve little more than customized colors overlaying our existing (station) page layout. This is achieved by creating a stylesheet which overwrites only the default values for various fonts/colors/background-images/etc. on the pages in question. This stylesheet would live at htdocs/scp/virgin/local.css The cobranded pages won't have a header or footer unless we create them -- this may be okay if the intent is to frame our pages on another website. Let's pluck the header/footer HTML code and CSS classes from Virgin.com's Entertainment channel, clean things up to fix any local links and image URLs, and place the HTML in local files called htdocs/scp/virgin/stn/header.mc and htdocs/scp/virgin/stn/footer.mc. The CSS classes can go in our htdocs/scp/virgin/local.css file.

So, with only an hour or so of basic HTML and CSS work, we've created something that can (more or less) be used for a site takeover or something similar. As mentioned, building a header and footer is completely optional -- if none exist, nothing is plugged into those spots on the pages.

Creating An Advanced Skin

The steps for making a basic skin outlined above demonstrate how customized CSS and header/footer files can replace/override the default look-and-feel of the Station Pages. These additional files are plugged into the template system and are used along with the standard page-layout templates (aka the Live365 skin) to impart basic color & text changes to the standard layouts.

Taking this "replacement" concept further allows us to make heavily-customized pages where conditions warrant -- we can create and insert customized page-layout templates into a given scp's "/stn" folder to create alternate layouts. Furthermore, these folders (plus a bit of additional Mason code) can be arranged in such a way that the custom layout is used for a subset of skins -- this is how the default grey PRO skin and all the premium coloured skins are set up. PROs use these alternate layouts because they do not need headers or footers, nor do we want to include several standard content-components like ads, VIP Station Info, and Broadcaster Station Picks (which are included on the default Live365 layout).

Here is an example of a skin with a customized Station Page layout. Note how the page colors, fonts, header/footer, and layout are customized, while the page's content is still the standard set of "building block" Mason content-components. The following files were created to implement this SCP: 

	/u01/apache_live/htdocs/scp/jimgdemo1/local.css -- custom stylesheet
	/u01/apache_live/htdocs/scp/jimgdemo1/images/a.gif -- header graphic
	/u01/apache_live/htdocs/scp/jimgdemo1/stn/station_info.live -- custom page template
	/u01/apache_live/htdocs/scp/jimgdemo1/stn/header.mc -- custom header
	/u01/apache_live/htdocs/scp/jimgdemo1/stn/footer.mc -- custom footer

In addition to customizing the look-and-feel of pages for an SCP, we also have the ability to modify some of the template-system's functionality on a per-SCP basis. The top-leve Mason autohandler defines several methods and attributes which controls the output of the template system. For example, method "getTitle" controls the HTML-page title. These methods can be overridden by any children (e.g., sub-level autohandler or *.live Mason page) within the system to customize the output or functionality.

An important point to remember is that Mason sub-components (*.mc files) can NOT overwrite methods and attributes. In fact, there is no object-oriented-style inheritance within these files. The workaround for this limitation is either to get a reference for the parent component (aka *.live file) via $m->request_comp from which you can get attribute values via $m->request_comp->attr('foo'), or to call methods as <& REQUEST:getTitle >. See the Mason Request Class documentation for more info.

Other Things To Know

Additional issues related to SCPs and skinning include player window cobranding, site takeovers, PRO broadcaster authorization, and station and profile page friendly URLs.

Player-window skinning is accomplished in the same manner as before the new Station Pages. Each SCP folder has a /mini subdirectory containing relevant CSS, HTML template files, /images directory, etc.

There exist "friendly URLs" to allow users/broadcasters to easily link to their station pages and/or DJ profiles without involving a complicated URL:

These links are facilitated by combining some Apache-configuration magic (consisting of Rewrite Rules to force the /stations and /profiles directories to be handled by the Mason engine) and Mason dhandler files in both directories (to parse the URL for the station name and the optional site parameter) to map the requested URL to the proper SCP directory which ultimately controls any web page customization.

Site takeovers can now be accomplished by hardcoding the SCP name in the main redirect Mason "dhandler" files: /u01/apache_live/htdocs/stations/dhandler and/or /u01/apache_live/htdocs/profiles/dhandler These files parse the "friendly URL" for a station name and also normally take a "?site=foo" parameter. These two inputs are then mapped to the desired SCP folder. This regular mapping can be interrupted to conditionally point to a specified SCP folder (e.g., $site = 'takeover' if ($site eq 'live365' or $site eq '');)

You might notice that you cannot apply a PRO skin to a non-PRO station -- attempting this will only result in the station's page being displayed in the default Live365 look & feel. Additionally, you cannot apply a Premium PRO coloured skin to a Basic PRO station. These types of checks are ideally located within the autohandler for each skin -- that way the business rule will automatically apply to any/all web pages within that folder. For example the PRO/non-PRO check is located within the PRO autohandler: if the specified station is not a PRO station, the user is redirected off to the default Live365 skin. Additionally, the getScpPath method checks to see if the station is a Premium PRO station and if not defaults the SCP Path to /scp/pro instead of, say, /scp/pro/green01.

Glossary

autohandler
See the Mason documentation.
cobrand
Another name for an SCP.
dhandler
See the Mason documentation.
scp
S.C.P = Syndicated Content Partner? The name given to the custom skin. Note that is is often, but not always, the same as the custom-skinned station name.
scp path
The SCP name plus the SCP-subdirectory containing that SCP (if any). For example, "pro/green01" is the scp path for the green01 skin which lives within the pro subdirectory, since it is a pro-only skin.