Filters are a functionality in WordPress that allows you to easily modify the data or output of other functions on the site. In the Total theme we’ve incorporated TONS of filters that will allow you to alter various aspects of the theme via a child theme without having to manually edit the theme code.
But why wouldn’t you just manually edit the theme’s code? Well, if you edit the theme’s code the next time you update your theme you will lose your edits. By placing your edits inside a child theme using filters, you will never lose your modifications when updating your theme.
Filters work via a function called apply_filters which you can learn about here but it can be a bit tricky to understand especially if you aren’t an experienced developer so I find it easier to explain via examples, have a look at some of them below:
Example 1: Add New Button Styles to Total
In the Total theme whenever you insert a Total theme button you can select from different styles like this:
These options are defined in an array in the theme like such:
Looking at the code you can see the function “apply_filters” which defines the filter named “wpex_button_styles”. This means you can actually use a custom function to add new styles to the options you can choose from via the add_filter function (apply_filters is used to define the filter and add_filter is used to alter it). Like such:
add_filter( 'wpex_button_styles', function( $styles ) {
// Add a new option to the styles array
$styles['custom-style'] = 'My Custom Style';
// Return the array of style options
return $styles;
} );So by using the add_filter function I can modify the list defined by the 'wpex_button_styles' filter to add my own Custom Button Option. Result:
Example 2: Disable the Post Meta Box for a Specific Post Type ( Using the Priority Argument)
The Total theme includes an advanced metabox for making various tweaks to a specific page or post type (learn more here). By default this metabox is displayed for posts, portfolio posts, staff posts, testimonials posts, pages and WooCommerce products. The theme also applies a filter to the post types it supports so that you can easily remove or add it to various post types.
Above is a screenshot of the code located at Total/framework/classes/post-metabox.php and you can see the filter "wpex_main_metaboxes_post_types" applied to the array.
So for example if you want to alter the post types the meta is added to you can use add_filter to remove or add any. Below is an example of removing the metabox from the staff post type:
add_filter( 'wpex_main_metaboxes_post_types', function( $types ) {
// Remove the staff post type from the array
unset( $types['staff'] );
// Return array of post types
return $types;
}, 10 );Priority: Notice how in this snippet I included the number "10" ? Well this is the "priority" for the filter. The default priority is 10 and the higher the priority the more importance the function will take. Example if you add the code twice and in the first instance you removed the staff post type and in the second instance you re-added the staff post type whichever function has a higher number for the priority argument will take over.
Example 3: Filtering with Multiple Arguments
When using apply_filters you can also pass on multiple arguments which can be accessed via add_filter so you can conditionally modify things.
The Total theme includes various custom Grid modules you can use to insert posts to a page such as the "Portfolio Grid". Every grid module when it queries the database it passes the query arguments through the 'vcex_grid_query' filter so that you can customize the query via a child theme for advanced modifications:
As you can see when using apply_filters here we are passing on the arguments ($this->args) which is the variable you can filter via add_filter, however, we are also passing the attributes from the current module as an argument ($this->atts). What this does is it allows us to access the current module settings. This way for example if we give the Grid a custom ID we can check for this value so that we ONLY target this specific module and no other Portfolio Grid on the site:
Below is an example of how we could filter the query for this Portfolio Grid and this one only by checking the Unique ID field:
add_filter( 'vcex_grid_query', function( $query_args, $module_atts ) {
// If the current module unique_id attribute is defined and set to "custom-id"
// then lets make some tweaks
if ( isset( $module_atts['unique_id'] ) && 'custom-id' == $module_atts['unique_id'] ) {
// Lets exclude specific posts from this query
$query_args['post__not_in'] = array( 2, 5, 12, 14, 20 );
}
// Return query arguments
return $query_args;
} );So now you can see how helpful it is for certain instances of apply_filters to pass on extra arguments that you can check for when using add_filter.
Conclusion
As you can see filters are very powerful. so having a bunch of them available in the Total theme makes it very modular giving you full control over essentially everything! Also filters are very efficient so they do not negatively impact your site speed.
What's Next? Actions!
Filters are awesome...but so are actions! The Total theme makes use of actions to output the different elements of the theme on the site (top bar, toggle bar, header, page title, breadcrumbs...etc) and they are also used throughout the theme and very useful for child theme development so take a look at our little guide on WordPress action hooks.