How to use SearchWP Hooks
SearchWP utilizes the same hooks system that WordPress uses. Hooks are a big part of what make WordPress plugins possible, because they allow you (the developer) to apply customizations to WordPress without having to edit core files. What this does is keep your code separated, allowing you to continually update WordPress without losing your customizations. SearchWP is not only built on WordPress’ hook system, it has a lot of it’s own.
If you’ve never added your own hooks, it might look a bit strange. It’s important to keep in mind how valuable this system is though, keeping your customizations separated from the core piece of code keeps things cleaner and more maintainable.
What are hooks?
‘Hooks’ is a phrase that encompasses two types of ways you can integrate with WordPress/SearchWP. They are as follows:
Actions: Actions are arbitrary points in the execution of the core code that allow you to fire your own functions before the core code continues
Filters: Filters send a variable (or multiple variables) out of the core code, allow you to filter/change it, and send it back to the core code.
Both actions and filters have their own uses, but you utilize them in a similar way.
How to add your own hooks
You have a couple of choices when deciding how to implement your own hooks. The most common way to utilize a hook is by adding some code to your active theme’s functions.php
. The functions.php
file is included on every page request, so the code is always run every time someone visits any page of your site.
The other way to utilize a hook is through your own plugin. Many times developers prefer to keep certain bits of code separated into a plugin in case the theme gets changed later on. Keep in mind that only the active theme’s functions.php
is included so if you utilize hooks in functions.php
and someone changes the theme your hooks will no longer be applied. If you’ve never written a plugin, writing one to execute a hook is a great way to learn! The Codex has a lot of information on writing your own plugin.
Once you’ve decided where you’re going to place your hook, it’s a matter of adding the snippet to the file (either functions.php
in the active theme, or your plugin file) and customizing it as you wish.
The main purpose of hooks is to allow you to change something while the code is executing, so very often there will be a variable (or something) that you will want to customize after seeing a hook snippet you would like to use.
Adding a hook for SearchWP
While SearchWP has a number of settings you can configure using the UI (weights, exclusions, etc.) there is a lot more you can customize, as outlined in the Hooks documentation.
For example: if a Custom Field meta key you want to use isn’t included in the Custom Fields dropdown when setting up weights (because it lists only the 25 most-used by default) you can fully customize what’s listed by using the searchwp_custom_field_keys
filter.
<?php | |
function mySwpCustomFields( $keys ) { | |
// $keys is an array of Custom Field keys | |
// I want to add 'sku' to that list | |
$keys[] = 'sku'; | |
// I need to return my customized array back to SearchWP | |
return $keys; | |
} | |
add_filter( 'searchwp_custom_field_keys', 'mySwpCustomFields' ); |
Note make sure to only include the <?php
line when necessary or you will trigger a PHP error. If after adding a hook you notice an error, make sure to check for that.
After adding that snippet of code to either your active theme’s functions.php
or your custom plugin that handles your hooks, ‘sku’ will now be at the bottom of the list of Custom Fields you can assign specific weights to on the SearchWP settings screen.
Hooks are very powerful, take advantage of them
That’s just one example of a single hook implemented in SearchWP. You can use hooks to implement very complex customizations of search on your website powered by SearchWP. Other hooks will allow you to customize the weights you have set in real time in response to certain terms being searched for. You can use a hook to set up a custom search form that limits search results to a single (or multiple) categories if you’d like. SearchWP has a hook that lets you control the list of stop words that are excluded from the index. The list goes on, and everything is documented for you to utilize.