Buy WavePlayer now, only on

Posted on

Using WavePlayer with AJAX-powered Themes

AJAX (Asynchronous Javascript And Xml) is a technique incorporated by many themes and plugins nowadays. If you ever experienced a website that is capable of loading new web content in single portions of a web page, without the need to reload the whole page itself, you have already used – albeit without knowing it – AJAX.

In the WordPress ecosystem, themes use AJAX to offer a more fluid pagination experience to their customers. Also WavePlayer uses AJAX to complete several tasks: retrieving the information of the tracks loaded inside an instance, sending to the cart the information of the product the user has just added, updating the statistics of a track or the number of likes or downloads when a user clicks on a button. The advantage of using AJAX is that, whatever the visitors are doing on your website, all these operations won’t interrupt them, because the page doesn’t refresh, but the content of the page will reflect anyway the changes they made to the page.

If you like to read more about AJAX, I recommend you this AJAX INTRODUCTION on W3Schools.

WORKING WITH WAVEPLAYER AND AJAX

When the portion of the page the theme is loading via AJAX contains an instance of WavePlayer, the instance needs to be initialized manually. The reason is that the script that initializes all the instances of WavePlayer in a page has already run at the completion of the page loading. Thus, when the theme loads the new content via AJAX, you need to call the initialization function after the new content finishes loading. Otherwise, the markup of the player will be in the page, but the player never gets initialized.

The main function initializing the instances of WavePlayer on a page is loadInstances() and can be called as follows:

WavePlayer.loadInstances();

The main problem, here, is finding where we can call that function. Since the AJAX is by design an asynchronous operation (we cannot predict when the visitor is going to click on a pagination link or update a post search), we need to attach the initialization function to an event that fires after the new content has completed loading. In the next two paragraphs we are going to describe the main two scenarios you will see when using an AJAX-powered theme.

THE TRIGGER METHOD

Any AJAX operation starts with a Javascript call attached to an action of the visitor (the click on a button or the change of a selection). If the scripts of your theme are developed keeping in mind the web developer who needs to extend their functionalities, at some point in the code where the AJAX request returns the content of the page, you will find a call to a trigger method. This is a very basic example of an AJAX request that triggers a “content-loaded” event for the current document:

function searchPosts(keys) {
    $.ajax({
        type: 'post',
        dataType: 'json',
        data: {
            action: 'my_theme_search_posts',
            keys: keys
        },
        success: function( result ) {
            $('#search-container').html(result.html);
            $(document).trigger('content-loaded');
        }
    });
}

In that scenario, calling the loadInstances() function would be as simple as adding the following script to the “Custom JavaScript” text box of the WavePlayer Settings, in the HTML & CSS page:

$(document).on('content-loaded', function(event) {
    WavePlayer.loadInstances();
})

What happens is that, after the theme script retrieves the content it requested and triggers the content-loaded event, the document calls all the scripts bound to that event, including the one we added to the Custom JavaScript box.

In this scenario, the most important aspect is finding the information about the event triggered upon loading of nw content via AJAX. Usually, those events are mentioned in the theme documentation. If they are not, a short research in the theme script, using the keyword “trigger” should help you find what you need.

THE CUSTOM SCRIPT in the THEME OPTIONS

Some more advanced themes provide you with a Custom Javascript option, offering you the possibility to bind a script to a certain event. In that case, you only have to find the right place in the theme settings where to write the loadInstances() function, but the principle is still the same.

IF NOTHING WORKS

If none of the previous options are available and contacting the theme developer does not help, the last resource you can try is binding the loadInstances() method directly to the object responsible for sending the AJAX request (the button, the link, the dropdown box). Because of its asynchronous nature, though, we cannot predict when the AJAX request is going to return the values it gets from the server. Thus, the problem is that if we call the loadInstances() method BEFORE the AJAX request has returned, the method is not going to initialize any instance. A possible solution to that – but far less ideal than the previous approaches – is delaying the call to loadInstances() using a setTimeout() function with a reasonably long delay time.

In the following example, the loadInstances() method is bound directly to the click event of the pagination link:

