Hi there Beans Community,
I've been wondering about since I started using the Beans theme (which is awesome by the way!). When would you use the default wordpress 'add_action()' function versus the 'beans_add_action()' and 'beans_add_smart_action()' functions and why would you use them?
Thanks in advance!
Hi Nick.
Beans Actions API (I recommend to read this article) extends WordPress core Actions API. The goal is to make it easier to manipulate actions.
Standard WordPress actions example
With standard WordPress actions, all arguments have to be passed to change an action. For example if an action is added as such
add_action( 'example_action', 'example_callback', 12, 2 );and we want to replace the callback function, we have to first remove it passing all arguments and then re-add it as such
remove_action( 'example_action', 'example_callback', 12, 2 );
add_action( 'example_action', 'example_new_callback', 12, 2 );This isn't really convenient are rather hard to work with, especially if an argument such as the priority changes overtime.
Beans Actions API examples
Since Beans Core uses a lot of actions, we decide it to make it easier to manipulate them by registering actions with an ID and build a set of functions to manipulated them.
Example using beans_add_action()
To answer your question, let's first look at beans_add_action(). To replicate the example above, the action would be added as such:
beans_add_action( 'example_unique_id', 'example_action', 'example_callback', 12, 2 );Then to replace the callback, we can just do as such:
beans_modify_action_callback( 'example_unique_id', 'example_new_callback' );Note how we can do it with one line of code, only passing the ID and the new callback without worrying about passing the action priority and number of arguments.
Example using beans_add_smart_action()
Now that we understand a bit more about how Beans Actions work, let's look at beans_add_smart_actions() which is simply a shortcut of beans_add_action(). As you can see in the example above, we passed 'example_unique_id' as the first argument of beans_add_action(). This is fine but we thought that since PHP function names are always unique in PHP, why not having a smart function which used the callback function name as the action ID. And beans_add_smart_actions() was born 🙂 So to add the action, we would do it as such:
beans_add_smart_action( 'example_action', 'example_callback', 12, 2 );The action is registered using 'example_callback' as for the ID (again function names are always unique in PHP so it works). Then to modify it as per the example above, it would be done as such:
beans_modify_action_callback( 'example_callback', 'example_new_callback' );Note that the action ID doesn't change when the callback changes, it will always keep it's original ID.
When to use Beans Actions API
Beans core is built entirely using Beans Actions API so that it makes it easy for users to manipulate them. However when using actions in your child theme you do not need to use it as you don't really need to modify it further. So the bottom line is; if you are building commercial plugins, it makes sense to use them, but if you are building a website it is perfectly fine to use normal WordPress Core actions.
I hope it makes a bit more sense to you how Beans Actions API work 🙂 I will let you refer to the Beans Actions API documentation to find out more about the other functions available to manipulate the actions.
Happy coding,