Setup - For Newbies
Setting is split into two sections:
Part 1 - Explains how to edit wimpy.js so that it is properly configured for your website.
Part 2 - Explains how to integrate the player into an HTML page.
Before you begin
1. Download
 Download the Wimpy JavaScript Kit.
2. Unzip and upload
After downloading the package, unzip and upload all of the files to your Wimpy Installation folder.
PART 1
In the first part we are going to edit the JavaScript file so that the JavaScript file refers to the proper locations to the Wimpy files on your site.
NOTE: Throughout this documentation we'll say things like "locations to files," "Internet address' and "URL (Uniform Resource Locator)" -- all of which mean the same thing and refer to the idea of "this is where I want to go on the internet," or," the internet address to a web site or specific file."
1. Open the local copy of wimpy.js in a simple text editor.
The simpler the text editor the better. I recommend Note Pad (notepad.exe), which is usually located here:
C:\WINDOWS\system32\notepad.exe
Make a shortcut to this program and place the shortcut on your desktop, as we will be referring to it a couple more times.
If your on a Mac, I recommend Smultron or TextMate.
2. Scroll down to the line that reads:
wimpySwf = "wimpy.swf";
What you are looking at is called a "variable" -- which means that wimpySwf can vary depending on your needs. You need this variable to reference the URL to wimpy.swf on your web site.
You should have already created a new "mp3s" folder (your Wimpy installation folder) on your web site and uploaded all the Wimpy MP3 Player files to the newly created folder. If you have not, be sure to do so now. Refer to the "installation" instructions for more information.
NOTE: It is a good idea to test the URL before you go to the next step. Usually, I copy and paste the URL into an empty browser window to make sure that i'm "hitting" the right file. (Sometimes my typing can be terrible.)
NOTE: You will notice that there are "comments" in the wimpy.js file. Comments are lines that begin with two slashes //. These slashes are not processed as code, they are overlooked when the JavaScript engine ("Interpreter") reads the script -- so it's a nice way to include "human readable" explanations for how the script works.
If you've purchased a license, enter your registration code into the "wimpyReg" variable.
Example
wimpyReg = "MlRRJTI2OCUzRXhGJTI0JTdEMXlrV3VMcVIlNUZ2cHNaS3ElMkYlM0RLNXN3czQlMkU";
If have not yet purchased a license, leave wimpyReg blank, or leave the existing demo registration "as is" until you decide to purchase a license.
3. Change this variable so that it references the location of wimpy.swf on your web site.
We'll want to set the URL to the wimpy.swf file so that a full URL(or "absolute" URL) is used. By using a full URL (as opposed to a "relative" URL) we will ensure that the player can be used throughout your web site, and not just in the Wimpy installation folder. Click here for more information on the differences between 'relative" and "absolute".
Example:
wimpySwf = "http://www.yoursite.com/mp3s/wimpy.swf";
NOTE: Be sure to keep the URL between the quotes, and that the semi-colon is at the end of the line. otherwise the code will "break."
5. Save the JavaScript file "wimpy.js" and re-upload the file to your Wimpy installation folder.
Example:
wimpySwf = "http://www.yoursite.com/mp3s/wimpy.swf";
6. Clear your browser's cache
By default all browsers store a copy of every page you visit so that next time you visist the page, the browser uses the locally stored file (cached file) rather than re-downloading from the server.
Since we've just edited the JavaScript file, we need to ensure that the newer version of the file is used. Clearing your browser's cache will ensure that your browser downloads the latest version of the files and doesn't use the older, locally stored file.
Click here for instruction on how to clear your cache.
7. Pull up example 1 (readme_wimpy_mp3_js_example1.html) with your browser.
Enter the following into your web browser's "address" field:
http://www.yoursite.com/mp3s/wimpy_js_example1.html
(Of course, you'll want to replace "yoursite.com" with your domain name)
8. Click on all the links to make sure that everything is working OK.
PART 2
In this second part we are going to edit the example HTML files so you will understand the process that you will need to apply to your existing web page(s) in order to use the JavaScript Controls on your web site.
2.1. Open your local copy of wimpy_js_example1.html in a text editor.
Toward the top of the page you will find the following line:
<script language='JavaScript' src='wimpy.js'></script>
Edit the reference to "wimpy.js" so that it uses a full URL to the wimpy.js file on your web site.
Example:
<script language='JavaScript' src='http://www.yoursite.com/mp3s/wimpy.js'></script>
NOTE: You can wrap the URL in 'single quotes' or "double quotes" -- I recommend single quotes, but double quotes are OK too. the reason to use one over the other is if you wanted to include a quote in the reference.
For example, if you wanted to use a URL such as:
http://www.yoursite.com/bob's files/bob.jpg
... the only way to ensure that the apostrophe would work would be to wrap the URL with double quotes. if we wrapped the URL with single quotes, then the code would "breaK" because the apostrophe would act as the last (or ending) quote:
Bad:
'http://www.yoursite.com/bob's files/bob.jpg'
Good:
"http://www.yoursite.com/bob's files/bob.jpg"
Likewise, if we wanted to use a double quote in the URL, we would have to wrap the URL with single quotes:
Bad:
"http://www.yoursite.com/bob said "hi" hello.jpg"
Good:
'http://www.yoursite.com/bob said "hi" hello.jpg'
Another method to allow for single or double quotes "inside" is to escape the quote with a backslash
Example:
"http://www.yoursite.com/bob said \"hi\" hello.jpg"
Or to URL encode the quotes as:
Double Quotes URL encoded = %22
"http://www.yoursite.com/bob said %22hi%22hello.jpg"
Single Quotes URL encoded = %27
'Bob%27s Song'
I do not recommend ever using weirdo characters in any file name or folder name. Try and use only alpha-numeric characters.
The reason I went off on this long explanation is because sooner or later you are going to want to use a file with an apostrophe in your wasp code -- like when you try and reference an FLV video such as:
Bad:
wimpy_addTrack(true, 'bob's song.mp3', 'Bob's song', 'Bob's Album', 'http://www.gieson.com', 'image.jpg')
Good:
wimpy_addTrack(true, "bob's song.mp3", "'Bob's song", "Bob's Album", "http://www.gieson.com", "image.jpg")
It will invariably happen, and now you know why.
2.2. Save _example1.html and upload it to a DIFFERENT folder on your web site.
Example:
http://www.yoursite.com/someWhereElse/wimpy_js_example1.html
2.3. Open your browser and enter the URL to the wimpy_js_example1.html file in the NEW folder.
The track should play. If it does not, go back to step 2.1 and try again.
If the player does work and you want to include the player on an existing page on your site. You will have to edit your existing page by adding the reference to the wimpy.js script in the <head> of your HTML page, then add the call to the JavaScript function somewhere in the <body> tag.
Come again?
OK, open the wimpy_js_example1.html file in a text editor and copy the line that reads:
<script language='JavaScript' src='http://www.yoursite.com/mp3s/wimpy.js'></script>
Then open your existing page and paste the code anywhere between the opening <head> tag and the closing </head> tag.
Example:
<html>
<head>
<script language='JavaScript' src='http://www.yoursite.com/mp3s/wimpy.js'></script>
</head>
<body>
blah blah blah
</body>
</html>
You can only have one set of <head> tags (an opening <head> and closing </head> is one set. Do not put two sets in your page... just paste the <script>blah blah</script> tag BETWEEN the head tags.
2.4 Take a deep breath.
2.5 Understanding the available "methods" contained in the JavaScript Controls.
There are a number of "methods" of "functions" you can call in your HTML pages. One being a call to embed a player directly into the page, this method is required since it "initializes" both the player and the JavaScript Controls. The remainder of the the functions take advantage of standard HTML hyperlink tags to control the player.
2.6 Establishing a player.
In order to use the JavaScript Controls, we must first establish / render a Wimpy MP3 Player on our page.
IMPORTANT NOTE: Only one player can be rendered and controlled on a page. If you need to have more than one player on a page, you may want to consider using Wimpy Rave. Wimpy Rave offeres the ability to render more than on player on a page.
Rendering the player relies on two portions of HTML code:
1. A <div> "target"
2. A JavaScript call
To establish a player in your HTML page the <div> target and the JavaScript call must exist within your page anywhere between the opening <body> and closing </body. tags in your HTML page.
The <div> target
The <div> target is used as a place holder. The JavaScript call replaces the contents of the <div> tag with the player. In the example below, the text "You need to upgrade your Flash Player" will be replaced with the player once the "makeWimpyPlayer" function is called. You may edit text / HTML code within the <div> tag with any other text or HTML code.
The <div> target must be located above the JavaScript call so that JavaScript can replace the HTML code inside the <div> tag (i.e. the <div> tag must exist before the call is made). You can place the <div> anywhere on the page. The player will be rendered where ever the <div> tag is located.
The <div> tag must have the "id" attribute set to "wimpyTarget" (case sensative) as follows:
<div id="wimpyTarget">You need to upgrade your Flash Player</div>
The JavaScript call
The JavaScript call is what is used to actually render the player on the page. This function will write all the HTML code necessary to display the player. The player will not render on the page unless the "makeWimpyPlayer" function is called, and the <div> tag exists somewhere on the page.
The following will render the player on the page with a default MP3 file. The player will be rendered where ever the target <div> tag exists.
<script>
makeWimpyPlayer("http://www.yoursite.com/path/to/song.mp3");
</script>
IMPORTANT NOTE: the "makeWimpyPlayer" call must be located below the <div> tag.
Example:
Good:
Notice that the <div> is above the <script>
<div id="wimpyTarget">You need to upgrade your Flash Player</div>
<script>
makeWimpyPlayer("http://www.yoursite.com/path/to/song.mp3");
</script>
Bad:
Notice that the <div> is below the <script>
<script>
makeWimpyPlayer("http://www.yoursite.com/path/to/song.mp3");
</script>
<div id="wimpyTarget">You need to upgrade your Flash Player</div>
Here are some additional examples / options available for issuing the call to render the player:
The following will establish the player with a default MP3 file.
<script>
makeWimpyPlayer("http://www.yoursite.com/path/to/song.mp3");
</script>
The following will establish the player with a default XML playlist.
<script>
makeWimpyPlayer("http://www.yoursite.com/path/to/playlist.xml");
</script>
The following will establish an "empty" player. If you just want to load the player without a start-up track or playlist, you'll have to "trick" Wimpy by referencing an XML file that doesn't exist, or references a playlist that doesn't have any <item>'s in it.
<script>
makeWimpyPlayer("blank.xml");
</script>
Custom Settings
The "makeWimpyPlayer" function you see above will cause the player to load using the default settings that are defined within the wimpy.js JavaScript file.
If you open the wimpy.js JavaScirpt file again you'll see a number of variables toward the top as:
var wimpyReg = "";
var wimpySwfBasename = "http://www.yoursite.com/path/to/wimpy.swf";
var defaultWimpyConfigs = new Object();
defaultWimpyConfigs.wimpyReg = wimpyReg;
defaultWimpyConfigs.wimpySwf = wimpySwfBasename;
defaultWimpyConfigs.wimpyApp = "playlist.xml";
defaultWimpyConfigs.wimpySkin = "http://www.yoursite.com/path/to/skin_bop.xml";
defaultWimpyConfigs.startPlayingOnload = "yes";
... etc...
For more information on all the available options, see the "Options Reference" page.
You can create a unique set of options when establishing the player to over-ride the default settings. To use unique values, create a new "object" and populate it with the settings you want to use. Then set the argument for "makeWimpyPlayer" to the object name.
<script>
var MySettings = new Object();
MySettings.wimpySkin = "skin_bop.xml";
MySettings.startPlayingOnload = "yes";
MySettings.startupLogo = "http://www.yoursite.com/path/to/image.jpg";
makeWimpyPlayer(MySettings);
</script>
2.7 Controlling the player.
The player is controlled by taking advantage of standard <a href> hyperlink tags. e.g. a "standard link" HTML code. With a standard HTML hyper link, we usually just reference a URL in the "href" attribute of a hyperlink tag.
Example of a standard HTML hyperlink tag:
<a href="URL"> Click Here </a>
The <a> tag contains one attribute named href (which stands for "Hyperlink Reference"). The <a> tag in our standard HTML example above is wrapped around the words "Click Here" -- so that when the words "Click Here" are clicked, the browser knows to go to a new page... Or, the browser "hyperlinks" to a new page.
With JavaScript we can take advantage of the simplicity of the <a> hyperlink tag by adding an additional attribute to the <a> hyperlink tag. The additional reference is an "onClick" attribute.
Example:
<a href="JavaScript:;" onClick="do something" > Click Here </a>
In order to tell the browser that we are using JavaScript instead of a traditional hyperlink reference, we replace the usual URL with the word "JavaScript" followed by a colon and semi-colon. Doing so indicates to the browser that we want to over-ride the traditional hyperlink action with a JavaScript function.
The additional attribute named "onClick" tells the browser what kind of user interactivity we want the browser to react to. There are a variety of interactive options we can set this attribute to, but onClick is the most widely used option -- supported by all browsers, so we'll just stick with this option.
So, now that we have told the browser to deal with this hyperlink when the link is clicked on -- or "onClick" -- we need to inform the browser which JavaScript function to use when the link is clicked.
In the same respect that the traditional href attribute "points" the browser to a new URL, with the onClick attribute, we are "pointing" the browser to a JavaScript function. The JavaScript function is actually contained in the wimpy.js file, which we referenced in the <head> tag... here we are just "calling" the function with the specifics about how we want to control the player.
2.8 Loading a file into an existing embedded player.
The function called wimpy_addTrack will load an MP3 file into the player.
The "wimpy_addTrack" function accepts 6 arguments.
- Start On Load
- The File's URL
- Title
- Artist
- Link URL
- Cover Art Image URL
Each of these "arguments" must be included within the function call as:
Example:
<a href="JavaScript:;" onClick="wimpy_addTrack(true, 'example4.mp3', 'My Artist', 'My Title', 'http://www.gieson.com', 'coverart.jpg');">
Click to play: Example 1
</a>
Broken down for ease of reading / explanation:
<a href="JavaScript:;"
onClick="wimpy_addTrack(
true, <-- Start playing on load
'example4.mp3', <-- URL to track.mp3
'My Artist', <-- Artist's Name
'My Title', <-- Track Title
'http://www.goto.com', <-- URL link on graphic
'coverart.jpg' <-- URL to graphic.jpg
);">
Load and Play: track 1
</a>
2.9 How functions work.
The way that the function puts this information into the player is through the references we use inside the parenthesis. As you may have noticed, all function calls contain a set of parenthesis after the name of the function (). These parenthesis allow us to send dynamic information into the player so that we can re-use the function with different information.
Think of a function as though it were a coffee grinder. you put beans into the top of the coffee grinder, the gears inside the grinder grind up the coffee , and the end result is usable coffee. A function is very similar. stuff gets "put into" the function, the function processes the information, then outputs usable code, or performs a specific task.
The stuff between the parentheses is like the area that accepts the raw coffee beans and the result is the usable coffee.
If you were to open the wimpy.js file in a text editor and find the reference to the wimpy_addTrack function, you will notice that there are words inside the parentheses that refer to specific "kinds" of information -- these words are "variables". When we use the function, we put "real" information in the same place that the "holder" reference words are located.
Each different kind of information that we want to put into the function is separated by a comma. Each piece of information we send into the function must be wrapped with quotes. By wrapping the stuff with quotes we are basically sending in "raw" data (or raw coffee beans).
It is important to maintain the proper order of the stuff that gets sent in. In other words, if a function accepts 3 items.
my_function(x, y, z)
Then we must include three items when we call the function -- and the reference to each must be in the same order.
For example, lets say we have a function named "make_a_sentance" that accepts three kinds of information:
1. A persons name
2. A day
3. A location
The function could look something like:
function make_a_sentance(theName,theLocation, theDay){
document.write(theName + " went to " + theLocation + " on " + ".");
}
When we call the function we would use something like:
make_a_sentance("Bob" , "the store", "3/14/2006")
This function would output the following:
Bob went to the store on 3/14/2006.
If, when calling the function, we put the information in the wrong "slot" the sentence would not print out properly. So we must ensure that we put the proper kind of information into the proper "slot" so that the function can put the stuff in the right spot. If you don't have anything for a specific "slot" then you would use empty quotes, but you still have to put "something" into the "slot" -- even if it's nothing.
Example:
make_a_sentance("Bob" , "", "3/14/2006")
This sentence would print out as:
Bob went to on 3/14/2006.
But if we simply omitted or didn't reference the second "slot" at all the function would output:
Bob went to 3/14/2006 on .
Because the function is thinking that the seconds "slot" should be a reference to a location, not a date.
So in the same respect, when using the JavaScript controls, you need to reference the proper kind of data in the proper slot. If you do not want to include anything for that particular kind of data, say, you didn't want to include an image or artist name, then you would simply use empty quotes.
Example:
<a href="JavaScript:;" onClick="wimpy_loadAndPlay('example4.mp3', '', 'My Title', '', '');">
Click to play: Example 1
</a>
Broken down for ease of reading / explanation:
<a href="JavaScript:;"
onClick="wimpy_loadAndPlay(
'example4.mp3', <-- URL to track.mp3
'', <-- Artist's Name
'My Title', <-- Track Title
'', <-- URL link on graphic
'' <-- URL to graphic.jpg
);">
Load and Play: track 1
</a>
There are plenty of tutorials on the Internet that you can refer to for more information on JavaScript.
3.1 Wrap up
This should help get you started using the JavaScript kit. Be sure to refer to the "Options reference" and "Function Reference" for explainations on each function.
Also, each of the example HTML pages contains commented source code that should be helpful for a more "hands on" approach.
|
