With the help of filters, you can connect Ultimeter with any 3rd-party source. This article introduces the 3 different filters, explains what you need to do to get Ultimeter to work with your chosen data.

The Filters #

Ultimeter has a filter that works for currency, percentage or custom units.

$current = apply_filters('ultimeter_progress', $current, $id);

If you are unfamiliar with hooks, we encourage you to read the basics here: https://www.wpbeginner.com/glossary/hooks/

The easiest way to explain the filters is to use a real world example. You have installed a Forms plugin, that simply allows users to fill out a form on your site, each time they see a rare parrot in their back garden. When you reach 100 forms (or parrot sightings), you will reward the 100th bird-watcher with a gold medal.

You know that you need to be able to see the real-time number of sightings, so you speak to the developers of the Forms plugin. They tell you that there is a function included in the code that counts the number of forms received for each form, and spits out the total. Let’s call it:

getTotalNumberOfSubmissions( $form_id );

At this stage, you don’t really need to know how the Forms plugin calculates the total. All the developers said was to swap ‘$form_id’ for the ID number of the form you want (you remember this was ‘1’), and that was it.

So, how do we connect the function you’ve been given, with Ultimeter?

Joining the Dots #

First head to your functions.php file. This is where you insert all sorts of custom code. Here’s a brief intro from the WordPress team: https://codex.wordpress.org/Functions_File_Explained.

The filter has 2 arguments, the current value (which we will be sending back) and the id of the Ultimeter. Let’s type our filter at the end of our functions.php file:

function countSightings( $current, $id ) {
    $current = getTotalNumberOfSubmissions( 1 );
    return $current; 
}
add_filter('ultimeter_progress', 'countSightings', 10, 2 );

If you were to check your Ultimeter now (assuming you have correctly set it up to measure custom units, and entered something like ‘Bird Sightings’ into the custom units box), you should see the correct number of sightings being tracked. Even better, the filter will continue to update as new forms are submitted.

We can go a step further and make this only apply to one particular Ultimeter. Let’s say we only want an Ultimeter with an ID of 5 to display parrot sightings, we could do something like the following:

function countSightings( $current, $id ) {
	if ( $id == 5 ) {
		return getTotalNumberOfSubmissions( 1 );
	} else {
		return $current;
	}
}
add_filter('ultimeter_progress', 'countSightings', 10, 2 );

It Isn’t Working/I Don’t Understand! #

As an Ultimeter customer, we are able to provide you with support for the filter itself, but not the bit in the middle. We won’t be able to assist with the code that gets the data from your 3rd-party source. We wish we were experts in every one of the millions of plugins and data sources available, but sadly we aren’t.

If you require further help in setting up your custom data source, any web developer should be able to assist, or get in contact with us directly and we will give you a quote.