Legacy MP3 Players

Beat Brokerz Website Plugins are ready-to-use script codes that you can easily drop into your existing webpage and instantly beef it up with awesome beat selling power! Out of the box, you don't need any special software or custom page design to use it. It's literally as easy as adding a few new lines of code to your webpage and then point and shoot!

Overview

The core module is a jquery plugin which transforms existing elements on your page into fully functional interactive components which come straight from the Beat Brokerz website. In a matter of seconds, you can add powerful features such as:

How It Works

When you or your designer create the html for your webpage, you just add a special css class to an element to tell our plugin how to transform it. Here's an example:

<img src="http://url.to/pic" />

This is the html code for a regular image. You or your designer can place this into your page as a placeholder for... let's say an mp3 player. This is nothing new, it can be styled and positioned as usual by css.

Now, if you want that image to be hot swapped for an actual "real live" mp3 player as the page loads in a web browser, you simply add a css 'class' (in the html source) to the image like this:

<img src="http://url.to/pic" class="bbmp3-player" />

That's It! Now a mp3 player will appear in place of that image! Could it be any easier?

And of course, it's just as easy to tell our plugin other things like:

Take a look at our "Basic Usage" guide to see how to add the plugin to your own webpage!

Basic Usage: MP3 Players

In this tutorial, we'll show you exactly how to get a basic implementation of the BB Website Plugins code on your page and load your own custom flash mp3 player! Don't worry, it's easy!

Note: The BB Website Plugins core module is a plugin for jquery, which means that you'll first need to make sure that you have the jquery script loaded into your page first. You can do that by placing the following script tag in the head section of your page. (Between the <head></head> tags.)

Load JQuery:
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.0/jquery.min.js" type="text/javascript"></script>

Next, you'll need to load some core BB Website Plugins scripts. Put the following script tags in your header as well, (after the jquery script tag above.)

Load BB Website Plugins Core:

<script src="http://www.bbkz.co/bbapi/jquery.appflow.js" type="text/javascript"></script>
<script src="http://www.bbkz.co/bbapi/jquery.bb.core.js" type="text/javascript"></script>
<script src="http://www.bbkz.co/bbapi/swfobject.js" type="text/javascript"></script>

The API can be configured to track usage stats back to your Beat Brokerz account by calling the $.bbmp3() function with settings from the example below.

Set Configuration Options:

<script type="text/javascript">
    $.bbmp3({
      accountID: 0, // Your Beat Brokerz account ID
      channel: 'Website Plugins',  // The channel to track your stats to
      default_player: 'bbmp3-7933', // The default player to load
      addons: {
        companion: true, // Load the licensing slide out
        fancybox: true // Checkout through an on page popup
      }
    });
</script>

After you have added all script code mentioned above, your html document might look similar to this:

<html>
  <head>
    <title>BB Website Plugin Example</title>
    <!-- start copying script here -->
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.0/jquery.min.js" type="text/javascript"></script>
    <script src="http://www.bbkz.co/bbapi/jquery.appflow.js" type="text/javascript"></script>
    <script src="http://www.bbkz.co/bbapi/jquery.bb.core.js" type="text/javascript"></script>
    <script src="http://www.bbkz.co/bbapi/swfobject.js" type="text/javascript"></script>
    <script type="text/javascript">
      $.bbmp3({
        accountID: 0, // Your Beat Brokerz account ID
        channel: 'Website Plugins',  // The channel to track your stats to
        default_player: 'bbmp3-7933', // The default player to load
        addons: {
          companion: true, // Load the licensing slide out
          fancybox: true // Checkout through an on page popup
        }
      });
    </script>
    <!-- stop copying here -->
  </head>
  <body>

    <!-- webpage content here -->

  </body>
 </html>

Now, for the actual magic to happen inside your webpage when it loads, all you need to do is apply a simple css class to any element that you want to be "re-born" as an mp3 player.

Here is a simple html "anchor" (link) tag.
<a href="http://www.beatbrokerz.com">Instrumentals</a>

Now, to turn it into an mp3 player, add the "bbmp3-player" class to it.

Point and Shoot:
<a href="http://www.beatbrokerz.com" class="bbmp3-player">Instrumentals</a>

That's It. The "bbmp3-player" classification tells the BB Website Plugins module to zap that link and turn it into a bonified Beat Brokerz mp3 player! But that's not all. Here are a few more customizations you can make to your player just by tweaking the attributes of your html "anchor" (link) tag.

You can load any playlist from Beat Brokerz into your player by simply linking to the page that has the beats that you want to play. (It needs to be a charts page, store page, or affiliate store page.)

Load Any Playlist:
<a href="http://www.beatbrokerz.com/charts/top10/hip-hop" class="bbmp3-player">Instrumentals</a>

