How to customize the info bar and the playlist rows

Infobar and Playlist templates

WavePlayer allows you to personalize the information displayed in the info bar and each playlist row. If you want to customize the Infobar and the Playlist templates, you can go to the Settings —> WavePlayer page on the Dashboard of your WordPress installation. It the HTML & CSS tab, you will find two text areas that you can customize using plain text or HTML syntax, together with audio tags and special placeholders, as explained below.

Each audio tag or placeholder you want to display in the Infobar or the Playlist must be listed in the respective text area, surrounded by the ‘%’ character.

For example, if you want to show the title of a track, you can use the %title% audio tag.

Please refer to the following lists of audio tags and special placeholders to learn what you can show in the Infobar and the Playlist of your players.


Audio Tags

Depending on the format of the audio tracks you upload on your website, the file may include one or more tags containing the audio track’s information. For an MP3 file, those tags are called ID3 tags and you can edit them with several different media players (such as iTunes, Windows Media Players) or other specialized applications. If you edit a file’s tags prior to its upload, WordPress can grab all of them and save the information in the database for future reference.

This is a list of the most common audio tags you can usually find in an MP3 audio file:

%album%, %artist%, %bitrate%, %bitrate_mode%, %channelmode%, %channels%%compression_ratio%, %dataformat%, %encoder_options%, %file%, %fileformat%%filesize%, %genre%, %length%, %length_formatted%, %lossless%%mime_type%, %sample_rate%, %title%, %year%.



Special placeholders

In addition to the previous audio tags, WavePlayer allows you to customize the Infobar and each playlist row using the following placeholders. When rendering a player instance, WavePlayer will replace each placeholder with the respective piece of information, icon or buttons, depending on the placeholder you use.

This is a list of the placeholders you can use:

%likes%: a like button and a counter of the total likes for a given track,
%downloads%: a download button and a counter of the total downloads for a given track,
%cart%: a cart button (an active WooCommerce installation is required),
%play_count%: a counter of the total playbacks for a given track,
%runtime%: a counter of the total time a given track has been listened to,
%share_fb%, %share_gp%, %share_tw% or %share_ln%: a share button , , or to share a track on Facebook, Google+, Twitter or LinkedIn, respectively.

NOTE: a like button can only be used by your logged in users and registers their likes on your website independently from any other social network.


Custom metadata

In addition to the default metadata WordPress automatically extracts from the audio files and store in the attachment metadata structure of each audio attachment, you can create any other custom metadata to use with your placeholders. For example, if you add a metadata called external_url, you can add it to the infobar or the playlist row simply using the %external_url% placeholder.

WavePlayer 2 introduced a waveplayer_add_track_info filter hook that allows you to add any custom value to any track object. In the following example, the callback function your_custom_track_filter is associated to the filter waveplayer_add_track_info. The callback function receives three parameters: $track is the track object; $track_id is the ID of the audio attachment in your media library; $post_id is the ID of the post or page that contains the instance of the player loading the track.

function your_custom_track_filter( $track, $track_id, $post_id) {
    
    // do something here to generate the value you want to assign
    // to the 'your_custom_meta_key' placeholder
    
    $track['your_custom_meta_key'] = $your_custom_meta_value;
    return $track;
}
add_filter( 'waveplayer_add_track_info', 'your_custom_track_filter', 10, 3);

When WavePlayer finishes loading all the default information into the track object, it invokes the filter so that you can add as many custom values as you like. In the example above, the your_custom_track_filter function uses the input parameters to retrieve the custom information your_custom_meta_value that you want to add to the your_custom_meta_key placeholder.

Simply adding the code above to the functions.php file of your theme/child theme, a new your_custom_meta_key placeholder will be available for you to use anywhere in the Info Bar or the Playlist Row templates.

Placeholder attributes

The placeholder functionality comes with a list of attributes that help you get the best result for your design. This is a comprehensive list of attributes currently available in WavePlayer.

urlWhen you specify a “url” key in the attributes of the placeholder, WavePlayer is going to build a link pointing to the URL you provide there. You can also use a metadata placeholder as the url value.

Example with a static URL: %artist{"url":"https://www.example.com/artist_url"}%

Example with a metadata placeholder for the URL:
%artist{"url":"%_artist_url_metadata%"}%

In this second example, each track must contain a meta value for the “_artist_url_metadata” meta key in the postmeta table.

iconWhen you specify an “icon” key in the attributes of the placeholder, WavePlayer adds two classes: the wvpl-icon class and the value assigned to the attribute as an additional class. This second value is particularly useful when using external icon libraries like Dashboard Icons or Font Awesome.

Example:%my-custom-icon{"icon":"fa-exclamation-triangle"}%

classAdd a class attribute to a <span></span> enclosing the placeholder

Example: %placeholder{"class":"my-placeholder-class"}%

rawNormally, WavePlayer encloses the placeholder in a <span></span> tag. When the raw attribute is set to 1, WavePlayer returns the raw data corresponding to the placeholder.

Example: <a href='%external_url{"raw":1}%'>BUY</a>

Mind the difference between the single quote enclosing the href attribute and the double quote enclosing the name (and values, in case of strings) of the placeholder attribute. The opposite way does not work, as the list of placeholder attributes must be formatted according to the JSON specifications.

eventYou can associate a custom event to any placeholder simply adding the event attribute with a value representing the name of the event triggered when clicking on the placeholder. You can call the placeholder any way you like.

Example: %my_icon_with_custom_event{"event":"myCustomEvent","icon":"my-icon-class"}%

The example above will create an icon that, when clicked, triggers the myCustomEvent event on the enclosing WavePlayer instance. You can then detect that event as follows:

$(document).on( 'myCustomEvent', '.waveplayer', function(event, track) {
// your custom function here
});

The function associated to the event gets passed two parameter: the usual jQuery event object and the track object.