Hooks & Filters Reference
A complete reference of all WordPress action hooks and filter hooks provided by Product Roadmap Pro. Use these hooks in your theme’s functions.php file or a custom plugin to extend and customize roadmap behavior.
Time to read: 10 minutes
Understanding Hooks
WordPress hooks let developers run custom code at specific points during execution. There are two types:
- Actions run custom code when something happens (e.g., after a vote is submitted)
- Filters modify data before it is used (e.g., change the email recipient)
To use a hook, add code like this to your theme’s functions.php or a custom plugin:
// Action example: run code after a vote
add_action( 'roadmap_vote_submitted', 'my_vote_handler', 10, 2 );
function my_vote_handler( $item_id, $user_id ) {
// Your custom code here
}
// Filter example: modify data
add_filter( 'roadmap_api_format_item', 'my_item_formatter', 10, 2 );
function my_item_formatter( $item_data, $item_id ) {
$item_data['custom_key'] = 'custom_value';
return $item_data;
}Event Action Hooks
These hooks fire when roadmap events occur. Use them to trigger notifications, log activity, or sync with external systems.
roadmapvotesubmitted
Fires when a user votes on a roadmap item.
| Parameter | Type | Description |
|---|---|---|
$item_id | int | The roadmap item post ID |
$user_id | int | The WordPress user ID who voted |
add_action( 'roadmap_vote_submitted', function( $item_id, $user_id ) {
error_log( "User $user_id voted on item $item_id" );
}, 10, 2 );roadmapcommentsubmitted
Fires when a comment is posted on a roadmap item.
| Parameter | Type | Description |
|---|---|---|
$item_id | int | The roadmap item post ID |
$comment_id | int | The WordPress comment ID |
roadmapsuggestionsubmitted
Fires when a logged-in user submits a new roadmap suggestion.
| Parameter | Type | Description |
|---|---|---|
$item_id | int | The newly created roadmap item post ID |
roadmapguestsuggestion_submitted
Fires when a guest (non-logged-in visitor) submits a suggestion.
| Parameter | Type | Description |
|---|---|---|
$suggestion_id | int | The guest suggestion post ID |
roadmapstatuschanged
Fires when a roadmap item’s status changes.
| Parameter | Type | Description |
|---|---|---|
$item_id | int | The roadmap item post ID |
$old_status | string | Previous status slug |
$new_status | string | New status slug |
add_action( 'roadmap_status_changed', function( $item_id, $old_status, $new_status ) {
if ( 'completed' === $new_status ) {
// Send a celebration email or update external tracker
}
}, 10, 3 );roadmapitemsmerged
Fires after two roadmap items are merged.
| Parameter | Type | Description |
|---|---|---|
$source_id | int | The item that was merged (now trashed) |
$target_id | int | The item that received the merged data |
Analytics Tracking Hooks
These hooks fire during analytics event recording.
roadmapitemvoted
Fires when the analytics system records a vote event. Different from roadmapvotesubmitted — this fires specifically for analytics tracking.
roadmapitemcomment_added
Fires when the analytics system records a comment event.
roadmapitemstatus_changed
Fires when the analytics system records a status change event.
roadmapitemviewed
Fires when a roadmap item page view is recorded for analytics.
Admin UI Hooks
roadmapsettingstabs
Fires when rendering the settings page tabs. Use this to add your own settings tab.
roadmapsettingstab_content
Fires when rendering settings tab content. Use this to output your custom tab’s form fields.
roadmapdashboardafter_sections
Fires after the main dashboard sections are rendered. Use this to add custom dashboard widgets.
roadmapaftermain_content
Fires after the main roadmap content on the frontend. Use this to append content below the roadmap display.
Data Filter Hooks
These filters let you modify data before it is used or displayed.
roadmapapiformat_item
Modify the data structure for a roadmap item in API responses.
| Parameter | Type | Description |
|---|---|---|
$item_data | array | The formatted item data array |
$item_id | int | The roadmap item post ID |
Returns: Modified $item_data array.
add_filter( 'roadmap_api_format_item', function( $item_data, $item_id ) {
// Add a custom calculated field
$item_data['priority_score'] = get_post_meta( $item_id, '_priority', true ) ?: 0;
return $item_data;
}, 20, 2 );This filter runs at priority 20 by default for custom fields. Use a higher priority number if you need your modifications to run after the built-in custom fields are added.
roadmapapiquery_args
Modify the WP_Query arguments used when fetching roadmap items via the API.
| Parameter | Type | Description |
|---|---|---|
$args | array | WP_Query arguments array |
$request | WPRESTRequest | The incoming REST request |
Returns: Modified $args array.
add_filter( 'roadmap_api_query_args', function( $args, $request ) {
// Only show items from the last 90 days
$args['date_query'] = array(
array( 'after' => '90 days ago' ),
);
return $args;
}, 10, 2 );roadmapapifilterbyproduct
Modify query arguments when filtering items by product.
| Parameter | Type | Description |
|---|---|---|
$args | array | WP_Query arguments |
$product_filter | string | Product slug or comma-separated slugs |
Returns: Modified $args array.
roadmapapisettings
Modify the settings object returned by the API.
| Parameter | Type | Description |
|---|---|---|
$settings | array | Settings key-value pairs |
Returns: Modified $settings array.
roadmapapichangelog_args
Modify the query arguments for changelog API requests.
| Parameter | Type | Description |
|---|---|---|
$args | array | WP_Query arguments for changelog |
$request | WPRESTRequest | The incoming REST request |
Returns: Modified $args array.
Shortcode Filters
roadmapshortcodeatts
Modify the shortcode attributes before they are processed.
| Parameter | Type | Description |
|---|---|---|
$atts | array | Parsed shortcode attributes |
Returns: Modified $atts array.
roadmapshortcodedata
Modify the data passed to the shortcode template.
| Parameter | Type | Description |
|---|---|---|
$data | array | Template data array |
$atts | array | Shortcode attributes |
Returns: Modified $data array.
roadmapavailabletemplates
Register additional display templates.
| Parameter | Type | Description |
|---|---|---|
$templates | array | Available template slugs and labels |
Returns: Modified $templates array.
roadmapchangelogshortcode_data
Modify the data passed to the changelog shortcode template.
| Parameter | Type | Description |
|---|---|---|
$data | array | Changelog template data |
$atts | array | Shortcode attributes |
Returns: Modified $data array.
Email & Notification Filters
roadmapnotificationemail
Change the recipient email address for notifications.
| Parameter | Type | Description |
|---|---|---|
$email | string | The recipient email address |
$item_id | int | The roadmap item post ID |
Returns: Modified email address string.
add_filter( 'roadmap_notification_email', function( $email, $item_id ) {
$product = get_the_terms( $item_id, 'roadmap_product' );
if ( $product && 'mobile-app' === $product[0]->slug ) {
return 'mobile-team@yoursite.com';
}
return $email;
}, 10, 2 );roadmapemailsubject
Modify the email subject line.
| Parameter | Type | Description |
|---|---|---|
$subject | string | The email subject |
$event_type | string | Type of event (vote, comment, suggestion, status_change) |
$item_id | int | The roadmap item post ID |
Returns: Modified subject string.
roadmapemailmessage
Modify the email body content.
| Parameter | Type | Description |
|---|---|---|
$message | string | The email body |
$event_type | string | Type of event |
$item_id | int | The roadmap item post ID |
Returns: Modified message string.
roadmapdigestcontent
Modify the digest email content before sending.
| Parameter | Type | Description |
|---|---|---|
$content | string | The digest email body |
$period | string | The digest period (daily or weekly) |
Returns: Modified content string.
Settings Filters
roadmapsettingsform_tabs
Add custom tabs to the settings form.
| Parameter | Type | Description |
|---|---|---|
$tabs | array | Array of tab slugs and labels |
Returns: Modified $tabs array.
roadmapitemmeta_fields
Register additional meta fields for roadmap items.
| Parameter | Type | Description |
|---|---|---|
$meta_fields | array | Array of meta field definitions |
Returns: Modified $meta_fields array.
roadmapguestuser_ip
Modify the detected IP address for guest voting and suggestions. Useful when your site runs behind a trusted proxy like Cloudflare or a load balancer.
| Parameter | Type | Description |
|---|---|---|
$ip | string | The detected IP address from REMOTE_ADDR |
Returns: Modified IP address string.
add_filter( 'roadmap_guest_user_ip', function( $ip ) {
// Trust Cloudflare's CF-Connecting-IP header
if ( ! empty( $_SERVER['HTTP_CF_CONNECTING_IP'] ) ) {
return sanitize_text_field( $_SERVER['HTTP_CF_CONNECTING_IP'] );
}
return $ip;
} );Lifecycle Hooks
These hooks fire during plugin initialization and are useful for addons or custom integrations.
roadmappluginloaded
Fires after the free plugin finishes loading all its classes. The Pro addon initializes itself on this hook.
add_action( 'roadmap_plugin_loaded', function() {
// Safe to interact with all roadmap classes here
} );roadmapregisterapi_routes
Fires when the free plugin registers its REST API routes. Use this to add custom routes under the same roadmap/v1 namespace.
| Parameter | Type | Description |
|---|---|---|
$namespace | string | The REST API namespace (roadmap/v1) |
add_action( 'roadmap_register_api_routes', function( $namespace ) {
register_rest_route( $namespace, '/my-custom-endpoint', array(
'methods' => 'GET',
'callback' => 'my_custom_handler',
) );
} );roadmapenqueueassets
Fires when the free plugin enqueues its frontend assets. Use this to enqueue additional scripts or styles alongside the roadmap.
roadmapsettingsupdated
Fires after roadmap settings are saved via the REST API.
| Parameter | Type | Description |
|---|---|---|
$settings | array | The updated settings array |
Gutenberg Block Filters
roadmapproblock_attributes
Modify the available attributes for the Gutenberg block.
| Parameter | Type | Description |
|---|---|---|
$attributes | array | Block attribute definitions |
Returns: Modified $attributes array.
roadmapproblock_output
Modify the rendered output of the Gutenberg block.
| Parameter | Type | Description |
|---|---|---|
$output | string | The rendered block HTML |
$attributes | array | The block’s attribute values |
Returns: Modified $output string.
Next Steps
- REST API Reference — Complete endpoint documentation
- Customization Guide — Common customization patterns
- Webhooks & Integrations — Connect to external services
← REST API Reference | Customization Guide →