Wimpy JavaScript Controls
By Mike Gieson
Available at www.wimpyplayer.com
©2002-2007 plaino
Contents:
- Overview
- Reading a Returned Object
- Putting rave.js into the <head> tag
- Verifying URLs
- Clear Browser's Cache
- Weirdo Characters
- Single Quotes, Double Quotes
- Choosing an HTML editor
- About Comments // <!--
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.
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:
<!-- THIS LINE GOES IN THE <HEAD> OF YOUR HTML PAGE -->
<script language="javascript" src="http://www.yoursite.com/wimpy/rave.js"></script>
<!-- START WIMPY PLAYER CODE -->
<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>
<!-- END WIMPY PLAYER CODE -->
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.
Function Reference
makeWimpyPlayer()
See Example 1
See Example 2
See Example 3
|
Renders a player on your page based on the options established within the rave.js file. The rave.js file contains more information about the available options in the javaScript comments.
To render a player:
<script language="JavaScript" >
makeWimpyPlayer();
</script>
To render a player with one file:
<script language="JavaScript" >
makeWimpyPlayer("file1.mp3");
</script>
To render a player with a few files, separate each file with a "pipe" character, see Example 2.
To render a player with a few files, with each file having additional information:, see Example 3.
|
wimpy_play() |
Starts the player or plays the track that is currently selected in the playlist.
<a href="javascript:;"
onClick="wimpy_play();">
Play
</a>
|
wimpy_stop() |
Stops the currently loaded track
<a href="javascript:;"
onClick="wimpy_stop();">
Stop
</a>
|
wimpy_pause() |
Pauses the currently loaded
<a href="javascript:;"
onClick="wimpy_pause();">
Pause
</a>
|
wimpy_gotoTrack() |
Goes to a specific track listed in the playlist. The only way to determine which track to "go to" is by referencing a number. Example wimpy_gotoTrack(3) would play the third item in the current playlist.
<a href="javascript:;"
onClick="wimpy_gotoTrack(2);"> <-- Specify the track number inside the ().
Stop
</a>
|
wimpy_next() |
Plays the next track in the playlist
<a href="javascript:;"
onClick="wimpy_next();">
Next
</a>
|
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_clearPlaylist() |
Clears the playlist
<a href="javascript:;"
onClick="wimpy_clearPlaylist();">
Clear Playlist
</a>
|
wimpy_appendPlaylist()
Returns: nothing
See Example 5 |
Adds tracks to the player's playlist. Loads XML data into the player.
To add an MP3 file to the playlist
<script language='javascript'>
var addFiles = "";
addFiles += "<playlist>";
addFiles += " <item>";
addFiles += " <filename>example1.flv</filename>";
addFiles += " <artist>killeen and gieson</artist>";
addFiles += " <title>Example 1</title>";
addFiles += " <link>http://www.gieson.com</link>";
addFiles += " <image>example1.jpg</image>";
addFiles += " </item>";
addFiles += " <item>";
addFiles += " <filename>example2.flv</filename>";
addFiles += " <artist>Killeen and Gieson</artist>";
addFiles += " <title>Example 2</title>";
addFiles += " <link>http://www.plaino.com</link>";
addFiles += " <image>example2.jpg</image>";
addFiles += " </item>";
addFiles += "</playlist>";
</script>
<a href="javascript:;"
onClick="wimpy_appendPlaylist(addFiles)">
Add Multiple Tracks
</a>
|
wimpy_getTrackInfo()
Returns: Object
See Example 6 |
Returns all the information for a track as an Object. If no argument is passed in, the info for the track that is currently playing will be returned.
In your HTML:
<a href="javascript:;"
onClick="wimpy_getTrackInfo();">
Get info about current track.
</a>
Wimpy returns:
anObject.artist = "The tracks artist";
anObject.title = "The track's title";
anObject.whatever = "Whatever else is available"
To retrieve information on a specific item in the playlist , enter the a number as an argument. The number that you enter should correspond to the playlist item. For example, entering "3" as the argument will get the info for the third item in the playlist.
wimpy_getTrackInfo(3)
In the example above, all the information for the third item in the playlist will be returned. NOTE: If the playlist is being sorted, the item may be different than the order in which the source XML playlist.
If the player has not yet started to play a track, the info for the first item in the playlist is returned.
If the player does not have anything in the playlist Wimpy will return false (boolean).
See also:
- Reading a Returned Object
|
wimpy_loadExternalPlaylist()
Returns: nothing |
Loads a playlist file into the player.
Example:
<a href="javascript:;"
onClick="wimpy_loadExternalPlaylist("http://path/to/playlist.xml");">
Load a playlist.
</a>
|
handleWimpyInit()
Returns: Boolean
See Example 6
|
This function will get pinged when Wimpy is ready and able to accept JavaScript calls / interaction. Wimpy will call this function as needed to inform you of the event.
In order for this function to be enabled, the variable "enableWimpyEvents" to be set to true. Open rave.js in a text editor and scroll down to the "Advanced Usage" area.
Example:
var enableWimpyEvents = true;
See also wimpy_amReady_ask()
|
handlTrackStarted()
Returns: Object
See Example 6 |
This function gets pinged every time a track starts to play. Wimpy will call this function as needed to inform you of the event.
In order for this function to be enabled, the variable "enableWimpyEvents" to be set to true. Open rave.js in a text editor and scroll down to the "Advanced Usage" area.
Example:
var enableWimpyEvents = true;
Wimpy will return an Object that contains all of the track information.
See also:
- Reading a Returned Object
|
handleTrackDone()
Returns: Object
See Example 6 |
// This function gets pinged each time a track finishes playing. Wimpy will call this function as needed to inform you of the event.
In order for this function to be enabled, the variable "enableWimpyEvents" to be set to true. Open rave.js in a text editor and scroll down to the "Advanced Usage" area.
Example:
var enableWimpyEvents = true;
Wimpy will return an Object that contains all of the track information.
See also:
- Reading a Returned Object
|
wimpy_amReady_ask()
Returns: Boolean
See Example 6
|
Checks to see if Wimpy has been initialized and is ready to accept JavaScript calls / interaction.
Example:
<a href="javascript:;"
onClick="wimpy_loadExternalPlaylist("http://path/to/playlist.xml");">
Load a playlist.
</a>
|
wimpy_setVolume()
Returns: nothing
See Example 6 |
Set the player's volume
Example:
<a href="javascript:;"
onClick="wimpy_setVolume(50);">
Set Volume to 50 percent.
</a>
|
wimpy_setLoopTrackState()
Returns: nothing
See Example 6
|
Sets the "loop track" button to the specified state.
State options are:
on
off
Example:
<a href="javascript:;"
onClick="wimpy_setLoopTrackState('on')">
on
</a>
|
wimpy_setRandomState()
Returns: nothing
See Example 6 |
Sets the "random playback " button to the specified state.
State options are:
on
off
Example:
<a href="javascript:;"
onClick="wimpy_setRandomState('on')">
on
</a>
|
wimpy_setRepeatState()
Returns: nothing
See Example 6 |
Sets the "repeat track " button to the specified state.
State options are:
on
off
Example:
<a href="javascript:;"
onClick="wimpy_setRepeatState('on')">
on
</a>
|
wimpy_setMuteState()
Returns: nothing
See Example 6 |
Sets the "loop track" button to the specified state.
State options are:
on
off
Example:
<a href="javascript:;"
onClick="wimpy_setLoopTrackState('on')">
on
</a>
|
wimpy_updateInfoDisplay()
Returns: nothing
See Example 6
|
Puts new information into the scroll info display area.
Accepts two arguments, the first refers to the Artist, the second the Title of the track.
This option is useful when running Icecast streams and allows you update the scrolling display dynamically.
Example:
<a href="javascript:;"
onClick='wimpy_updateInfoDisplay("My New Artist", "My New Title")'>
Update Artist and Title
</a>
|
wimpy_getPlayheadPercent()
Returns: Number
|
Gets the current playhead percentage.
|
wimpy_setPlayheadPercent()
Returns: nothing |
Sets the playhead to the specified percentage.
NOTE: This option was not designed to for use milliseconds after launching a file. In other words, some folks might be trying to use this function to "pick up" playing where a user left off last time they visited a page.
Although this kind of functionality can be achieved, it will require additional scripting to accomplish because the file must have enough data loaded before Wimpy can advance the playhead.
For example, lets say you launch a track, then immediately call this function and set the argument to 95 (meaning "set the playhead so that the track starts playing at 95%"... Since it is highly likely that the file has not been fully loaded milliseconds after launching it, Wimpy will not advance the playhead to 95%. Wimpy can only advance the playhead to a percentage that has been loaded.
This means that you will probably need to use the wimpy_getLoadPercent function before calling this "set" function in order to determine how much of the file has been loaded, and / or if it is safe to advance the playhead.
Here's a potential method for achieving this kind of functionality:
// Create a player:
makeWimpyPlayer();
// In the rave.js, add a function call inside wimpy_amReady() as:
function wimpy_amReady(retval){
loadAndListen(
"myFile.flv");
}
// Create a new function in rave.js as:
function loadAndListen(myFile){
// Add a track to the player and launch it (so it starts to load)
wimpy_appendPlaylist(myFile, true);
// Pause the player immediately
wimpy_pause();
// Set an interval call to wait until enough data has been
// loaded before setting the playhead position:
ourInterval = setInterval('checkLoadStatus()', 1000);
}
// Establish varibles in the global scope:
var ourInterval;
var gotoPercent = 30;
// Create function to intermitenly check the load percent:
function checkLoadStatus(){
var loaded = wimpy_getLoadPercent();
if(loaded > gotoPercent){
wimpy_setPlayheadPercent(gotoPercent);
clearInterval(ourInterval);
}
}
|
wimpy_getPlayheadSeconds()
Returns: Number
|
Gets the playhead position in seconds. |
wimpy_setPlayheadSeconds()
Returns: nothing
|
Sets the playhead to the specified second.
See "NOTE" in wimpy_setPlayheadPercent();
. |
wimpy_getLoadPercent()
Returns: Number
|
Retrieves the loading status according to percent loaded (0-100). |
wimpy_getLoadState()
Returns: Object
See Example 6
|
Retrieves all information associated with file loading.
The object will contain the following variables:
percent |
A "float" number from 0.0 to 1.0.
Example:
0.34
(the file is 34% loaded)
|
loaded |
Number of bytes loaded
Example:
5035075 (bytes)
|
total |
Total file size in bytes
Example:
7481037 (bytes)
|
status |
The state identified by a number: -1, 0, 1
Example
-1 = loading is complete / no more loading is needed.
0 = an error occurred while attempting to load
1 = loading is in progress \
|
See also:
- Reading a Returned Object
|
wimpy_getPlayerState()
Returns: Object
See Example 6 |
Retrieves all information associated with clip playback.
The object will contain the following variables:
buffering |
Boolean value indicating whether or not the track is buffering
The spinning "wait" icon is a graphic representation of this value.
|
bufferState |
A numerical representation of the buffer status:
1 = Buffer is full
0 = Buffer is empty
-1 = Buffer is flushing
|
buffer |
Number of seconds worth of media in the buffer. See also "bufferSeconds." |
printTime |
A nicely formatted time signature. representing the current time. |
remaining_nice |
A nicely formatted time signature. representing the remaining time. |
remaining |
Number of seconds remaining |
current_nice |
A nicely formatted time signature. representing the current time. |
current |
Number of seconds that have been played. (e.g. The position of the playhead in seconds) |
duration_nice |
A nicely formatted time signature. representing the total time. |
duration |
The total time of the track in seconds. |
percent |
The current percentage of playback. This is graphically represented by the scrubber handle. |
status |
A numerical representation of the players overall status:
1 = playing
0 = paused or stopped
|
init |
A numerical representation of the tracks initialization status:
1 = track is queued and ready to play or playing.
0 = no track is queued nothing can play.
|
See also:
- Reading a Returned Object
|
wimpy_getTotalPlaylistItems()
Returns: Number
See Example 6
|
Returns the total number of tracks loaded into the playlist. |
wimpy_returnPlaylistItem() |
Returns all the information for a specific track loaded into the Wimpy playlist.
Wimpy returns the information as an array, where the first index of the array is a string identifying the name of the function (e.g. "wimpy_returnPlaylistItem " which allows you to distinguish between different function calls returned to the function that is defined in js_wimpy_returnOnComplete.
This function requires js_wimpy_returnOnComplete to be established within rave.js. See the comments within rave.js for how to use this feature.
<a href="javascript:;"
onClick="wimpy_returnPlaylistItem(2);"> <-- Specify the track number inside the ().
Get info about a specific track
</a>
See readme_wimpy_mp3_js_example6.html for example of how to use this feature.
See also:
- Reading a Returned Object
|
wimpy_getPlaylistXML()
Returns: XML
See Example 6
|
Returns the current playlist as a string in the form of XML data.
|
wimpy_getPlaylist()
Returns: Array
See Example 6
|
Returns an array where each item in the array is an object. that refers to a playlist item.
Example:
returned_array[0] = playlist_item_object
returned_array[1] = playlist_item_object
returned_array[2] = playlist_item_object
Each "playlist_item_object" can be interpreted using the method described in "Reading a Returned Object."
This method is provided so that you don't have to convert the XML into a usable array or object. It should be noted that in each playlist_item_object, the <item> XML is also included in the XMLdata variable.
See also:
- Reading a Returned Object
|
wimpy_callPlugin() |
Allows you to call a custom plugin.
wimpy_callPlugin(pluginID, argument)
Where pluginID refers to the ID name given to the plugin. The ID can be modified using Skin Machine.
Only one argument is allowed to be sent it. If your plugin requires more than one argument to be sent in, the argument must be formatted according to the method described by the plugin author. Usually this means "packaging" the multiple arguments with some kind of delimiter, such as a pip " | " or carat " ^ ".
Example:
var myPluginID = "CoolPlugin";
var arg1 = "http://path/to/something";
var arg2 = "true";
var combinedArgument = arg1 + "|" + arg2;
wimpy_callPlugin(myPluginID, combinedArgument);
|
Reading a Returned Object
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");
}
Putting rave.js into the <head> tag
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.
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 <!-- and end with -->
Greater-than-exclaimation-dash-dash followed by dash-dash-less-than.
When a browser sees <!-- it skips reading and interpreting HTML code until it reaches -->
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:
<!-- The following will render a text-based hyperlink to Google-->
<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";
© 2007 Plaino. www.wimpyplayer.com
|