Triggers & Hooks: Creating Custom Applications

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.

  • playersObj : this is a jQuery object which contains the selection of players that was just created.

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.

  • playerID : this is the id of the player for which playback has started.

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.

  • playerID : this is the id of the player for which playback 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.

  • playerID : this is the id of the player for which playback has started / resumed.

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).

  • playerID : this is the id of the player for which playback has been stopped.

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.

  • playerID : this is the id of the player for which the volume has been changed.
  • volume : this is a decimal value between 0 and 1 that represents the new 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.

  • playerID : this is the id of the player for which a new track has started playing.
  • beatID : this is an integer value, the "id" of the beat assigned to it in the Beat Brokerz system.
  • data (optional) : this is an object which contains more information about the beat being played. It is only passed to the 'render' and 'after' hooks of the main event. Also, it is only passed when the bbmp3 plugin's "ajax" feature has been turned ON. (Please see our tutorial on using the bbmp3 ajax feature for more information on how to use this.)

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.

  • playerID : this is the id of the player for which the volume has been changed.
  • href : this is the url to the beat view page for this beat on Beat Brokerz

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>