Version History is available here
Currently, downloading is available to approved testers only.
Go to Download page
If you would like to be a tester, contact Spud at firstname.lastname@example.org.
The following is prototype documentation. It should give you a good idea how the machine works, but is subject to change prior to the machine being released for download.
The code, folder, and images required to implement Spud's Amazing Website Machine are provided in one .zip file or one .rar file. Download one of these files to your computer and decompress it somewhere on your hard drive.
When the package in unpacked, several folders will be created. These folders are required for proper operation of the machine, and are described here.
Contains standard background images. That's the image that repeats in the background of the page. Also, any uploaded background images are stored here.
Contains standard foreground images. Those are the images that appear on the left of the page. Also, any uploaded foreground images are stored here.
Semi-transparent overlays and underlays area stored here.
This is where your .m3u playlist files are stored.
Miscellaneous site interface graphics.
Optional. Contains images for the knob-style menu.
This is where uploaded song art is stored.
This is where your site management code is stored.
This folder should be password protected to keep other people from changing your site. More on how to do that below.
This is where your uploaded songs will be stored. If you already have a folder with your music in it, you can specify the name of this existing folder on the site management page.
This is where the 'stream all' playlists (.m3u files) for your albums will be stored.
This is where you should put lyrics for your songs, in simple text files, with the extension txt. More detail below.
This folder contains some special files needed to hook your site up to your front page, and a template file for Blogger users. You do not need to make a templates folder on your server (although it won't hurt anything if you do), and do not upload these files until you are ready to go live, as described at the end of this documentation.
You need to upload all of the unzipped files to your webspace somehow. Usually, this is done with an ftp client. If you use Firefix, there are some add-ons that will do the job, such as Fire FTP. Essentially, you are copying the files from your computer to another computer somewhere else in the world, which is your website's server.
When you connect with your server through FTP, you will see a number of folders, which will vary depending on the configuration of your server. Your files need to go at the root of your publicly available webspace. There are several possibilities:
If you see an index.htm or index.html file when you connect, you are at the right place. Put your files there.
If instead, you see a bunch of folders, and one of them is the name of your domain, open it up and put your files in there.
If there is a folder called public_html, your files go in there.
If you are unsure, contact your webspace provider, or go read their faq to find out where to put your files.
When you upload your files, you must make sure that everything goes into the proper folders. If your ftp client does not do this automatically, you may have to make the folders yourself before uploading. All of the files may be transferred in binary mode, if there is a choice in your ftp client software.
Optionally, especially if you already have a website and are using Spud's Machine for a music management component, you may want to create a folder (such as 'music'), and install the files there.
Initially, the machine is not linked to the front page of your site. This is so you can configure it, upload your own graphics, songs, etc., and fill in the content before it goes live on your website.
To preview the site using your web browser, go to your domain and add /news.php after the domain name, i.e. http://www.mysite.com/news.php
Before you can explore any of the other pages, you must first do a little configuration:
To configure the look and feel of your website, and to add content, go to yoursite.com/manage (replace yoursite.com with your real domain name).
From this main management page, select 'Manage Design'. This will take you to the main site configuration page, whose features are described here:
Here is where you control the images that are used on your site. There are three sub-sections here.
From the drop-down list, there are a number of provided background images from which you can choose. These are normally small images that repeat in the background of the entire site.
If you want, you can make up your own background image and upload it. If you do, be sure to provide a name for the drop-down menu so that you can select it!
From the drop down list, there are a number of provided foreground images. That's the image that you see on the left of the page, and it usually includes your logo, a picture of you, or whatever you want. For that reason, you probably won't use one of the provide images, but they are there for demonstration purposes and to give you ideas about what can be done.
If you want to create your own foreground image, use the following specificiations:
376 pixels wide by 800 pixels tall. Of this, the image should not usually extend to beyond the leftmost 360 pixels, in order to leave a 16 pixel space between your image and the site content. In certain cases, you may wish to encroach on this 16 pixel gutter with shadows or other special effects.
For best effect, do not crop the image against the right or bottom sides. Cropping to the left and top are OK, because those are the edges of the browser page.
Transparent .png is best. If the graphics or pictures in the image are set onto a transparent background, it will allow the background image that you select to show through. Transparent shadows work very will in this situation, as you can see in the Spud's Amazing Website Machine graphic to the left.
If your imaging software does not create transparent .png files, you could consider either using a transparent .gif, or as a last resort, tiling the background into the background of the image yourself and using a .jpg. This can be a bit tricky, so I don't recommend it, unless you require IE6 (which doesn't support transparency in .pnt files) compatibility.
Selecting one of these options will put an underlay under the content on your site, which will serve the function of making the background less busy below your text, so it will be easier to read. If you have a very busy background, select a higher level of opacity for the underlay.
If you background is not busy at all, you can set the opacity to zero and ignore the color, and your content will be placed directly on the site background.
Caution: If your users view your site in IE6, this underlay will not be displayed, so if this is a requirement, test your site with opacity set to zero to make sure that it is readable.
Here is where you control the color and font of the various text on your pages, as well as select your menu style and color options.
This is the text that appears in the top level menu (NEWS, ABOUT, MUSIC, etc., on this site). You can pick the font, the color, and the color that the text changes to when the user's cursor rolls over the text.
There are a number of different menu style available for your site. Pick one.
Menu Bar Color and Height
Certain menu styles are further configurable by color and height. Other image-based menu styles ignore these options.
Title Font and Color
This is the main title text for each page. On this page, it is the text that says 'Spud's Machine: Download'. Select a font and a color.
Sub Title Font and Color
Controls the font and color of page subtitles.
Body Text Font, Color, Link and Rollover Colors
These options control the style of most of the text on your pages, including the color of links and what color they turn when rolled over.
A number of basic site information and layout options.
This is the name that appears at the top of every page below the menu. On this site, it is 'Spud's Web Machine'.
Site Address (URL)
This is the website address that someone would type to get to your site. For this site, it is 'http://www.cybertoys.org'. Do not include a trailing '/'. If the Machine is installed in a folder, include this, e.g. 'http://yoursite.com/music'.
Web Machine Folder:
If the machine is installed in a folder, rather than at the root, put the name of that folder here, e.g. 'music'. Otherwise, leave this box blank (the default).
This is the folder that your .mp3 files will be uploaded to (in sub-folders for each album). If you already have a folder with your music in it, you can change the name in this box. "Songs" is the default. When you create an album, a folder will be created within this folder for that album's songs.
This is the email address that will appear on your site's contact information on the front page.
Horizontal Line Color and Thickness
Certain areas of the site use a horizontal line to separate items. You can specify the color and thickness of that line here. If you don't want any horizontal lines, set the thickness to zero.
Generally, this will be 'manage_news.php', which is the machine's internal news editor. However, if you want the site to use information from Blogger, you can put 'http://www.blogger.com' in here to take you to the front page of blogger where you can log in and post to your blogger site.
Left Image Link
If you want the image on the left to be linked to a page on the site, enter the URL of that page here. Most users have found this link to by annoying because the graphic is very large and easy to accidentally click on, so they leave this box blank.
Your "manage" folder should be password protected so that no one but you can change the configuration or add content. Information on doing this can be found at these excellent websites:
I have provided several reference that may make more or less sense to you depending our your comprehension of geek speak. Undoubtedly, this is one of the hardest parts of configuring your site, and will make everything else look really easy.
If you can't figure any of this password protection out (and I wouldn't blame you), another approach is to simply rename the "manage" folder to something that only you would think of. This isn't as secure as password protecting it, but it will prevent the casual user from making a mess out of your site.
ADD YOUR CONTENT
The rest of configuring your site involved adding your specific content. This includes a news page, a bio page, your music files, a list of links, and a general-purpose page called MISC.
All of this content is added through a number of web forms that are accessed through the 'manage' section of the site, as follows:
Your news page is similar to a blog in that it contains a number of articles or posts that have a headline, a date, and a body. However, it differs from a blog in that you can arrange these posts in whatever order you want on the page, and there is not archive for preserving them once deleted. I think of them as the most current content on your site.
From the 'Manage News' page, you can either Submit New News, or Manage existing news, if any.
Submit New News Item
This form gives you a place to put a title and your news. That's it. The only other item to select is whether you want the item added to the top or the bottom of your news page. Pretty simple, huh?
Just above the text entry box, there are number of buttons provided at the top of the text box that you can use to format your text:
These should be used as follows:
Type a line of text, then press ENTER to put the text on a line by itself. Now select the text with your mouse, and press the SUBHEAD button. Tags will be added that will cause the text to display as a level 2 head. The title of your new item is automatically a level 1 head.
Bold, Italic, Del, Ins
Select the text and press the button. Tags will be added.
Type the URL, select it, and then press the LINK button. The appropriate html tags will be added. You can edit the text inside the tags to say something other than the URL if you want.
Type the URL of the image, selected it, then press the IMG button. The appropriate html tags will be added.
For the more experience user, you should note that you can use html in these news posts to bold face type, add images, etc.
When your press the SUBMIT button, the item will be added to your news page.
Manage Existing Items
You can edit existing items, move them up and down the page, or delete them when they are out of date.
To edit a news item, just click on the title of the item. You will be taken to a page very much like the "Submit News Item" page, except that it will already be filled out. Make whatever changes you want (including changing the date or putting something else entirely in the date location), and submit the edited news.
To move items up and down or delete them, use the button next to each item, which are in order from left to right as follows:
Move item to top of page
Move item up one
Move item down one
Move item to bottom of page
These buttons are used throughout the management section to move items up and down the various lists that they are on.
To see the results of any editing you have done, click the NEWS item on the main menu.
The interface for editing your bio is a simple text box into which you can type your bio. As you will see, you can really use this page for any content that you want, as you can change the name from BIO to whatever.
In addition to simple text, there are number of buttons provided at the top of the text box that you can use to format your text:
In addition to the buttons in your news edit there is one more, since there are no automatic heads in your bio. It is completely optional, but allows you to add a little more formatting to your bio page if you like:
Type a line of text, then press ENTER to put the text on a line by itself. Now select the text with your mouse, and press the HEAD button. Tags will be added that will cause the text to display as a level 1 head.
This is where the action is. Here, you can create albums, upload songs, add album art, lyrics, and specify how albums are to be displayed. The various options are as follows:
Create New Album
All songs are uploaded into albums, so if you want to categorize your music into albums, you will first have to create them. If you do not create at least one album, your songs will be uploaded into an album called "default", but will show up only as a list of songs, not inside of an album.
When you create an album, you will have a number of items to fill out on the web form:
Add to top or bottom of list
This is the name that will be displayed on your Music page.
This is the name of the folder that will be created as a sub-folder of your music folder where songs uploaded to this album will be stored. Please follow web-safe file naming standards including no spaces, and no funny characters. Best to stick to letters of the alphabet, numbers, and the dash and underscore characters to be safe.
Associated .m3u File:
I am not sure why I left this up to you, but I did. Pick a simple name, following the web-safe standards mentioned above, followed by the extension '.m3u'. The file will be created automatically.
If you already have a .m3u file for this album, you may wish to put the URL of that file in the box below, but for the life of me, I can't figure out why you would want to do that. I may remove this option in the future so that all playlists can be managed automatically.
This should ba a 150pixel square image representing the album (like the album cover, duh). If you already have one on line somewhere that meets that criteria, you can enter the URL in the box below instead of uploading one.
If there is no album art, enter 'none' (without the quotes) in the second box.
This is the text that will appear under the album's title on the Music page. Use your judgement, but I would advise keeping it short and to the point. Let the music speak for itself. But as I said, that's up to you.
Song Display Format
This option controls how the songs will be displayed on the Album page.
If you choose 'Full entry with picture and description', each song's art and description will be displayed on the page, together with a full media player bar, download and lyrics options.
If you choose 'List Only', only the title of the song will be displayed next to a simple "play" button, along with options to download the song or view the lyrics, if any.
When you press the SUBMIT button, the album will be added to your Music page.
Change Album Order
A list of albums will be presented. You can move them up or down or delete them, using the buttons which operate the same as the news list button described above.
Submit New Song
This page allows you to create a new song entry within an album by uploading the music, the art, and the lyrics, and adding a name and a description. The fields are as follows:
Add to Album:
Select the album that you want to add this song to. DO NOT FORGET TO DO THIS, or you will have to upload the song all over again. Don't say I didn't warn you.
Add to top or bottom of list
This is the name that will be displayed on the Music or Album page.
This should ba a 150pixel square image representing the song. If you already have one on line somewhere that meets that criteria, you can enter the URL in the box below instead of uploading one.
If there is no song art, enter 'none' (without the quotes) in the second box. If your album is being displayed in 'List Only' format, the art will not be used, so there is no point in uploading it.
This must be a .mp3 file. Use the 'Browse..' selector to find the song on your computer's hard drive.
If the music file is already on line, you can enter the URL in the box below instead of uploading a new one.
Browse to a .txt file on your computer that contains the lyrics of the song. This must be a PLAIN TEXT FILE, containing no formatting or other junk that word-processors like to put in there. Windows users, if you are unsure how to make a plain text file, use Windows Notepad (NOT Wordpad). Mac users, use SimpleText, if they're still shipping that. If you must use a word processor, use Save As... to save it as type 'Plain Text', making sure that it has a .txt file extension.
You do not need to include the name of the song in this file, as it will be displayed automatically on the Lyrics page, but you should give the file a unique name (following of course, the web-save conventions discussed above), so that your lyrics files don't over-write each other. For example, DON'T name it lyrics.txt.
If you already have such a file on line somewhere, you can enter the URL in the box below, but this feature seems to be a little flaky. I don't advise it.
As with the album description, this is the description that will appear under the song title. If your album is being displayed in "List Only" format, this description will not be displayed, so you can save your time and ignore it.
When you press the SUBMIT button, the song will be added to the selected album.
Edit Existing Album or Song
Below the preceding options will be a list of Albums and Songs that you can edit individually by clicking.
Edit Existing Album
Clicking on an Album title will bring up a page very similar to the one that you used when you created the album, except that everything will be filled out. Use this option to make changes.
One additional item on this page, near the top, allows you to change the order of the songs on the album using song-order buttons as discussed above.
Edit Existing Song
Clicking on a Song Name will bring up a page very similar to the one that you used when you first uploaded the song, except that everything will be filled out. Use this option to make changes, including uploading a new song file, song art, or song lyrics if necessary.
See 'Manage Bio'. This is exactly the same, except that it's called Misc by default. You can change the name to anything you want, and you can use the buttons to format the text and add links and images.
You can either Submit a New Link or Edit Existing Links and Categories by moving them up and down or clicking on their name to change their contents.
Submit New Link
Selecting this option brings up a page where you add a link to an existing category or create a new category of links.
As usual, the new link (or the new category) can be added to the top or bottom of the existing list.
Select either an existing category or the item "NEW CATEGORY".
New Category Name:
Enter the name of the new category, only if you have selected the NEW CATEGORY option in the "Link Category" selector.
This is the text that will be displayed on the Links page.
This is the URL of the page that you want to link to. Always use the full address of the page (i.e., include the http://).
Pressing the SUBMIT button will add the link to the Links page.
Edit Existing Link
This will bring up a form similar to the Submit New Link form, except that everything will be already filled out. You can change the name of the link, the URL that the link points to, and even which category the link is displayed under.
Edit Existing Category
The only item that you can edit is the Category Name. That's all there is.
The names of all top-level menu items (i.e. NEWS, BIO, MUSIC, MISC and LINKS) can be edited on this page.
The first five items are pretty obvious. Enter the text that you want to display for each item. This text is used on both the menu and on the title of each page. Keep it short. When you are done, have a look up there at the top and make sure that it fits. In general, about 8 characters is a good maximum.
The last two items control how the text is displayed in the two locations where it is used:
Display in menu as:
This is the menu at the top of the screen. You can choose between Mixed Case, All Upper Case, or All Lower Case.
Display on pages as:
Same three options, only this controls how the text is used on the body of the pages, rather than in the menu itself.
Once everything is working, you are ready to go live and hook this thing up to your front page. There are several ways to do this, depending on your goals.
If you already have a front page and don't want to change it, simply create a link to news.php (or whichever page you prefer to have them start on). That's it. Done.
If you want users to come directly to your front page, you can use an html redirect in your index.html file to send them to news.php or any other page. There is such an index.html file in the 'templates' folder that you can copy to the root of your webspace.
This is considered a temporary and somewhat hinky solution, however, because if someone comes to your site, and then they press the 'back' button on their browser, they will hit your index.html again, and again be redirected back to your site. Kind of annoying.
The best way to permanently redirect to your new site is with a .htaccess file. You will find one in the 'templates' folder as well, however, it will need a little editing (with a plain text editor!).
Open up 'htaccess.txt' file, and change the name of the domain from cybertoys.org to your domain.
Upload this file to your site using ascii mode in your ftp client.
Change the name of the file to .htaccess (add the period at the beginning and get rid of the extension).
If you already have a .htaccess file at the root of your webspace, it might contain important instructions regarding your server configuration. You will want to upload it to your computer, add the one line from the one provided in "templates", and re-upload it to your server following the process described above.
If all this fails, go back the HTML redirect method. Sorry...
SUPPORT SPUD'S AMAZING WEBSITE MACHINE
If you get it all working, you might consider making a donation to Spud's beer fund. It will encourage him to keep working on this thing, adding features, fixing bugs, etc. You can click the potato to make your own personal contribution via paypal: