Conditional shortcodes for field connections (Themer)

There are conditional shortcodes, which display content only if the shortcode does or does not return content. The conditional uses the wpbb-if shortcode, and it always returns a boolean exists/doesn't exist value.

Conditional shortcode syntax

The basic conditional shortcode syntax is as follows.

[wpbb-if some-field connection]Some content here[/wpbb-if]

The conditional checks whether the shortcode returns content, and the content between the tags is added if the conditional is true.

Here's a real example:

[wpbb-if post:featured_image] Has a featured image. [/wpbb-if]

In other words, if a featured image exists for that post, display "Has a featured image."

To check whether a shortcode does NOT return content, add the   ! symbol before the property, as in the examples below:

[wpbb-if !some-field connection] Some content here [/wpbb-if]

Real example:

[wpbb-if !post:featured_image] Doesn't have a featured image. 
[/wpbb-if]

In other words, if the post doesn't have a featured image, display the text "Doesn't have a featured image."

You can use shortcodes that have parameters, such as a custom field:

[wpbb-if post:custom_field key="my_field"] Has a custom field with the key my_field. [/wpbb-if]

[wpbb-if !post:custom_field key="my_field"] Doesn't have a custom field with the key my_field. [/wpbb-if]

If you're using a field created with the Advanced Custom field plugin, you'd use the attributes from that field. The following code shows an example of inserting an ACF of type  Image only if the field contains an image.

[wpbb-if post:acf type="image" name="corp-photo"]
    <div>
       <img src="[wpbb post:acf type='image'
            name='corp-photo' image_size='thumbnail']"/>
    </div>
[/wpbb-if]

Examples

When would you want to add content based on whether the field connection has a value or not? Here are some examples.

  • You want to add some text before or after a custom field value, but only when the custom field is not empty. 
    For example, you have a custom field for content warnings such as "Strong language" or "violence," and you want to display the text "Content advisory"" before the field content, as shown in the following screenshot.
  • You want to display a message when a custom field doesn't have a value.
    For example, if a image field doesn't return a URL from the shortcode, you could display the text "No image available."
  • In a custom post layout in a Posts module, you want to use HTML markup for a field connection shortcode only when the shortcode returns content.
    For example, you might want your <div> markup for the featured image to be used only when the post has a featured image.

Note: You don't need to use conditional shortcodes for the field connection shortcodes themselves. If they do not return content, nothing is displayed. Use the conditional shortcode only to add text or markup based on whether the target field has a value.

Code example 1: Add text before a field value

Suppose you have a custom field called content-advisory that has values such as "Strong language" or "Violence." You want to display this content in a Heading module with the prefix "Content advisory," as shown in the screenshot above.

The following code adds the text "Content advisory:" before the custom field content, but only when that custom field has a value.

[wpbb-if post:custom_field key='content-advisory']Content advisory: [/wpbb-if]
[wpbb post:custom_field key='content-advisory']

You can see that the text "Content advisory" is set inside a conditional so it appears only when the specified custom field has a value. The custom field shortcode itself does not need to be inside the conditional, because it won't appear if it doesn't have a value.

Code example 2: Insert markup to display an Advanced Custom Field image.

The following code shows an example of inserting an ACF of type Image only if the field contains an image.

[wpbb-if post:acf type="image" name="corp-photo"]    
    <div class="fl-post-feed-image">    	
        <img src="[wpbb post:acf type='image'                
            name='corp-photo' image_size='thumbnail']"/>   
     </div>
[/wpbb-if]

Even though the ACF field has the data type Image, the shortcode returns the the value as a URL, so you have to provide the markup to use the URL as an attribute in an <img> tag.

Troubleshooting conditional shortcode

If your conditional shortcode isn't working the way you think it should, the most important question to ask is whether the field connection shortcode is returning a value. To test this, use an HTML module with both the field connection shortcode to display the field contents and the conditional shortcode with text to describe the expected outcome, as in the following example.

To add content only when the shortcode doesn't return content, add the  ! symbol before the property, as shown below:

[Post:featured_image][wpbb-if post:featured_image] Has a featured image. [/wpbb-if]
[wpbb-if !post:custom_field key="my_field"] Doesn't have a custom field with the key my_field. [/wpbb-if]