1. Customize
  2. Tutorials
  3. Creating a custom event related to a specific post

Creating a custom event related to a specific post

Some GamiPress events are related to be achieved by just perform the described action to a specific post. This events (named specific events) will show the attached post field on the requirements UI.

Important: The Creating a custom event tutorial is a must-read article before start this tutorial.

Registering a specific event

The first step is register a custom event to become a selectable item on the available events dropdown displayed on the requirements UI.

For this, you will need to hook to the gamipress_activity_triggers filter as the following code shows:

function my_prefix_custom_register_specific_activity_triggers( $triggers ) {

    // The array key will be the group label
    $triggers['My Custom Specific Events'] = array(
        // Every event of this group is formed with:
        // 'specific_event_that_will_be_triggered' => 'Event Label'
        'my_prefix_custom_specific_event' => __( 'Custom specific event label', 'gamipress' ),

        // Also, you can add as many events as you want
        // 'my_prefix_another_custom_specific_event' => __( 'Another custom specific event label', 'gamipress' ),
        // 'my_prefix_super_custom_specific_event' => __( 'Super custom specific event label', 'gamipress' ),
    );

    return $triggers;

}
add_filter( 'gamipress_activity_triggers', 'my_prefix_custom_register_specific_activity_triggers' );

Next, you need to hook to the gamipress_specific_activity_triggers to let GamiPress know that this event is specific to a post.

Also, you need define the post types that the attached post field of the requirements UI should filter:

function my_prefix_custom_specific_activity_triggers( $specific_triggers ) {

    // Every specific event here needs to be defined as:
    // 'specific_event_that_will_be_triggered' => array of post types
    $specific_triggers['my_prefix_custom_specific_event'] = array( 'post', 'page', 'other-post-type' );

    return $specific_triggers;

}
add_filter( 'gamipress_specific_activity_triggers', 'my_prefix_custom_specific_activity_triggers' );

Finally, you need to hook to the gamipress_specific_activity_trigger_label to define the label pattern that GamiPress will when auto-generates the requirement label.

function my_prefix_specific_activity_trigger_label( $specific_trigger_labels ) {

    // %s will be replaced with the post title
    // Choosing the page "Sample Page" will show "Specific event for Sample Page" as label
    $specific_trigger_labels['my_prefix_custom_specific_event'] = __( 'Specific event for %s', 'gamipress' );

    return $specific_trigger_labels;

}
add_filter( 'gamipress_specific_activity_trigger_label', 'my_prefix_specific_activity_trigger_label' );

Listening to the user action and let it know to GamiPress

This section is exactly the same as the example provided on the Creating a custom event tutorial.

The unique difference is, when working with specific events, we need to pass the specific_id parameter to the code>gamipress_trigger_event() function.

function my_prefix_custom_specific_listener( $args ) {

    // Call to the gamipress_trigger_event() function to let know GamiPress this event was happened
    // GamiPress will check if there is something to award automatically
    gamipress_trigger_event( array(
        // Mandatory data, the event triggered, the user ID to be awarded and specific ID
        'event' => 'my_prefix_custom_specific_event',
        'user_id' => get_current_user_id(),
        'specific_id' => get_the_ID()

        // Also, you can add any extra parameters you want
        // They will be passed too on any hook inside the GamiPress awards engine
        // 'date' => date( 'Y-m-d H:i:s' ),
        // 'custom_param' => 'custom_value',
    ) );

}
// The listener should be hooked to the desired action through the WordPress function add_action()
add_action( 'action_we_want_to_hook', 'my_prefix_custom_specific_listener' );

Full template to register specific events

The following snippet is the full template that you can use to register your own specific events to being used through the requirements UI.

function my_prefix_custom_register_specific_activity_triggers( $triggers ) {

    // The array key will be the group label
    $triggers['My Custom Specific Events'] = array(
        // Every event of this group is formed with:
        // 'specific_event_that_will_be_triggered' => 'Event Label'
        'my_prefix_custom_specific_event' => __( 'Custom specific event label', 'gamipress' ),

        // Also, you can add as many events as you want
        // 'my_prefix_another_custom_specific_event' => __( 'Another custom specific event label', 'gamipress' ),
        // 'my_prefix_super_custom_specific_event' => __( 'Super custom specific event label', 'gamipress' ),
    );

    return $triggers;

}
add_filter( 'gamipress_activity_triggers', 'my_prefix_custom_register_specific_activity_triggers' );

