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.


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.


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:

function getHandles(){
	var myPlayerHandle1 = wimpy.getPlayer("player1");
	var myPlayerHandle2 = wimpy.getPlayerByName("player2");

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




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

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


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.


// 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>


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:
// ... see the discussion on "Scope" in the documentation.


See Also

- Scope
- Overview (describes the "wimpy" object a little better)