A Look into the Inner Workings of the Live365 Station Page Template System

So, exactly just what happens when someone clicks on a link to a Live365 Station Page, anways?!? This document will attempt to explain just that. Let's start from the top...

Somehow, somewhere, someone clicks a link or types in a browser the following:

http://www.live365.com/stations/live365premium
This URL is first encountered by a "thin-layer" Apache webserver, which employs a Rewrite Rule to shift the request to one of our "FAT3" webservers (which, incidentally, are running Mason 1.28 vs. 1.0x running on the normal servers): 
#
# overrides to 5003
#
RewriteRule ^/stations/(.*)   http://10.10.11.173:5003/stations/$1 [P,L]
Note that the page request is internally redirected via Apache to http://10.10.11.173:5003/stations/$1 -- this means that our original URL gets mapped to someting like
http://10.10.11.173:5003/stations/live365premium
Another Apache configuration directive within the FAT3 webserver tells it to treat any file within the /stations directory as a Mason file to be parsed by the Mason engine (READ: don't put anything else but Mason files in this directory, else your GIFS and JPEGS will be interpreted by the Mason engine -- BAD THINGS WILL HAPPEN!): 
<Location /stations>
    SetHandler perl-script
    PerlHandler Live365::Mason
    PerlSetVar MasonDeclineDirs 0
    DefaultType text/html
</Location>

Apache handoff...Mason takes over

Based on the URL, it would at first appear that there must be a /stations directory at the webroot level, and then also a /live365premium subdirectory within that. This is not the case, since we'd then need a subdirectory for every single station on Live365. Well then, how does this work, you ask? If you look into the /stations directory, you'll see a single file called and named dhandler. This is a special type of Mason file that gets triggered when a non-existing file is requested. So, although the URL asks for /stations/live365premium, only /stations actually exists, and the dhandler file gets executed. Aha!

Here's a secret debugging tip: If you append "?dddebug=1" onto the original URL, you can see what the dhandler is calculating. In a nutshell, it parses the station name ("live365premium") from the URL, and also gets the value of the optional "site" parameter (the default value of which is "live365"), and uses those to formulate a new internal URL:

http://[FAT3 WEBSERVER]/scp/live365["live365" IS THE DEFAULT SITE VALUE]/station_info.live?station_name=live365premium
The SCP dhandler performs an internal redirect to this new URL. The rest of the Mason functionality within the template system works off of this secondary internal URL. Note that the URL in the browser window doesn't change, however -- this preserves our legacy "friendly" public URLs for station pages.

So what's next?

We've now finished handling the legacy "friendly" URL support and we're getting into the inner workings of the templating system. At this point, we have a familiar URL pointing to a Mason "*.live" file:
/scp/live365/station_info.live?station_name=live365premium
You're probably thinking that there's a file called station_info.live in the /scp/live365 directory -- and I don't blame you. However, it's a little more complicated than that. In fact, there isn't a file at that location. During the design-phase of the templating system, we thought it'd be efficient to contain the station-page-related files within a single subdirectory within the SCP heirarchy, seperating them from, say, player-window files in /mini...so the station-page files are in a /stn directory: /scp/live365/stn in this case. So ultimately, that's where our station_info.live file actually lives.

Again we're employing a dhandler file to map the /scp/live365/station_info.live?station_name=live365premium URL to the actual file in the /scp/live365/stn directory. The dhandler lives in the /scp directory, and parses the PATH from the URL and also grabs the station_name parameter value. It builds another internal URL (/scp/live365/stn/station_info.live) and performs a subrequest -- we use a subrequest here instead of an internal redirect because we want the subsequent page to inherit properly. If you append "?ddebug=1" (2 'd's this time) onto the original URL, you can see what's going on.

Onwards to the web page!

We're almost home -- we've finally worked out a "solid" path to an existing file. Now we know that we want to get to
/scp/live365/stn/station_info.live?station_name=live365premium
At this point, Mason's object-oriented inheritance features come into play, through the use of autohandlers. There's a top-level autohandler file in the /scp directory, which controls the inclusion of page headers and footers, plus it contains methods and attributes for controlling (among other things) the web-page title, CSS includes, and Javascript includes. You can view some debugging information for this autohandler by appending "?debug=1" onto the URL. Additionally, a secondary autohandler can be placed within each /scp/SITE/stn directory to apply further customization across the set of skinned pages for that SCP.

A Brief Recap

Just a quick summary before we proceed...We've discussed the following key parts so far:
  1. Apache Rewrite Rules which map a friendly URL over to the FAT3 servers.
  2. Apache Location directives which activate Mason-parsing for the entire /stations directory.
  3. A "friendly URL" dhandler file in the /stations directory that parses the friendly URL into a template-system-friendly format.
  4. An "SCP" dhandler file in the /scp directory that controls which page-template file is used.
  5. A main autohandler in the /scp directory that lays the foundation for object-oriented inheritance and HTML content-wrapping.
The walk-through outlined thus far describes what happens when someone makes a web page request for our default Live365 look-and-feel. Now let's look at what happens for a skinned/co-branded page...

Now, Co-branding

Let's review the previous discussion, but now assume that the original URL looks like
http://www.live365.com/stations/live365premium?site=pro/green01
When you click on the link, you'll notice that the page is green and is missing a header and footer, plus the content of the page is slightly different. This, of course, is controlled by the template system. All of the previously-discussed Apache processes happen exactly the same way in this skinned case. The first difference we encounter occurs in the "friendly URL" dhandler. If you again append "&dddebug=1" onto the URL you'll notice that now our SITE value is "pro/green01" whereas before it was "live365". This parameter instructs the "friendly URL" dhandler (which lives in the /stations directory, remember) to internally redirect to /scp/pro/green01/station_info.live?station_name=live365. Again, there's no station_info.live file in that directory. The SCP dhandler comes into play here, and as before, checks into the /stn subdirectory for the proper file. However, in this case, this file doesn't exist. The SCP dhandler is intelligent enough to walk up the SCP directory tree (currently only 2 layers) looking in each successive /stn directory until it finds the requested file. For our example, this means that the dhandler finds and uses the file /scp/pro/stn/station_info.live. Note also that, although the template file comes from the /scp/pro/stn directory, /scp/pro/green01/local.css is still being used to define the colors and fonts used on the page. Additionally, if any pro/green01 headers and footers existed, those would be picked up, too. This functionality, based on the nested SCP arrangement, allows us to customize headers, footers, and CSS files but still use a single (set of) page template(s).

Other URLS

There are other public-facing "friendly" URLs besides the link to the station page:
DJ Profile: http://www.live365.com/profiles/live365premium

Broadcast Schedule: http://www.live365.com/stations/live365premium/schedule

The mechanism supporting the DJ Profile URL works in much the same way as the Station Page URL -- the main differences are a second set of Apache config parameters to support the /profiles directory, another Mason dhandler in the /profiles directory, and instead of redirecting to "station_info.live" we switch to "dj_profile.live" The dhandler within the /scp directory executes as before, but now looks for "dj_profile.live" in the various /stn directories.

The functionality behind the Broadcast Schedule URL is contained within the /stations dhandler -- if "/schedule" exists in the URL, the dhandler redirects to the scheduler page vs. the normal station page. This can be expanded to handle additional pages as the need arises.

Additionally...

Once the final web-page template is resolved, that template file establishes the layout of the content-area of the page by including component-modules in a specified arrangement.