Monthly Archives: August 2015

How To Use WordPress Filters and Actions To Extend Plugins Functionality

There are two main ways to extend or customize existing WordPress plugin without editing the code directly – filters and actions (as a whole called “hooks”). The WordPress Codex does a good work of documenting the functions for actions and filters. It does not do such a good job in giving easy to understand example how to actually use this to do something useful. We are going to fix the problem with this tutorial.

Before going further you must have one thing in mind – the plugin that you are going to customize must be customization-friendly and offer at least some hooks. Example of such plugin is our Namaste! LMS with its Developer’s API. If you are writing a plugin it’s good to think about adding do_action and apply_filters calls on the most important places.

In this tutorial I’m going to use a couple of examples from Namaste! LMS and our other developer-friendly plugin WatuPRO to illustrate the usage of only the 4 most important action / filter functions:

  • do_action
  • add_action
  • apply_filters
  • add_filter

Let’s go!

Filters

The below chart will give you basic idea how filters work. Then we’ll provide some examples.

filters

Filters are used mostly when you want some content to be modified before displayed or sent to user. You can apply filters on text but not only – there are a lot more creative ways to use filters. Here are a couple examples from Namaste! LMS:

1. All the places where courses are selected to be shown to the user in Namaste! LMS have this hook:
$courses = apply_filters('namaste-reorder-courses', $courses);

What does it do? It allows other plugins to apply changes directly to the $courses array. And Namaste! PRO uses exactly this filter to apply the custom order of courses to the array by catching the filter:

add_filter( 'namaste-reorder-courses', array('NamastePROCourses', 'reorder_filter'));

There are several things that you must understand here:

a) The “source” plugin (the one that you will be customizing) must provide the proper filter by calling apply_filters($tag, $value) on the variable that will be modified. The first argument is the tag of the filter. It’s just unique name that will then be used by other plugins in the add_filter($tag, $function) call. When the name matches, the function defined in add_filter will be executed over the content of $value from apply_filters in the other plugin. Thus you can modify the $value (in our cases $value is the variable $courses).

b) The extending plugin must catch the filter with add_filter() call as explained above. But in order anything to happen the extending plugin should also define the function or method mentioned in the add_filter call (the second argument called $function). Look at the code again:

add_filter( 'namaste-reorder-courses', array('NamastePROCourses', 'reorder_filter'));

This means your customization plugin should have a class called NamastePROCourses with method called reorder_filter.

c) The apply_filters() call returns the modified $value which should also be returned by the function defined by add_filter(). It’s not important how exactly the method reorder_filter works but it must return the modified variable:

static function reorder_filter($courses) {
   // do something with $courses inside the method
   // not shown here

   return $courses; // return the modified variable
}

Only this way the $courses variable will be modified in the original plugin.

d) Multiple plugins can apply changes to the content using the same filter tag. So you can write your plugin that will for example add more properties to the $courses array, slice it, erase it, change it to something completely different and so on.

e) Do not rely on order of filters execution. When writing a custom plugin you should never assume that add_filter() calls from other plugins will be executed before or after your call.

f) If no filters are defined with add_filter for a given tag, then the apply_filters call will return the original variable.

2. As you saw from the above example, you can filter not just text but any kind of variable – in our case it was an array. The below example will demonstrate a smart trick using text. We need to allow external plugin to apply user-based restrictions to the SQL query that selects courses. instead of working with the courses array, we just use SQL variable string that will be applied to the query:

$filter_sql = '';
$filter_sql = apply_filters('namaste-course-select-sql', $filter_sql, $user_ID);

In the above example the variable $filter_sql (which is after that used inside the SQL query string) is first initialized as empty string. This way if no plugin defines add_filter on the namaste-course-select-sql tag, the string will remain empty and the query will remain as is. However if another plugin catches this filter and adds some SQL to it, the query which contains the $filter_sql variable will also be changed!

The above example also passes additional argument so the add_filter call needs two extra arguments:

add_filter( 'namaste-course-select-sql', array('NamastePROClass', 'course_select_sql'), 10, 2);

Check the add_filter documentation to understand why they are required.

Actions

Actions don’t return value and don’t let you modify variables but are probably even more powerful and easier to understand than filters. Actions let you notify other plugins that something in your plugin has happened. Then the other plugins can act based on it. You can also pass arguments to actions. The “source” plugin must call do_action($tag) and the receiving (customization) plugins must call add_action($tag, $function) with the same $tag to catch the action and call the $function. Here are a couple of examples:

1. Probably the most used action call in WatuPRO is the “waturpo_completed_exam” action called when a quiz is completed:

do_action('watupro_completed_exam', $taking_id);

