Player Handle, ID & Name

If you plan on using the Javascript API, you'll need a way to access Wimpy Player Objects (WPO) in order to make API calls to them. There are a couple different approaches to get a "handle" to a WPO.

The most straight forward way to get a handle to a player is to establish a player via Javascript. When you create a player using the "new wimpyPlayer" method, a handle to the Wimpy Player Object is automatically returned.

Example

var myPlayerHandle = new wimpyPlayer();

"myPlayerHanle" is now a "handle" to a Wimpy Player object.

If you're establishing players via HTML, we have to identify players in the HTML so we can snag them with Javascript. To identifiy a player, we can use a traditional "id" on the Player Instance DIV tag, or we can use the "name" Player Option.

Examples

Using a traditional "id" on the Player Instance DIV:

<div id="player1" data-wimpyplayer></div>

Using the "name" Player Option:

<div data-wimpyplayer data-name="player2"></div>

Now we can snag the handles using the API as:

<script>
function getHandles(){
	var myPlayerHandle1 = wimpy.getPlayer("player1");
	var myPlayerHandle2 = wimpy.getPlayerByName("player2");
}
wimpy.onReady(getHandles);
</script>

"myPlayerHandle1" and "myPlayerHandle2" are now a "handles" to a Wimpy Player Objects.

ID

Every Player has a unique ID. Player ID's are an intragal part of the overall Wimpy system. There a a few different ways that Player IDs are assigned.

If you're using Javascript to create players, you can include the "id" Player Option.

If your establishing players via HTML:
If a Player Instance DIV does not have an ID, Wimpy creates one automatically and assigs it to the player instance DIV.

For example, if we create a Player Instance as follows:

<div data-wimpyplayer></div>

... then Wimpy will automatically create and assign an ugly ID to the player. If there are a few players on the page, it will be very difficult to figure out which player is which.

If you assign an ID to the Player Instance, using a traditional "id" attribute on the DIV, Wimpy will automatically use the ID as the internal Player ID.

For example if you include a traditional "id" attribute as:

<div id="player1" data-wimpyplayer></div>

... then the internal Player ID will be: player1

WARNING
ID's must be unique. HTML programming rules apply to assiging the "id".

Name

Not every player has a name. A name is simply a label that developers can assign to a player in order to make referencing a specific player a little more friendly.

You can assign a name to a player by using the "name" option within the DIV as:

<div data-wimpyplayer data-name="player1"></div>

With Javascript created players you would do something like:

var myPlayer = new wimpyPlayer({name:"player1"});

In the examples above, no ID was assigned, so Wimpy ugly IDs. But that's OK, because we can use the alternate wimpy.getPlayerByName method to get a handle to the player as explained below.

Now that we know how and why IDs and Names are created we'll show you how to use these to get a handle to a player.

Player Handles

What we mean by "handle" is that we need a way to get a grip on a Player Object so we can interact with it.

When you establish a player via javascript, the constructor returns a handle to the player object.

Example

// The variable "myPlayerHandle" is a handle to a player 
// because "new wimpyPlayer()" returns a reference to the 
// newly created Wimpy Player Object.                  
var myPlayerHandle = new wimpyPlayer();

// Players are not fully functional the instant they are created 
// because they need time to load the skin, playlist and so on.

// So we'll leverage the onReady method to wait until 
// the player is ready to be interacted with.
var doSomething = function(){
	myPlayerHandle.setInfo("The player is ready!");
}
myPlayerHandle.onReady(doSomething);

// NOTE: You can also leverage the global wimpy.onReady, 
// which triggers when all players on the page are ready.

When establishing a player via HTML, we use either the wimpy.getPlayer or wimpy.getPlayerByName methods to snag a handle to a player.

<!-- A Player Instance DIV with the "id" attribute assigned -->
<div id="player1" data-wimpyplayer></div>

<!-- A Player Instance DIV with the "name" option assigned -->
<div data-wimpyplayer data-name="player2"></div>

<script>

// Players are not fully functional the instant they are created 
// because they need time to load the skin, playlist and so on.

// We'll leverage the global wimpy.onReady method for our example 
// because there is no Javascript involved when establishing the player.
var doSomething = function(){

	// Using the getPlayer method:
	var myPlayerHandle_1 = wimpy.getPlayer("player1");
	myPlayerHandle_1.setInfo("Player 1 is ready!");

	// Usign the getPlayerByName method:
	var myPlayerHandle_2 = wimpy.getPlayerByName("player2");
	myPlayerHandle_2.setInfo("Player 2 is ready!");

}
wimpy.onReady(doSomething);

</script>

IMPORTANT
You may need to refer to the "wimpy" object using "this" as in the example belo. Generally "this" is may be required when the player is running in an iFrame.

// You may need to refer to the "wimpy" object using "this" as:
this.wimpy.onReady(doSomething);
// ... see the discussion on "Scope" in the documentation.

Player Handle, ID & Name

ID

Name

Player Handles

See Also