Wimpy JavaScript Controls - About

The following "JavaScript Controls" section is intended for advanced users who wish to take advantage of additional functionality built into Rave.

NOTE: Using the examples locally: We recommend running examples on your web server. Running the examples on your local PC may cause your browser to issue a security warning, which is a built in feature of the Adobe Flash plugin that flags any Adobe Flash file that is run locally. There is no risk in running Rave locally, you can configure your Adobe Flash plugin to "allow" specific Adobe Flash files to run by clicking the "Settings" button on the pop up dialog.

Overview

Javascript controls allow you to control nearly every aspect of Wimpy RAVE and/or interact with Wimpy RAVE to collect / insert data to / from the player, or load files into Wimpy RAVE dynamically..

Javascript controls are handled through rave.js, which is also used to render Wimpy RAVE in your HTML page. Hence, JavaScript controls do not need to be installed or configured. The Javascript controls work "out of the box."

The JavaScript controls are intended for advanced HTML authors who are not afraid to tinker with HTML and modify JavaScript variables. If the previous sentence didn't make sense to you, you may want to make a pot of coffee. There is a "newbie" section included in this documentation, which attempts to help explain some of the techno mumbo-jumbo it's the best I can offer without actually showing up at your office and holding your hand.

I recommend that you take a look at the source HTML code in the example HTML pages to see how the code is implemented in a **real** HTML page. The examples **may** work on your local PC, but you may experience problems when viewing locally -- depending on the security settings you have established through the Flash plugin installed in your browser. The best way to test things out is to upload all the files contained in this package to your web server.

By default, the Customizer will output HTML code that is "ready to go." This means that you don't have to do anything special to the Wimpy HTML code or player in order to start using the JavaScript controls described below.

We've created several example pages to show how the JavaScript Controls actually work. The example pages all use "relative" paths to files associated with Wimpy. This means that all of the example pages, Wimpy files and media files need to all be in the same folder.

The example pages are:
- readme_rave_js_example1.html
- readme_rave_js_example2.html
- readme_rave_js_example3.html
- readme_rave_js_example4.html
- readme_rave_js_example5.html
Advanced examples:
- readme_rave_js_example6.html
- readme_rave_js_example7.html
    The following pages are for use with example 7:
     - readme_rave_js_example7-otherpage.html
     - readme_rave_js_example7-popup.html

The "Advanced" examples (example 6 and 7) rely on an external JavaScript file (readme.js) render the call-backs from Wimpy. Within the example 6 and 7 HTML code, we've set "enableWimpyEvents" to TRUE, which allows callback events to work.

We've tried to keep the HTML code within the examples clean and commented, so if you are experienced with HTML and JavaScript reading the source HTML / source JavaScript will be helpful.

Choosing an HTML editor

We recommend using a "plain old" text editor The simpler the text editor the better.

For Windows users Note Pad (notepad.exe) is a good choice. Note Pad is usually located here:
C:\WINDOWS\system32\notepad.exe

If your on a Mac, check out Smultron.

The reason we recommend using a regular text editor, as opposed to a big fancy HTML editor such as Dreamweaver, FrontPage or similar is because often times, these programs will re-write the HTML code, in the process of re-writing the HTML code, sometimes they will include un-necessary stuff, or eliminate certain stuff that Wimpy needs to operate properly. This can create serious headaches.

Do NOT use Microsoft Word (or similar) to edit the HTML code.

About Comments // <!--

Comments are lines within code that help programmers understand what certain parts of the code does. Comments are not processed by the browser, but are simply ignored -- so it's a nice way to include "human readable" explanations for how the script works within the code.

Programmers will often use the following terminology:
"Comment out that line."
and
"Put some comments in that code."

Interpreted for non-programmers:
"We don't want to delete that line (because we may need it later) so just put two slashes in front of it so that that line of code won't get processed, which is the next best thing to deleting the line."
and
"It would be nice to have a little explanation of what each part of the code does so that I can better understand it, and perhaps make some modifications to it to suit my needs better (or correct your bugs :)"

HTML comments

In HTML, comments are "chunks" of code that start with 

Greater-than-exclaimation-dash-dash followed by dash-dash-less-than.

When a browser sees 