function my_prefix_custom_specific_activity_triggers( $specific_triggers ) {

    // Every specific event here needs to be defined as:
    // 'specific_event_that_will_be_triggered' => array of post types
    $specific_triggers['my_prefix_custom_specific_event'] = array( 'post', 'page', 'other-post-type' );

    return $specific_triggers;

}
add_filter( 'gamipress_specific_activity_triggers', 'my_prefix_custom_specific_activity_triggers' );

function my_prefix_specific_activity_trigger_label( $specific_trigger_labels ) {

    // %s will be replaced with the post title
    // Choosing the page "Sample Page" will show "Specific event for Sample Page" as label
    $specific_trigger_labels['my_prefix_custom_specific_event'] = __( 'Specific event for %s', 'gamipress' );

    return $specific_trigger_labels;

}
add_filter( 'gamipress_specific_activity_trigger_label', 'my_prefix_specific_activity_trigger_label' );

function my_prefix_custom_specific_listener( $args ) {

    // Call to the gamipress_trigger_event() function to let know GamiPress this event was happened
    // GamiPress will check if there is something to award automatically
    gamipress_trigger_event( array(
        // Mandatory data, the event triggered, the user ID to be awarded and specific ID
        'event' => 'my_prefix_custom_specific_event',
        'user_id' => get_current_user_id(),
        'specific_id' => get_the_ID()

        // Also, you can add any extra parameters you want
        // They will be passed too on any hook inside the GamiPress awards engine
        // 'date' => date( 'Y-m-d H:i:s' ),
        // 'custom_param' => 'custom_value',
    ) );

}
// The listener should be hooked to the desired action through the WordPress function add_action()
add_action( 'action_we_want_to_hook', 'my_prefix_custom_specific_listener' );

A real world example

Let’s to see a real world example based on the “purchase a specific product” event provided on GamiPress – WooCommerce Integration.

function my_prefix_register_specific_triggers_for_purchase_a_product( $triggers ) {

    $triggers['My Custom Specific Purchase Events'] = array(
        // Register the event my_prefix_custom_specific_purchase_event
        'my_prefix_custom_specific_purchase_event' => __( 'Purchase a specific product', 'gamipress' ),
    );

    return $triggers;

}
add_filter( 'gamipress_activity_triggers', 'my_prefix_register_specific_triggers_for_purchase_a_product' );

function my_prefix_specific_triggers_for_purchase_a_product( $specific_triggers ) {

    // Set 'my_prefix_custom_specific_purchase_event' as specific event that requires the 'product' post type
    $specific_triggers['my_prefix_custom_specific_purchase_event'] = array( 'product' );

    return $specific_triggers;

}
add_filter( 'gamipress_specific_activity_triggers', 'my_prefix_specific_triggers_for_purchase_a_product' );

function my_prefix_specific_label_for_purchase_a_product( $specific_trigger_labels ) {

    // %s will be replaced with the product title
    $specific_trigger_labels['my_prefix_custom_specific_purchase_event'] = __( 'Purchase the %s product', 'gamipress' );

    // GamiPress automatically will use this pattern for auto-generate the requirement label
    // Some examples with "Purchase the %s product" label:
    // Step example using the product "T-shirt": Purchase the T-shirt product 2 times
    // Points award example using the product "CD Album": 10 points for purchase the CD Album product  5 times

    return $specific_trigger_labels;

}
add_filter( 'gamipress_specific_activity_trigger_label', 'my_prefix_specific_label_for_purchase_a_product' );

function my_prefix_specific_listener_for_purchase_a_product( $order_id ) {

    $order = wc_get_order( $order_id );

    foreach ( $order->get_items() as $item ) {

        // Call to gamipress_trigger_event() on each product purchased
        gamipress_trigger_event( array(
            'event' => 'my_prefix_custom_specific_purchase_event', // Set our custom purchase event
            'user_id' => $order->user_id, // User that will be awarded is the one who made the order
            'specific_id' => $item->get_product_id(), // Specific ID, here is the product ID

            // Add any extra parameters you want
            // In this example we passed the order item object and the order object itself
            'item' => $item,
            'order' => $order,
        ) );

    }

}
// The safe way to check if an user has perform a purchase is when an order payment is set to completed
// So let's hook the 'woocommerce_payment_complete' action
add_action( 'woocommerce_payment_complete', 'my_prefix_specific_listener_for_purchase_a_product' );

More examples

Almost every GamiPress add-on provides new events related to custom functionalities, like content sharing events provided by Social Share add-on, or events related to specific plugin actions, like form submissions provided by the Ninja Forms Integration add-on.

Some of the events will use GamiPress default functionalities and other will add new fields to the requirements UI and extra checks to the awards engine, so feel free to check their code to develop complex events.

Was this article helpful to you? Yes No

How can we help?