Those of you who read my blog regularly will probably know, that I use Gravity Forms in many projects. I really like the huge feature set of the plugin (and it’s add-ons), but even more than that, the possibilities to customize things. I’ve also helped to build such an extension, which allows you to bulk download all files of one (or many) entries. This week we have released a new version introducing a small but important feature: the possibility to have form specific hooks.
Hooking into Gravity Forms
When customizing Gravity Forms functionalities, it works just as with Core and plugins/themes. You would use add_action() or add_filter() for your custom code. And Gravity Forms has a lot of actions and filters!
Let’s take the gform_pre_submission action as an example. You can use this action to change the entry before notifications are sent, and before it is saved to the database. A use case might look like this:
function my_gform_pre_submission( $form ) {
$_POST['input_1'] = strtolower( $_POST['input_1'] );
}
add_action( 'gform_pre_submission', 'my_gform_pre_submission' );
This would take the value of the form field with ID 1 (input_1) and change the text to lower case. This however would do it for every single form you have created. If you just want to do it for one form, you have to use the action specifically for this form. Fortunately, that’s possible by using the dynamic form specific hook names. Just replace the add_action call with this line:
add_action( 'gform_pre_submission_5', 'my_gform_pre_submission' );
This action name has a _5 suffix and will therefore only be called for the form with the ID 5. I’ve already covered this in the blog post Dynamic form specific hooks for GravityForms earlier this year, where I’ve also explained on how to deal with those static form ID values in the hook names.
Now that we have repeated this little introduction, let’s dive into adding such a form specific hook into your own code.
Providing hooks in your custom code
When you want to allow parts of your code being changed by hooks, you have to use one of these two functions:
You can probably guess which one to use for which type of hook. The difference is, that filters return a value while actions do not. So when using a filter, it looks like this:
$value = apply_filters( 'filter_name', $value, $arg1, $arg2 );
You define the filter name, then you pass the value to be filtered. You can also optionally pass more arguments to the filter, which you can then use in your callback function, to decide on how to change the value.
For an action, it looks pretty much the same. But you won’t save the return value, as the function does not return anything:
do_action( 'action_name', $arg1, $arg2 );
As an action does not change a value, it does not necessarily need a value being passed, so all arguments are optional. Many actions take no values at all, like wp_head for example.
Make hooks form specific
Now that we know how we can add hooks to our code, let’s see how we can make them form specific. In the official Gravity Forms documentation, you only find a page for actions, but without too much explanation. But the modifications you have to do are the same for actions and filters. All you have to do is prefixing the two function with gf_ and passing an array with the hook name and the form ID as the first argument. For filters, it looks like this:
$value = gf_apply_filters( array( 'filter_name' $form_id ), $value, $arg1, $arg2 );
In this example, we would need to have the ID of the form stored in a variable $form_id, but you might get it from $form['id'], $entry['form_id'] or similarly. You just have to make sure you pass it. For an action, the new function call would look like this:
gf_do_action( array( 'action_name' $form_id ), $arg1, $arg2 )
That’s really all you have to do!
Conclusion
When you write add-ons/plugins or custom code for Gravity Forms, it’s always nice to think about parts of your code others might want to change. Providing hooks for those parts can make your code so much more useful. And if you add those hooks, always use the Gravity Forms functions, so the hooks can be targeted specifically for individual forms.