This enables HTML authors to include "human readable" messages within the context of the HTML code so that anyone who reads the source HTML code can get a better understanding of what certain portions of the code are used for.

Example:


<a href="http:// www.google.com">Go to Google</a>

JavaScript Comments

In JavaScript, comments are lines that begin with two slashes //.

Example:

// myVariable will be used to identify my pet fish's name.
myVariable = "bob";

Notice that these are forward slashes, not backward slashes. If you use backward slashes, you will break the code. Lines that begin with two forward slashes are NOT processed, they are ignored when the JavaScript engine ("Interpreter") processes the script. You can also use a slash-star pair to comment out a large block..

Example:

/*
myVariable will
be used to identify
my pet fish's name.
*/
myVariable = "bob";

Usage

The first thing to do is use the Customizer Tool to generate the necessary HTML code. Using the Customizer Tool, you can choose to output an HTML snippet or a full page. . We recommend outputting an HTML snippet, because it is more than likely that you will be controlling Wimpy from other elements on your page. An HTML snippet generated by the Customizer Tool looks something similar to the following:


<script language="javascript" src="http://www.yoursite.com/wimpy/rave.js"></script>


<table width="100%" height="100%" border="0" cellpadding="0" cellspacing="0" bgcolor="#000000">
<tr>
<td align="center" valign="middle">
<div id="flashcontent"><a href="http://www.adobe.com/products/flashplayer/">Flash Player upgrade required</a></div>
<script language="javascript">
// <![CDATA[
var wimpyConfigs = new Object();
wimpyConfigs.wimpySwf="http://www.yoursite.com/wimpy/rave.swf";
wimpyConfigs.wimpyApp="http://www.yoursite.com/wimpy/rave.php";
wimpyConfigs.wimpyWidth="520";
wimpyConfigs.wimpyHeight="300";
wimpyConfigs.wimpySkin="http://www.yoursite.com/wimpy/skins/skin_itunes.xml";
wimpyConfigs.autoAdvance="no";
wimpyConfigs.setAspectRatio="maintain";
makeWimpyPlayerFromConfigObject(wimpyConfigs);
// ]]>
</script>
</td>
</tr>
</table>


The HTML code contains four basic parts.

1. A reference to rave.js
2. An HTML table used as a container for Wimpy.
3. A <div> tag which is used as a target for rendering Wimpy in the page.
4. A <script> used to configure and render Wimpy.

When uploading Wimpy to your web site, be sure that the following files are located in the same folder:
     - rave.swf
     - rave.js
     - wimpy_downloadFile.html
     - wimpy_fullscreen.html
     - wimpy_popout.html

You can include Wimpy on any page throughout your site, however, in order to do so, you'll need to use the Customizer Tool to generate an HTML snippet. The HTML snippet can be included in any web page on your site.

When using the JavaScript controls, it is important to use full URLs to any file associated with Wimpy, including HTML, JavaScript, MP3, FLV, SWF and XML files. For more information on using full URLs see the "Relative and Absolute" page.

Returned Objects

A number of functions will return an Object, which is an easy way to send a number of mixed variables all packaged up within a single "thing." The file "readme.js" is used by the example pages. It contains a number of functions that are useful for rendering data to the page.

This is especially useful when all of the variables are not "pre determined" -- as is the case with a playlist <item>. As you know, a playlist <item> can contain any number of <tags>

For example, if we are using an XML playlist and one of our items is set up as follows:

<item>
   <filename>     example2.flv         </filename>
   <artist>       Killeen and Gieson   </artist>
   <title>        Example 2            </title>
   <link>         http://www.plaino.com</link>
   <image>        example2.jpg         </image>
   <someOtherTag> whatever             </someOtherTag>
</item>

... then the returned object will contain variables according to the same structure as:

returnedObject.filename    = "example2.flv"
returnedObject.artist       = "Killeen and Gieson"
returnedObject.title        = "Example 2"
returnedObject.link         = "http://www.plaino.com"
returnedObject.image        = "example2.jpg"
returnedObject.someOtherTag = "whatever"

Perhaps the easiest way to see how to get the data out of the variable is to check out the "displayObject" function that is found within "readme.js."