$(document).on('click', '.pagination a', function(event) {
    setTimeout(function(e){
        WavePlayer.loadInstance();
    }, 2000);
});

The evident problem with that approach is that the loadInstances() method gets called 2 seconds (2000 ms) after the visitor clicked on the pagination link. If the AJAX call has not returned in those 2 seconds, the loadInstances() will have nothing to initialize, as the new content has not been loaded yet. Conversely, if the AJAX call returns in 100ms, the loadInstances() won’t be called for the subsequent 1900ms because the timeout has not fired yet.

Posted on

Embedding WavePlayer

Starting from version 2.3.1, it is now possible to embed WavePlayer inside other websites using an <embed> element.

1

WavePlayer 2.3.1 comes already with this capability, but you need to add an embed-attachment.php file to your Theme (or, even better, to your Child Theme).

When WordPress finds that file in your Theme root folder, it uses it to display an element from your website inside an <iframe>. If you want to read more about this technique, you can refer to this article in the WordPress documentation.

The embed-attachment.php template file

Let’s start with a basic structure of the embed-attachment.php file.

<?php
get_header( 'embed' );
if ( have_posts() ) :
	while ( have_posts() ) : the_post();
		echo do_shortcode("[ waveplayer ids='".get_the_ID()."']");
	endwhile;
else :
	get_template_part( 'embed', '404' );
endif;
get_footer( 'embed' );
?>

Compared to the usual single.php, the file embed.php (or, in this case, embed-attachment.php) adds the name ’embed’ to get_header() and get_footer(). We then see the main query looping among all the results. Since this is going to be used on a single attachment post, the query is going to return only one result: the page of the attachment we want to embed inside an external website.

How do we get the right link to be used in the embed element? It is pretty easy. Just go to the Media library and click on the thumbnail of the audio attachment you want to embed. In the right bottom corner, look for the link “View Attachment Page“, right click on it and choose “Copy link address” (or, alternatively, click on it and copy the URL in the address bar of the browser).

Now, it is just a matter of typing the right embed code inside the website where we want to publish our attachment. The embed code looks like this:

<embed height="220" src="https://www.waveplayer.info/10197133_wedding_by_audiopizza_preview/?embed=true">

Please note that, in order for this to work, it is important that you add embed=true at the end of the link. You need also to pay attention to the structure of the URL you copied. If the URL already contains some arguments, like the following one:

www.waveplayer.info/?post_type=attachment&p=1614

then you have to add embed=true at the end of the URL prefixing it with an ampersand (&) like this:
www.waveplayer.info/?post_type=attachment&p=1614&embed=true

On the contrary, if your URL is a permalink like this:

www.waveplayer.info/10197133_wedding_by_audiopizza_preview/

you have to prefix embed=true with a question mark (?), like this:
www.waveplayer.info/10197133_wedding_by_audiopizza_preview/?embed=true

A simple rule of thumb to better understand whether you need to use a question mark or an ampersand is checking the URL you have before adding the embed argument. If the URL already contains a question mark, then it means you need to add the embed argument prefixing it with an ampersand. If the URL doesn’t contain a question mark, then you need to use that to add the embed argument.

Providing additional arguments

You can also pass additional arguments to the URL you embed, so that you can alter the aspect and the property of your embedded WavePlayer instance. For example, the following example pass the size and the shuffle argument to the embedded player:

www.waveplayer.info/10197133_wedding_by_audiopizza_preview/?embed=true&size-large&shuffle

Of course, we have to make some adjustments to the embed-attachment.php file as well, so that we process the additional arguments. The following code retrieves the size and shuffle arguments from the URL and incorporates them into the shortcode:

<?php

extract($_GET);
$args = array();
if ( isset( $size ) ) $args[] = "size='$size'";
if ( isset( $shuffle ) ) $args[] = "shuffle='true'";

$args = implode( " ", $args);

get_header( 'embed' );
if ( have_posts() ) :
	while ( have_posts() ) : the_post();
		echo do_shortcode("[ waveplayer $args ids='".get_the_ID()."']");
	endwhile;
else :
	get_template_part( 'embed', '404' );
