JavaScript Function Reference

The following page explains all of the function calls that are available for interacting with Wimpy via AJAX.

IMPORTANT NOTE: It is best to try and only use alpha-numeric characters. Double-byte and non-alpha-numeric characters must be URL encoded. You may want to apply the escape() function to any questionable arguments that may contain non-alpha-numeric characters.

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

makeWimpyPlayer()

Renders a player on your page where ever the target <div> exists. This is required to use any of the JavaScript Controls. In order to take advantage of the JavaScript Controls, an instance of the player must be established through javascript using makeWimpyPlayer. Only one player can be rendered and controlled on a page.

NOTE: The target <div> must have an id attribute set to "wimpyTarget".

Example

<div id="wimpyTarget">Wimpy gets rendered here</div>

Accepts one argument

makeWimpyPlayer(
[String or Object: Either a string referencing files, OR a configuration object]
);

Examples

To render a player with a default MP3 file:

To render a player with a few files, separate each file with a "pipe" character:

To render the player using custom options:

To render a blank player:

NOTE: 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. If you reference an XML file that doesn't exist (as in this example) you may recieve 404 errors in your server logs, so referencing "real" file that doesn't have any <items> will eliminate server log entries.

See the source code of the example HTML page for more implemendation examples.

wimpy_addTrack()

Load an MP3 file into the playlist.

Accepts 6 arguments:

wimpy_addTrack(
    [Boolean: Start playing on load],
    [String:    URL to track.mp3],
    [String:    Artist's Name],
    [String:    Track Title],
    [String:    URL link on graphic cover art],
    [String:    URL to cover art],
);

Example

<a href="javascript:;"
onClick="wimpy_addTrack(
    true,
    'example4.mp3',
    'My Artist',
    'My Title',
    'http://www.gieson.com',
    'coverart.jpg'
    );">
Load and Play: track 1
</a>

NOTE: We've placed each argument on a new line for ease of reading, you should not do so in your HTML page -- keep all arguments on the same line.

wimpy_addMultipleTracks()

Load multiple tracks into the player.

Accepts 2 arguments:

wimpy_addTrack(
[Boolean: Start playing on load],
[Array: An Array of playlist items where each is an object]
);

Example

NOTE: "filename", "artist", "title", "visual", and "link" are all hard-wired into Wimpy. These labels must be use "as is" and are case-sensative -- they do not need to appear within each object in any specific order.

// Create an Array to hold our track objects (i.e. a playlist array).
Alist = Array();

// Establish and empty object.
var temp = new Object();

// Populate the object with varibles refering to each kind of data.
temp.filename = "example1.mp3";
temp.artist = "Artist One";
temp.title    = "Track One";
temp.visual = "example1.jpg";
temp.link     = "http://www.wimpyplayer.com";

// Add the object to the end of the array
Alist[Alist.length] = temp;

// The model above is replicated for additional playlist items:
var temp = new Object();
temp.filename = "example2.mp3";
temp.artist = "Artist Two";
temp.title    = "Track Two";
temp.visual = "example2.jpg";
temp.link     = "http://www.wimpyplayer.com";
Alist[Alist.length] = temp;

var temp = new Object();
temp.filename = "example3.mp3";
temp.artist = "Artist Three";
temp.title    = "Track Three";
temp.visual = "example3.jpg";
temp.link     = "http://www.wimpyplayer.com";
Alist[Alist.length] = temp;

var temp = new Object();
temp.filename = "example4.mp3";
temp.artist = "Artist Four";
temp.title    = "Track Four";
temp.visual = "example4.jpg";
temp.link     = "http://www.wimpyplayer.com";
Alist[Alist.length] = temp;

wimpy_addMultipleTracks(true, Alist);

wimpy_clearPlaylist()

Clears the playlist

Example

<a href="javascript:;"
onClick="wimpy_clearPlaylist();">
Clear Playlist
</a>

wimpy_play()

Starts the player or plays the track that is currently selected in the playlist.

Example

wimpy_stop()

Stops the currently loaded track and rewind the playhead to the beginning.

Example

wimpy_pause()

Pauses the currently loaded

Example

<a href="javascript:;"
onClick="wimpy_pause();">
Pause
</a>

wimpy_gotoTrack()

Goes to a specific track listed in the playlist. To determine which track to "go to", start at the top of the playlist and count down. For example wimpy_gotoTrack(3) would play the third item in the current playlist.

Accepts 1 argument:

wimpy_gotoTrack(
[Number: a number referencing the track to go to]
);

Example

wimpy_next()

Plays the next track in the playlist

wimpy_prev()

Rewinds the play head to the beginning of the track, or goes to the previous item in the playlist depending on the current status of the player's play head.

<a href="javascript:;"
onClick="wimpy_prev();">
Previous
</a>

wimpy_getTrackInfo()

See example 5

Returns information about the track that is currently playing. You may also specify a specific track to retrieve information about by using the track number as an argument.

Returns an object containing named variables and their values. The default information returned is:

- Title
- Artist
- File Name
- Visual (cover art file)
- Comments (URL link)
- Loaded Percent (percentage of the file that has been loaded)
- Time Current Nice (human readable time format for current time)
- Time Current (current time in seconds -- including the float)
- Time Total (total number of seconds -- including the float)
- Entity (the kind of file it is. "m" = MP3, "x" = "XML playlist)
- Flashlist ID (the track number, for example, the thrid track down would be "3")

Your responsible for interpreting the returned object in your application -- wimpy.js includes a javascript function that processes and prints out an object, which you can use as a starting point for creating your own function that reads the object. Check out the source code inside example 5 and wasp.js (displayObject).

For all the nerds out there, here's an example of the structure of the returned object::

returnedObject.title       = "My Track";
returnedObject.artist      = "My Artist";
returnedObject.filename    = "song.mp3";
returnedObject.visual      = "coverart.jpg";
returnedObject.comments    = "http://www.gieson.com";
returnedObject.loadedPercent = "100";
returnedObject.timeCurrentNice = "3:16";
returnedObject.timeCurrent = "196.038";
returnedObject.timeTotal   = "212.23506";
returnedObject.entity      = "m";
returnedObject.flashlistID = "3";

Accepts 1 argument (optional):

wimpy_getTrackInfo(
[Number: This argument is optional, if left blank, the info on the current track will be returned]
);

Examples

This will return info on the current track:

<a href="javascript:;"
onClick="displayObject(wimpy_getTrackInfo());">

Get info about current track.

</a>

NOTE: In our example you'll notice that "wimpy_getTrackInfo" is an argument for "displayObject" because "displayObject" will be interpreting the returned object.

wimpy_getPlaylist()

See example 6

Returns the current playlist as a multi-dimensional array.

We decided to return a raw array rather than an object / variable (index-based vs. associative-based) in order to streamline the returned data (The playlist can hold thousands of tracks). This means that you'll have to put your thinking cap on to recognize which index of the array refers to which kind of data.

Your responsible for interpreting the returned array in your application -- wimpy.js includes a javascript function that processes and prints out an object, which you can use as a starting point for creating your own function that reads the object. Check out the source code inside example 6 and wasp.js (displayObject).

For all the nerds out there, here is an example of the structure of the returned array:

returnedArray[0] = array =>
                        [0] = "0"
                        [1] = "m"
                        [2] = "song1.mp3"
                        [3] = "Artist 1"
                        [4] = "Title 1"
                        [5] = "http://www.link.com"
                        [6] = "coverart1.jpg"

returnedArray[1] = array =>
                        [0] = "1"
                        [1] = "m"
                        [2] = "song2.mp3"
                        [3] = "Artist 2 "
                        [4] = "Title 2 "
                        [5] = "http://www.link.com"
                        [6] = "coverart2.jpg"

returnedArray[2] = array =>
                        [0] = "2"
                        [1] = "m"
                        [2] = "song3.mp3"
                        [3] = "Artist 3 "
                        [4] = "Title 3 "
                        [5] = "http://www.link.com"
                        [6] = "coverart1.jpg"

Example

<a href="javascript:;"
onClick="displayObject(wimpy_getPlaylist());">

Get info about a specific track

</a>

NOTE: In our example you'll notice that "wimpy_getPlaylist" is an argument for "displayObject" because "displayObject" will be interpreting the returned array.

wimpy_loadExternalPlaylist()

Loads and opens an external XML playlist

Accepts 1 argument:

wimpy_loadExternalPlaylist(
[String: URL to XML playlist]
);

Example

<a href="javascript:;"
onClick="wimpy_loadExternalPlaylist('playlist1.xml');">
Load and open playlist1.xml
</a>

wimpy_changeVisual()

Swaps out the existing cover art image with a new one, also changes the link on the cover art image.

If the second argument is set, the image will act as a button, when a user clicks on the image, they will be brought to the URL defined for the second argument.

Accepts 2 arguments:

wimpy_changeVisual(
[String: URL to a JPG image],
[String: URL to to use as the link on the image.]
);

Example

<a href="javascript:;"
onClick="wimpy_changeVisual('example1.jpg', 'http://www.gieson.com');">
Change the cover art image and set the link on the image to "http://www.gieson.com"
</a>

NOTE: To target a specific window, you'll have to set the ecomWindow option to reference "_self" or "_parent" or some other window.

wimpy_updateInfoDisplay()

Changes the text in the main info display area. NOTE: If the text is not longer that the available area, the text will not scroll, it will remain static.

Accepts 2 arguments:

wimpy_changeVisual(
[String: Text for the Title of the track],
[String: Text for the Artist]
);

Example

<a href="javascript:;"
onClick="wimpy_updateInfoDisplay('Hello', 'Mom');">
Update the Info Display Text;
</a>

wimpy_amReady_ask()

Checks to see if Wimpy is initialized and ready to accept calls.

Example

<a href="javascript:;"
onClick="alert(wimpy_amReady_ask());">
See if Wimpy is ready
</a>