function displayObject(returnedObject){
   // Create a string variable so we can put the
   // information into a variable and print it out later:
   var retText = "";
   // "prop" is the name of the variable
   for(var prop in returnedObject){
     // Here we are "printing" the "prop" variable name,
     // the retrieving the "prop" from the object using
     // [brackets] to access the variable name within the object
     retText += "<b>" + prop + "</b> : " + returnedObject[prop] + "<br>";
   }
   // Here we "print" retVal to the screen using the "writeIt" function
   writeit(retText,"trackInfo");
}

Integrating rave.js

When including Wimpy on an existing page, we recommend putting the reference to rave.js into the <head> tag of your HTML page. Although it is not 100% necessary to do so, it is simply a good practice. Putting the reference to rave.js into the <head> ensures that the javascript will be ready and available before any of the content for the pages loads. Putting the reference to rave.js into the <head> tag has a few advantages:

- Page loads a little bit more cleanly.
- When putting more than one Wimpy Player on a page, you MUST put the reference to rave.js into the <head> tag, other wise, rave.js will get loaded more than once, which can cause Wimpy (or your page) to freak out.
- If the reference to rave.js is not "above" any of the <div> target, Wimpy will not render in the page. (i.e. Wimpy will not show up on your page).

To put the reference to rave.js into the <head> tag:

Open the HTML code output from the Customizer Tool in a text editor and copy the line that reads:

<script language='javascript' src='http://www.yoursite.com/mp3s/rave.js'></script>

Then open your existing page and paste the code anywhere between the opening <head> tag and the closing </head> tag as:

Example:

<html>

<head>

<script language='javascript' src='http://www.yoursite.com/mp3s/rave.js'></script>

<head>

<body>
yada yada
</body>

</html>

Verifying URLs

It is a good idea to test a URL before using it. Usually, I copy and paste the URL into a new browser window's address field to make sure that i'm "hitting" the right file. (Sometimes my typing can be terrible.)

Clear Browser's Cache

Clearing your browser's cache ensures that your browser loads the latest changes to any files that were edited. Click here to lean how to clear your browser's cache.

For development I highly recommend Mozilla's Firefox browser. The primary reason is because FireFox's "Clear Cache Now" button actually works. Internet Explorer does not always clear files from the cache, which causes many hours of double thinking where the code is wrong. With FireFox, you KNOW that the cache is cleared when you "Clear the cache." Plus there are a number of developer tools and extensions that make clearing the cache 9or disabling the cache a one click (or no-click) deal.

To clear the cache in FireFox, From the Main Menu > Tools > Options > Privacy Icon > Cache tab > "Clear Cache Now." You can also include the "clearing of the cache" by clicking the "settings" tab in the same screen and check "cache" from the list, This way you only have to From the Main menu > Tools > Clear Private Data. OR, ctrl+ shift+del.

In addition there is a nifty JavaScript error reporting tool, which can help you determine exactly where the JavaScript error is occurring. The JavaScript error console can be access From the Main Menu > Tools > JavaScript Console.

Nailing down the "Clear cache" and using the JavaScript Console will save you lots'o'time and headaches.

Weirdo Characters

It is best to try and only use alpha-numeric characters. Multi-byte (e.g. chinese characters) and non-alpha-numeric characters (e.g. ' ? & " etc.) may be problematic. You may want to apply the escape() function to any questionable arguments that may contain non-western / non-alpha-numeric characters.

Pay special attention to URL encode (escape) -- or don't use at all -- the following characters:
& ' ? space " # ! \

Single Quotes, Double Quotes

When referencing files, or including function calls within your HTML code, you can use 'single quotes' or "double quotes." There is no set rule, both will work.

The reason you would want to use one instead of the other is if the content contains one of the two.

Example:

Good:
" ' "

Bad:
" " : "

Example:

If you wanted to use a URL such as:
http://www.yoursite.com/bob's files/bob.jpg
.. where bob is plural

You would have to wrap the line with double quotes, because there is a single quote in the line. if we wrapped the URL with single quotes, then the browser will think that the ending quote is after bob.

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'

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:
waspPopup('bob's video.flv', 320, 240)
Good:
waspPopup("bob's video.flv", 320, 240)

It will invariably happen, and now you know why.