When working with Gravity Forms, you may want to display dynamic content after a user submits a form. For example, you might need to:
- Display different content depending on a user’s answer.
- Run a custom PHP function after form submission.
- Display a list of custom posts, documents, or other dynamic data.
- Show the output of an existing shortcode only when a condition is met.
Gravity Forms provides a conditional shortcode for showing content based on submitted field values. However, when you need to run your own PHP function as part of that logic, it can be easier to put the condition directly inside your own shortcode.
In this guide, we’ll use a small custom shortcode to check a Gravity Forms field value and display dynamic content only when the value matches the condition.
1. Understanding the Problem
Gravity Forms includes a conditional shortcode that can show or hide content in confirmation messages and notification emails based on a form field’s value.
For example:
[gravityforms action="conditional" merge_tag="{:3:value}" condition="contains" value="E"]
Some content here
[/gravityforms]
This example displays the enclosed content when the value of field ID 3 contains the letter E.
The conditional shortcode is useful for straightforward display rules. However, it does not execute arbitrary PHP code written inside the shortcode content. If you need to call a custom PHP function and control its output, you need a PHP-based solution.
Also, nested shortcode behavior depends on how the enclosing shortcode processes its content. WordPress supports nested shortcodes when the enclosing shortcode handler processes the content with do_shortcode(). You can read more in the official WordPress Shortcode API documentation.
2. The Output We Want
Suppose your website already has a PHP function that displays a list of useful tools:
<?php
useful_tools_list(
array(
'type' => 'documents',
'desc' => 'true',
)
);
You also have a shortcode that displays the same content:
[useful-tools type="documents" desc="true"]
Now imagine that you want to display this list only when a user selects a particular answer in a Gravity Forms field.
Instead of placing your custom shortcode inside the Gravity Forms conditional shortcode and relying on nested shortcode processing, you can move the condition into your own shortcode.
3. Add the Condition to Your Shortcode
First, update the shortcode usage by adding two attributes:
[useful-tools type="documents" desc="true" merge_tag=" {
:3:value
}
" value="B"]
These additional attributes have specific purposes:
merge_tag: The Gravity Forms merge tag containing the submitted field value.value: The value you want to check for.
In this example, the shortcode should display the tools list only when field ID 3 contains the letter B.
Gravity Forms replaces supported field merge tags with the submitted value when processing confirmation content. It also handles merge tags used in the merge_tag attribute of its conditional shortcode. You can learn more about supported merge tags in the official Gravity Forms Merge Tags Reference.
4. Update the PHP Shortcode Function
Now update your existing useful-tools shortcode callback so it checks the submitted field value before calling your PHP function.
Here is a complete example:
<?php
function geekerhub_useful_tools_shortcode( $atts ) {
$atts = shortcode_atts(
array(
'type' => 'documents',
'desc' => 'true',
'merge_tag' => '',
'value' => '',
),
$atts,
'useful-tools'
);
// Get the submitted field value and expected value.
$field_value = trim( (string) $atts['merge_tag'] );
$expected_value = trim( (string) $atts['value'] );
// Do not display anything if the values do not match.
if (
$field_value === '' ||
$expected_value === '' ||
strpos( $field_value, $expected_value ) === false
) {
return '';
}
// Make sure the custom function exists.
if ( ! function_exists( 'useful_tools_list' ) ) {
return '';
}
// Prepare the arguments for your existing PHP function.
$args = array(
'type' => sanitize_key( $atts['type'] ),
'desc' => 'true' === strtolower( $atts['desc'] )
? 'true'
: 'false',
);
// Return the generated content.
return useful_tools_list( $args );
}
add_shortcode(
'useful-tools',
'geekerhub_useful_tools_shortcode'
);
Important: This example assumes that useful_tools_list() returns its generated HTML as a string. If your existing function prints output directly instead, update it to return the output or capture it with PHP output buffering.
The condition uses strpos(), so it checks whether the submitted field value contains the expected value. If you need an exact match instead, replace the condition with:
if ( $field_value !== $expected_value ) {
return '';
}
For example, an exact match is appropriate when the field should contain only B, while a contains check is useful when the field can return multiple selected values.
5. Understand the Complete Workflow
Once the shortcode is registered, the process is straightforward:
- A visitor fills out and submits the Gravity Forms form.
- Gravity Forms processes the submitted field values.
- The field merge tag in the shortcode attribute is replaced with its submitted value in the confirmation-processing context.
- Your custom shortcode receives the field value and the expected value.
- The PHP callback checks whether the condition is satisfied.
- If the condition matches, the callback runs
useful_tools_list()and returns its output. Otherwise, it returns an empty string.
The important part is that the condition and the PHP function call are handled by your own shortcode. You do not need to put PHP code inside the Gravity Forms confirmation editor.
6. Why Use This Approach?
This approach can be useful when you want to keep the confirmation editor simple while allowing developers to control the output in PHP.
- Centralized logic: The condition and output are handled in one shortcode callback.
- Reusable code: You can use the same shortcode in multiple confirmation messages.
- Editor-friendly: Content editors only need to add shortcode attributes instead of writing PHP.
- Flexible output: The callback can call an existing function to display custom data.
- Easy maintenance: You can update the PHP logic without changing every confirmation message.
7. An Alternative: Use the gform_confirmation Filter
Gravity Forms also provides the gform_confirmation filter, which allows developers to modify a form’s confirmation message using PHP.
This is a good option when the confirmation needs more complex logic or when you want to work directly with the submitted entry and form data.
For example, the filter provides the confirmation message, the submitted entry, and the form object:
<?php
add_filter(
'gform_confirmation',
function ( $confirmation, $form, $entry, $ajax ) {
// Check the submitted value of field ID 3.
$field_value = rgar( $entry, '3' );
if ( 'B' === $field_value ) {
$confirmation .= useful_tools_list(
array(
'type' => 'documents',
'desc' => 'true',
)
);
}
return $confirmation;
},
10,
4
);
This example appends the tools list when field ID 3 has the exact value B. It is a form-level approach, so you should target the appropriate form if the same logic must not run for every form on your website.
For more details, see the official Gravity Forms gform_confirmation documentation.
The trade-off is that more of the confirmation logic lives in PHP rather than in the confirmation editor. If editors need to manage the displayed content themselves, a custom shortcode may be easier to maintain.
8. A Few Things to Check Before Using It
- Use the correct field ID: Make sure
{:3:value}refers to the field you want to check. - Test the returned value: Check whether the field returns a single value or multiple values, especially for checkbox fields.
- Use the right comparison: Choose
strpos()for a contains check or strict comparison for an exact match. - Confirm merge-tag processing: Test the shortcode in the actual Gravity Forms confirmation context. If the callback receives the literal merge tag instead of the submitted value, this approach will not work in that processing context.
- Return output from the callback: WordPress shortcode callbacks should return their output rather than echo it directly.
If you are building reusable WordPress functionality, consider keeping the shortcode in a small custom plugin instead of placing all the code in your theme’s functions.php. This makes the functionality independent of your active theme. You can follow our guide on creating a custom WordPress plugin for a practical starting point.
Final Thoughts
Gravity Forms provides built-in conditional shortcodes for displaying content based on submitted field values. But when you need to call a custom PHP function and control its output, moving the condition into your own shortcode can be a clean alternative.
By passing the field merge tag and expected value as shortcode attributes, your PHP callback can decide whether to display the requested content. This keeps the confirmation editor simple and gives developers control over the dynamic output.
For more WordPress shortcode examples, see our guide to creating a WordPress shortcode to display the number of products.
