Conditional shortcodes for field connections (Themer)
Besides field connection shortcodes, which return the contents of field connections as text strings, Beaver Themer has conditional shortcodes, which display custom text if the field connection shortcode does or does not return content.
Conditional shortcode syntax
The basic conditional shortcode syntax is as follows. Note that the conditional has a beginning and end tag.
[wpbb-if some-field-connection] my-custom-text [/wpbb-if]
As of Beaver Themer 1.0.3, you can add an optional
[wpbb-else] clause, like the following. Notice this tag doesn't require an end tag.
[wpbb-if some-field-connection] my-custom-text [wpbb-else] my-other-custom-text [/wpbb-if]
The conditional checks whether
some-field-connection returns content as text (required for field connection shortcodes) and if it does, the custom text is inserted. Custom text can include HTML markup and shortcodes. The exception is that you can't nest conditional
[wpbb-if] shortcodes within each other.
To add the logical operator NOT before the field connection in the conditional, use the exclamation mark
!, as shown in this code, paraphrased as "If some-field-connection doesn't return any content, display the text 'Field connection content doesn't exist.'"
[wpbb-if !some-field connection] Field connection content doesn't exist. [/wpbb-if]
1 Featured image in Posts module layout
Themer conditional shortcodes are often used in custom Posts module layouts, to alter the layout or to incorporate custom fields. When you choose a custom layout for the Posts module, you'll see a conditional shortcode to test whether the post featured image has content, as follows:
[wpbb-if post:featured_image] <div class="fl-post-image"> [wpbb post:featured_image size="large" display="tag" linked="yes"] </div> [/wpbb-if]
- Any Posts module layout settings disappear when you switch to custom layout. The markup in the initial custom layout displays the post featured image above the post content, even if you had set it to the left or right on the Layout tab.
- What's returned by the
post:featured_imageshortcode is the URL wrapped in HTML, so you don't need an
<img>tag in the custom layout markup to display the featured image. This is different from the behavior of custom image fields. See the next section.
2 Use an Advanced Custom Field connection in a custom Posts layout
The following code shows an example of using an Advanced Custom Field of type Image instead of the featured image in a custom layout in a Posts module. The name of the ACF field is
corp-photo, so the Posts module custom layout includes the following code to display the ACF image when there is one.
[wpbb-if post:acf type="image" name="corp-photo"] <div class="fl-post-image"> <img src="[wpbb post:acf type='image' name='corp-photo' image_size='thumbnail']"> </div> [/wpbb-if]
Note that in this case the custom image field shortcode returns a URL, so an
<img> tag is added to wrap the image.
Here's the same example with a
[wpbb-else] clause to display text when no image is available.
[wpbb-if post:acf type="image" name="corp-photo"] <div class="fl-post-image"> <img src="[wpbb post:acf type='image' name='corp-photo' image_size='thumbnail']"> </div> [wpbb-else] <div> <p>No image available</p> </div> [/wpbb-if]
This code results in the message "No image available" when there is no ACF image to display, as shown in the following screenshot. You can position that message by adding CSS rules.
3 Add an optional WordPress custom field in a Singular layout
Suppose you have an optional WordPress custom field called
content-advisory, which has values such as "Strong language" or "Violence." When this custom field does contain an advisory, you want to display it in a Singular Themer layout as a heading with the prefix "Content advisory," as shown in the following screenshot.
If you use a Heading module to display this line, the code in the Heading field would look like the following.
[wpbb-if post:custom_field key='content-advisory'] Content advisory: [wpbb post:custom_field key='content-advisory'] [/wpbb-if]
Or you could use an HTML module and provide the HTML markup as well as the field connection shortcode:
[wpbb-if post:custom_field key='content-advisory'] <h3 style="text-align:center;"> Content advisory: [wpbb post:custom_field key='content-advisory']</h3> [/wpbb-if]
For more information about using WordPress custom fields with Beaver Themer, see the Related Article below.
4 Add a Pods custom field and separator only when there's content
One Themer user reported that he was building a Singular Themer layout for a custom post type, and he had a number of PODS custom fields. He used conditional shortcode to display the content of each Pods field only when the field had content, with a horizontal separator below it. Here's an example of conditional shortcode that could be used for each custom field. You could place this code in an HTML module in your Themer layout and add custom CSS to style the
[wpbb-if post:pods_display field='intro_text'] <div class="my-custom-class"> [wpbb post:pods_display field='intro_text'] </div> <hr> [/wpbb-if]
5 Use conditional shortcode to troubleshoot field connection shortcode
If your field connection shortcode isn't displaying the content way you think it should, the first question to ask is whether the field connection shortcode is returning a value and what value it's returning. To test this, use an HTML module with conditional shortcode testing the field connection and a status messages.
For example, the following test code in two HTML modules in a Singular Themer layout shows the difference between what is returned by the featured image shortcode and ACF image field shortcode.
Test featured image shortcode:
Does this post have a featured image? [wpbb-if post:featured_image] Yes: [wpbb post:featured_image size='thumbnail' display='tag' align='default' linked='yes'] [/wpbb-if]
You can change the
display='tag' parameter to
alt to return different values for the featured image.
Test ACF image field shortcode:
Does this post have a corporate photo? [wpbb-if post:acf type="image" name="corp-photo"] Yes: [wpbb post:acf type="image" name="corp-photo"] [/wpbb-if]
The ACF image field shortcode parameters do not have as many options as the featured image, so it only returns the image URL.
Here are the results of these two tests as displayed by the HTML modules when published. The test for featured image shows the image, whereas the test for the ACF image field, shows the URL.