Skinning AmphetaDesk

The user interface for AmphetaDesk is controlled by files located within the /templates/ directory of your installation. This directory is further divided up into subdirectories, each representing one complete template. By default, AmphetaDesk uses the information stored in the "default" subdirectory (pretty semantic, eh?).

To facilitate your tweaking and visual desires, the following documentation will give you a rundown of the template system, how it works, what's possible, and so forth. While having knowledge of Perl will allow you to create advanced templates with the most power, a decent text editor with syntax coloring will allow you to focus on only the HTML.

This document is not yet complete.

How To Not Screw Up

Your first step is to make a copy of the default templates shipped with AmphetaDesk. This insures that if you do something weird or silly, you'll always have a backup copy to fall back on. We all want to play - knowing there's a backup allows us to throw caution to the wind.

If you look in the /templates/ directory of AmphetaDesk, you should see a subdirectory called default. This contains all the files that make up the default visual look shipped with AmphetaDesk. Make a copy of it, and call the duplicate whatever you want - just make sure to include the "_" character before your name (the "_" tells AmphetaDesk not to display that directory as a template choice). For example, you may want to call it _default_backup or something equally exciting. After you've made the backup, you can continue on to edit the files within the default directory.

A Brief Template Introduction

The templates are made up of both HTML and Perl - HTML is used for the actual display, and Perl is used to process the data and make it suitable for consumption (via the HTML display). The template backend is implemented via Text::Template and interested Perl coders should read through the POD to get a stronger background of what's possible.

Perl code is ONLY processed if it's between special delimiters. An example:

# this is plain, boring HTML code.
<strong>AmphetaDesk v0.93</strong>

# this uses Perl to spit out the same thing.
# notice the [$ and $] delimiters. they're important.
[$ $OUT .= "<strong>AmphetaDesk v0.93</strong>"; $]

# this uses Perl to get the same information from 
# the internal settings created by AmphetaDesk.
[$ my $name = get_setting("app_name"); 
   my $version = get_setting("app_version");
   $OUT .= "<strong>$name v$version</strong>"; $]

The best way to learn the templates is to jump right in with a text editor. When you first open the templates, you'll notice a decent amount of text within those [$ and $] delimiters. This is necessary, as the Perl code builds the HTML that is ultimately displayed to the browser. If you're just looking to tweak the HTML, be on the lookout for $OUT - any time you see that variable, the data to the right of it will be sent to the browser for HTML display (as per the second and third examples, above). Frequently, the $OUT line will have variables on the right side as well:

[$ $OUT .= qq{ The channel's XML URL is $channel->{xmlurl}. }; $]

By the time this line of code gets to the browser, it'll simply be:

The channel's XML URL is

If you're looking to customize only the HTML display, again, focus on the $OUT lines. Other variables that are located on that line (like $channel->{xmlurl}, $item->{link}) are named in such a way that they should be easy to determine their purpose. If you have any problems, don't hesitate to email with questions.

If you're a Perl coder, all code has been documented within the templates, and further information about the various routines used can be found within the matching modules located in ~/lib/AmphetaDesk/. Anything you can do with Perl is possible within the templates (you may run into module dependcy issues, though). As above, if you have trouble, email for help, or keep watch for new HOWTO documentation.

Changes made to the templates are effective immediately. A good way to learn what does what is to have AmphetaDesk running, tweak the templates a little bit, and then refresh the page within your browser to see the results.

Customizing the OS GUI

Depending on your OS, AmphetaDesk also opens a normal window that takes care of log messages and alerts you to its progress as it checks for new channel data and so forth. Quite nicely, this window is also customizable (or at least, the logo and icons are).

To mess with these, take a look in the /gui/ subdirectory of your template. You'll notice eight files, controlling the logo and icons for different OS's that AmphetaDesk runs on. Keep the file formats (and the height and widths) the same, and you'll be seeing your own images adorning the AmphetaDesk window in no time.

I'm Done! Now What?

If you completed a skin for AmphetaDesk, and you think it's worth it, we'd love to see it and tell the rest of the AmphetaDesk audience about - just tell and he'll take care of you (tender loving care, awww).