endif;
get_footer( 'embed' );
?>

Following the example above, you can add as many arguments as you like to the embedded URL, adjusting the WavePlayer instance to your needs.

Posted on

Play and Wave

When you need to visualize several instances of the player on your page and you don’t want to clutter the space with too many elements, this customization can help you get a more streamlined player.
.wvpl-left-box {
    background:none!important;
    width:40px;                
    height:60px;               
    border-radius:0!important; 
}
.wvpl-right-box{
    height:60px;               
}
.wvpl-interface:hover {
    background:none!important; 
}
.wvpl-poster{
    display:none;              
}
.wvpl-info,.wvpl-volume{
    visibility:hidden;         
}
.wvpl-icon.wvpl-play{
    color:#058;                
    text-shadow:none;          
}
.wvpl-infobar{
    visibility:hidden          
}




If you prefix your CSS rules with a specific class, you can limit your customization to those players that are inside an element with that class.
Posted on

Big Thumbnail, Small Waveform

This is a perfect example of how deep it is possible to customize WavePlayer. The customization shown in this example can be achieved simply by adding few CSS rules to your stylesheet or to the Custom CSS box of the WavePlayer settings. Without those rules, the player you see on this page would display exactly like the one on the homepage. This is the set of CSS rules that allow to transform the default player into the one shown on this page:
.waveplayer{
    display:flex;
    flex-direction:column;
}
.wvpl-left-box{
    width: 100%;
    max-width:300px;
    position: relative;
    display:table;
    border-radius:0;
}
.wvpl-left-box::before{
    content:"";
    width:100%;
    padding-top: 100%;
    display:table;
}
.wvpl-right-box {
    width:100%;
    max-width:300px;
    height:80px;
    margin:0;
    margin-top:-80px;
    background-color: rgba(0,0,0,0.75);
    z-index:200;
}
.wvpl-waveform{
    margin:10px;
    height: calc(100% - 20px);
    width: calc(100% - 20px);
}
.wvpl-infobar{
    visibility:hidden;
}
.wvpl-interface,.wvpl-poster {
    top:0;
}
.wvpl-interface:hover{
    background:none;
}
.wvpl-volume-overlay{
    display:none;
}
.wvpl-info,.wvpl-volume,
.wvpl-position,.wvpl-duration{
    visibility:hidden;
}
.wvpl-icon {
    font-size: 36px!important;
}

With the style described by those rules, the thumbnail expands responsively, adapting to the width of its container up to a maximum of 300px. If the container is larger, the player sits in the center, 300px wide. You can adjust those rules to your specific case.

You can easily limit this style to a certain page or set of pages simply by prefixing all the rules above with the class of a container that pertains to that page or set of pages. For example, if you wanted to assign this aspect for all the players in the WooCommerce Shop page, it would be enough to write all those rules with the .products (plural).
Posted on

Playlist with max-height

In this example, a specific CSS rule is applied to the playlist to set its max-height, like this:
.wvpl-playlist ul {
    max-height: 160px;
}

Because of that setting the playlist only shows 4 of the 8 items included in the playlist. The hidden items can be revealed scrolling with the mouse. In addition to that, WavePlayer automatically scrolls the playlist to make the playing track always visible. The automatic scrolling occurs either when the user advance the tracks with the skip buttons and when the player jumps to the next track at the end of the current one.
Posted on

Sizes and shapes

Large player


[code][ waveplayer size="lg" wave_mode="0" ids="1014,24,22,20" ][/code]

Buy WavePlayer now, only on


Medium players with round thumbnails and repeat_all


[code][ waveplayer repeat_all="true" shape="rounded" gap_width="3" ids="58,51" ][/code]

Buy WavePlayer now, only on


Small players with square thumbnails and shuffle


[code][ waveplayer size="sm" shuffle="true" shape="square" wave_mode="5" ids="53,51,22,15" ][/code]

Buy WavePlayer now, only on


Extra Small single-track players


[code][ waveplayer size="xs" wave_mode="2" gap_width="4" ids="20" ][/code]

Buy WavePlayer now, only on