This call sends the ID of the just taken quiz record so other plugins can use it. And they do. For example the Play Plugin catches this action to update user’s level, badges, points balance etc:

add_action('watupro_completed_exam', array($_user, 'update_meta'));

The variable $_user in this case is instance of the WatuPROPlayUser user object which has method update_meta. The method update_meta takes one argument – the taking ID – and does things with it:

function update_meta($taking_id){ /* do something here */}

Of course, just like with filters, the call to add_action must use the the same tag as the call to do_action to catch the action – in this case the tag is watupro_completed_exam.

2. Here’s a bit different example, this time from Namaste! LMS. At the end of creating the menu of the plugin we add the following simple do_action call, no arguments needed:

do_action('namaste_lms_admin_menu');

This lets other plugins hook their links under the Namaste! LMS menu so their extra options nicely align in it instead of creating more top-level menu links. This action is caught by Namaste! Reports, Namaste! Connect, Namaste! PRO, the InstaMojo integration plugin and many more. If you write your own plugin for Namaste! LMS I recommend using the same action (in case you need to add pages to the menu). Example call:

add_action('namaste_lms_admin_menu', array('NamastePRO', 'menu'));

Then the menu() function in NamastePRO class simply adds its own add_submenu_page() calls to add more links (note that the add_submenu_page() parent slug must also be properly defined).

Actions and filters give you huge options for customization and the best of it: without touching the code of the original plugin. Beautiful! Of course this is only possible if the original plugin defines do_action and add_filter calls in the proper places. If it doesn’t you can try to request the original developer to add some hoks. Most will not refuse because adding a hook here and there is not hard and makes the plugins easier to extend.

If there’s anything unclear in the above explanations, please ask in the comments.

WatuPRO 4.9

The latest version of the WordPress quiz plugin WatuPRO is now 4.9.

Below are the new features and improvements done between versions 4.8 and 4.9:

      • Question difficulty levels can now be selected in user’s profile (by admin). When this is done the user will be restricted to access only questions from the selected difficulty levels.
      • Difficulty levels can have unlock criteria to be automatically unlocked (if you select “Apply difficulty level restrictions per user account.”)
      • Added log that will show you who and when unlocked a difficulty level (provided that you select “Apply difficulty level restrictions per user account.”)
      • The search form on “view results” page will now include the Phone and Company fields, when they are requested in the quiz.
      • Limit the number of logged in users quiz re-takings within interval of 24 hours, a week, or a month.
      • Certificates now can be issued for completing multiple quizzes with min. average points and / or min. average % correct answer.
      • New option lets you enable a rating widget so users can rate questions.
      • New “final screen” variable %%ANSWERS-PAGINATED%% lets you display the user’s answers one at a time, with a numbered pagination.
      • Added option to automatically cleanup or blank out user submitted data older than X days (to save database space).
      • PDF Certificates can now be attached to emails (Requires PDF Bridge version 0.8 or newer)
      • New option “When no more attempts are available display the latest result.” lets you display a snapshot of the final screen when logged in user that can’t retake the quiz visits the quiz page.
      • The variable %%USER-NAME%% can also be used in the email subject.
      • Added variable %%ADMIN-URL%%. It can be useful for the email sent to admin to quickly find the submission details in the administration.
      • [Reporting module] A bar chart shows the average % correct answers per skill.
      • [Intelligence module] Fill the gaps questions can now accept a numeric range also as correct answer.
      • [Intelligence module] Paid quizzes are now available for non-logged in users as well. To use this your server must support sessions (true in 99% of the cases). Also note that coupon codes functionality is currently available for logged in users only.
      • [Intelligence module] Date stamp when teacher manually edits user results will be stored and shown in the list of results on a quiz.
      • [Intelligence module] You can specify individual CSS for every gap (in Fill the gaps questions) by passing it like last correct answer for the gaps. Example: {{{answer1|answer2|style=”width:250px;font-weight:bold;height:50px;”}}}
      • [Reporting module] Fixed bug: the “Different tests attempted” on the Overview page was showing 0.
      • Fixed subcategory related issues in the Reporting module -> Skills.
      • Fixed false “category name already exists” message when adding subcategories.
      • Fixed bug when user  with the same session saves multiple in-progress quizzes (only one was saving).
      • Fixed bug with saving and reusing the “common category grade design” in the default grades page.
      • Fixed bug with timed quizzes that store user progress and randomize questions (questions order was lost during different unfinished quiz attempts).
      • Fixed bug when timed “non-ajax” quiz required contact details at the beginning (the details were getting lost)
      • Added auto-scroll to top after filling contact details on quizzes that ask for them at the beginning.
      • Improved styling of the buttons in the admin pages.

The new version is sent by newsletter to eligible customers.