Links & Downloads

The Wimpy playlist control includes two special icons for each playlist item -- the download icon and the link icon.

These icons can be displayed globally, meaning that the icons will appear all the time for all playlist items. Or the can be displayed indiviually, meaning that the icons will appear on an item-by-item basis.

NOTE
You can use different icons. See the "Player Options -> glyphLink, glyphDownload" for more info.

Globally

To display the icons globally, set the linkEnable and downloadEnable Player Options to 1 (true).

Example via HTML

<div data-wimpyplayer data-downloadEnable data-linkEnable></div>

NOTE: When establishing boolean options via HTML, they just have to exists. Their mere existance indicates that you want to use them (e.g. set them to true).

Or with Javascript

var myPlayer = new wimpyPlayer({downloadEnable: 1, linkEnable:1});

You can also set these options for all players using the Global Options.

Individually

To display the icons individually, use the "link" and "downloadable" fields for individual playlist items.

Example

{
	file : "Track.mp3",
	downloadable : 1,
	link : "http://www.jbeeb.com"
}

See the Track Dataset for more info defining playlist items.

Individual setting trump global settings. When setting these options on individual playlist items, the global setting will be over-ridden.

Reference Chart

Here' we'll show you some code and what you can expect to see based on a given setup.

Case 1

Here we're setting the global options on the player.

var myPlayer = new wimpyPlayer({
					downloadEnable 	: 1,
					linkEnable 		: 1,
					media 			: "Track_1.mp3|Track_2.mp3|Track_3.mp3"
});

Resulting in the playlist rendering similar to:

Case 2

Here we're setting individual options on the player.

var myPlayer = new wimpyPlayer({
					media : [
							// Only has a link
							{
								file : "Track_1.mp3",
								link : "http://www.jbeeb.com"
							},
							// Only has downloadable
							{
								file : "Track_2.mp3",
								downloadable : 1
							},
							// Has both
							{
								file : "Track_3.mp3",
								downloadable : 1,
								link : "http://www.wimpyplayer.com"
							}
						]
});

Resulting in the playlist rendering similar to:

Case 3

Here we're setting both the global options and individual options on the player.

var myPlayer = new wimpyPlayer({
					downloadEnable 	: 1,
					linkEnable 		: 1,
					media : [
							// Has both because both global settings are "on"
							{
								file : "Track_1.mp3"
							},
							// Force both off
							{
								file : "Track_2.mp3",
								downloadable : 0,
								link : "http://jbeeb.com"
							},
							// Force link off, download uses global setting
							{
								file : "Track_3.mp3",
								link : 0
							}
						]
});

Resulting in the playlist rendering similar to:

Logic

Wimpy has built-in logic to handle each type of action. For example, if a playlist item contains a "link" field, and the user clicks on the "link" icon, a new window will open, directed to the URL set. The link action is a simple window.open command issued via Javascript.

Likewise, when the download icon is clicked, Wimpy will prompt the browser to save the media file. The download action is a little bit more complex, as Wimpy attempts to invoke an HTML 5 "download" attribute.

While the download action should work "as one would expect" for most modern browsers, it's a little clunky for older browsers as Wimpy simply pushes the media file out to a new window.

The traditional method for handling downloads requires a bit of server-side scripting in order to get the server to issue the proper "headers" that invoke a "save as" dialog in the browser. But since offering this kind of functionality involves knowing each server's capabilities, plus hard-coding a URL to the script handler, it is not feasable within Wimpy due to do this without driving me insane and creating a massive cludge.

Overriding Wimpy's Logic

You can cause Wimpy to use your own handler for each icon via the "setLinkHandler" and "setDownloadHandler" methods. When these methods are hooked into a player, Wimpy redirects the calls away from Wimpy's built-in logic and sends the request to your Javascript function.

Notification

In addition to the "handlers" mentioned in the "Overriding Wimpy's Logic" section above, you can leverage the "link" and "download" Event Listeners. These event Listeners are always triggered (whether a "handler" is established or not). This allows you to recieve notification when a user clicks one of the icons regardless of whether you're handling the logic or Wimpy is.

Event Listeners compliment "handlers", both handlers and listeners are completely seperate -- each serve a unique purpose.

Way Too Complicated?

Perhaps. But there's a reason. If you don't set things up globally, and simply incorporate "what you want" into each playlist item, it's pretty straight forward.

But some folks just want download always on, regardless. Hence the global option.

Some folks are using custom handlers, with a back-end system, and rather than writing complicated URLs for the links, they can simply flag a link (e.g. set link to "1"), then set up a custom handler, then let their onw custom back-end handle the rest.

With great complication comes great flexability.

A little more on the "link"

Wimpy "flys blind". Meaning that it doesn't attempt to validate links and downloads, it just sends whatever is thrown at it into the wild. So be carefull out there! Also, if you're using the getid3 option, Wimpy automatically checks MP3 files for embedded links.

Window

You can specify a target window that links will be directed to using the linkWindow and downloadWindow Player Options. The value for each of these options set's the "window name" as per the Javascript core function window.open. The default value is "_blank".

Icons

The link and download icons (as well as the file and playlist icons) con can be changed by editing "glyph" Player Options.

Links & Downloads

Globally

Individually

Reference Chart

Logic

Overriding Wimpy's Logic

Notification

Way Too Complicated?

A little more on the "link"

Window

Icons

See Also