The above code will load the top 10 hip hop beats from the charts into your player. If you wanted to load the beats from your seller store, you would just link to your seller store (http://www.beatbrokerz.com/stores/{sellerid})

You can also use a theme and settings from one of your custom players that you've set up in your Beat Brokerz account! (My Account > Affiliate Center > MP3 Players). Just set the 'id' attribute of your link to the custom player id (shown when you preview/load your player in the affiliate center).

Use Custom Theme/Settings:
<a id="bbmp3-7933" href="http://www.beatbrokerz.com" class="bbmp3-player">Instrumentals</a>

In the code above, your player will use the custom settings from the mp3-player on Beat Brokerz with an id of "bbmp3-7933". By setting up a custom player to use on Beat Brokerz, you can change colors, buttons, actions, and default settings for the player!

You can customize the title of the playlist displayed in your mp3 player also. Just set the 'title' attribute of your link to the text you want displayed as the title.

Change Player Title:
<a title="My Custom Player Title" href="http://www.beatbrokerz.com" class="bbmp3-player">Instrumentals</a>

In the code above, the title of your player will read "My Custom Player Title".

You can also change the size of your player to fit whatever dimensions that you want. (Must be at least 275px wide X 95px high.) Just set the width and height properties of your link using a stylesheet, or inline css.

Change Player Size:
<a style="width:400px; height:400px;" href="http://www.beatbrokerz.com" class="bbmp3-player">Instrumentals</a>

In the code above, your player will be created 400px wide by 400px high.

Advanced Usage: MP3 Player Programming

Warning: This tutorial involves programming in javascript.

Since BB Website Plugins is built using the popular JQuery javascript framework, it is very easy to tie your own custom programming in to the function of bbmp3 players on your page. If you're not familiar with JQuery, we recommend that you take a crash course first.

Creating Players:

Basic jquery usage:

<script type="text/javascript">

  /* code to execute when the document is loaded */
  $(document).ready(function() {

    /* find all elements with the 'bbmp3-player' class and turn them into mp3 players */
    $(".bbmp3-player").bbmp3();

  });
</script>

The code example above tells jquery to wait until the document is fully loaded, and then finds all elements that have the "bbmp3-player" class and executes the .bbmp3() jquery plugin on them.

When the .bbmp3 plugin is applied without any configuration parameters, the plugin will read in settings from the attributes of any matched elements, and use default settings for everything else. You can optionally specify settings for the plugin to use when you invoke the plugin from a jquery selector.

Alternative jquery usage:

<script type="text/javascript">

  $(document).ready(function() {

    $(".bbmp3-player").bbmp3({
      width: 400,
      height: 400,
      href: "http://www.beatbrokerz.com",
      player: "bbmp3-7933",
      title: "My Custom Player Title",
    });

  });
</script>

Controlling Players:

The bbmp3 plugin can also be used to control command functions on players such as play, pause, stop, volume, etc. You can target an individual player, a list of players, or all players on your page.

Here is the list of available commands:

Dispatching a command is done through jquery as follows:

Native Way:
$.bbmp3('volume', targetPlayers [,value]);

Alternative Way:
$.bbmp3.volume(targetPlayers [,value]);

Example:

<script type="text/javascript">

  /* pause all players on the page */
  $.bbmp3.pause('all');

  /* start playing a player (with a specific ID) */
  $.bbmp3.play('bbmp3-7933');

  /* turn the volume up on two players at once */
  $.bbmp3.volume(['bbmp3-7933','bbmp3-7979'], .8);

</script>

Triggers & Hooks: Creating Custom Applications

Customizing BB Website Plugin Functionality

BB Website Plugins was designed to allow developers to easily add their own custom modules that tie in with the core functionality. These custom modules can do anything from adding new transition effects on page elements, to adding totally new functionality on the page that interfaces with BB Website Plugins.

Triggers & Hooks

BB Website Plugins uses a system of "triggers & hooks" provided by another jquery plugin called AppFlow. Using AppFlow, BB Website Plugins fires "events" at various points where a user interacts with the page (such as when the mp3 player changes songs, volume changes, new mp3 player is created, etc.) You can easily add your own javascript that will be executed at the time these events are fired... and therefore add or change what happens on the page when those events happen.

Click Here to learn more about AppFlow.

Here is an example of how AppFlow works:

<script type="text/javascript">

  $.appflow.bind('bbmp3_songchange', function(playerID, beatID) {
    alert('Player with ID: ' + playerID + ', is now playing a new song with ID: ' + beatID);
  });

</script>

In the example above, we have added a popup alert that will show us what player and what song is playing whenever an mp3 player on the page changes songs. We basically "bind" a javascript function to the event so that when the event is fired, our javscript is executed. There is no limit to how many javascript functions we can bind to any one event. They all get executed in order.

Events

Here is a list of all the BB Website Plugin "events" that you can bind to, and the arguments that will get passed to those functions.

bbmp3_launch : ()
This event is fired when the document (page) is first loaded and it is time for the plugin to convert any elements with the "bbmp3-player" class into mp3 players. It has no arguments.

Example Usage:

<script type="text/javascript">

  $.appflow.bind('bbmp3_launch', 'before', function() {

    /* use our own default settings to create players before the plugin does */
    $(".bbmp3-player").bbmp3({
      player: "bbmp3-1234"
    });

  });

</script>

bbmp3_created : ( playersObj )
This event is fired every time the bbmp3() plugin is invoked and creates at least one player.

Example Usage:

<script type="text/javascript">
  $.appflow.bind('bbmp3_created', function(playersObj) {

    /* make sure each created player is stopped playing */
    playersObj.each(function(){ this.stop(); });

    /* popup notification of how many players were just created */
    alert(playersObj.length + ' players created.');

  });
</script>

bbmp3_playstarted : ( playerID )
This event is fired when a new track begins playing in an mp3 player. It only fires when the track first starts playing, and not if the playback is paused and then resumed.

Example Usage:

<script type="text/javascript">
  $.appflow.bind('bbmp3_playstarted', function(playerID) {

    /* oh yeah, let's turn the volume up! */
    $.bbmp3.volume(playerID, 1);

  });
</script>

bbmp3_playpaused : ( playerID )
This event is fired when playback in an mp3 player has been paused.

Example Usage:

<script type="text/javascript">
  $.appflow.bind('bbmp3_playpaused', function(playerID) {

    /* don't like this track? let's play the next! */
    $.bbmp3.next(playerID);

  });
</script>

bbmp3_playresumed : ( playerID )
This event is fired every time playback in an mp3 player has been resumed. This event is triggered even when playback has started for the first time on a track.

Example Usage:

<script type="text/javascript">
  $.appflow.bind('bbmp3_playresumed', function(playerID) {

    /* let's rewind the playback a little bit (5 seconds) */
    $.bbmp3.rewind(playerID);

  });
</script>

bbmp3_playstopped : ( playerID )
This event is fired when playback in an mp3 player has been completely stopped (the time marker is set back to 0:00).

Example Usage:

<script type="text/javascript">
  $.appflow.bind('bbmp3_playstopped', function(playerID) {

    /* just for fun, let's mute the volume */
    $.bbmp3.volume(playerID, 0);

  });
</script>

bbmp3_volumeset : ( playerID, volume )
This event is fired when the user interacts with the volume slider on an mp3 player and changes the volume level.

Example Usage:

<script type="text/javascript">
  $.appflow.bind('bbmp3_volumeset', function(playerID, volume) {

    /* let's change the volume of all other players on the page to match */
    $.bbmp3.volume('all', volume);

  });
</script>

bbmp3_songchange : ( playerID, beatID [,data] )
This event is fired when a new track begins to play in any mp3 player on the page.

Example Usage:

<!-- an html link that will allow the listener to visit the beat view page on Beat Brokerz -->
<a id="moreinfo" href="#">View this beat on Beat Brokerz!</a>

<script type="text/javascript">
  $.appflow.bind('bbmp3_songchange', function(playerID, beatID) {

    /* let's change the href pointer of our 'moreinfo' link */
    $("#moreinfo").attr('href','http://www.beatbrokerz.com/node/'+beatID);

  });
</script>

bbmp3_buysong : ( playerID, href )
This event is fired when the user clicks the "buy/download" button for a track in the player.

Note: for this to work, the setting for the player's "buy button" must be set to "Trigger Javascript" in the player settings in your Beat Brokerz account.

Example Usage:

<script type="text/javascript">
  $.appflow.bind('bbmp3_buysong', function(playerID, href) {

    /* let's alert the listener that we'll be redirecting them to a new page */
    alert("We'll now redirect you to the download page!");
    window.open(href);

  });
</script>

Data Objects: Using AJAX Functions

About Ajax Data

BB Website Plugins can retreive data from the Beat Brokerz database in real time (on demand). This data can be used to populate content on the page, or for use as input to your custom processing script. It is retreived using a technology called 'ajax'.

A basic example would be when the beat changes on an mp3 player. If the 'ajax' feature is turned on (see below), then your 'bbmp3_songchange' event processing function will receive a data object as the third argument. This data object contains specific information about the new beat that's playing (such as title, description, licensing, buy now, etc). You can then use this information to update or change content on the page in real time.

How It Works

Turn It On:
First you have to turn the feature on in your processing script. Here is an example on how to do that.

<script type="text/javascript">

  $.bbmp3({
    ajax: true,   /* turns ajax feature on */
  });

</script>

Ajax enabled events:
Currently, the following events receive the optional data object as an argument.

bbmp3_songchange : (playerID, songID [,data])
Note: only the 'render' and 'after' hooks receive the data object for this event.

Object Properties:

How to use the data object in the 'bbmp3_songchange' event:

<script type="text/javascript">

  $.appflow.bind('bbmp3_songchange','render',function(playerId, beatid, data) {
    // fill elements on the page
    $('.bbmp3-producer').html(data.producer);
    $('.bbmp3-title').html(data.title);
    $('.bbmp3-description').html(data.description);
    $('.bbmp3-rating').html(data.rating);
    $('.bbmp3-image').html(data.image);
    $('.bbmp3-licensing').html(data.licensing);
    $('.bbmp3-cartform').html(data.cartform);
    // the following line adds the fully qualified domain name to the form submit action
    $('.bbmp3-cartform form').attr('action','http://www.rapbeatbrokerz.com' + $('.bbmp3-cartform form').attr('action'));
  });

</script>