How to Use the WPBakery Shortcode Mapper with GiveWP Shortcodes

Using GiveWP and the WPBakery Page builder together, you need some extra steps to make GiveWP shortcodes work. The WPBakery Shortcode Mapper tool can aid with that process. This document walks you though why and how to make GiveWP work alongside WPBakery.

Why is This Process Necessary?

It’s an exciting time for the WordPress open source project. The block-based editor that comes with WordPress starting in 5.0 makes creating content more user-friendly. The goal is to move from shortcodes to creating everything with blocks. That way, users customize content in real time within the editor.

GiveWP is compatible with the new block-based editor. The plugin includes backward compatibility to accommodate users still using the classic editor. The classic editor has a shortcode generator to create correctly-formatted shortcodes easily. The new block-based editor has several GiveWP blocks, making adding form-based content simple.

Some sites use page builders like WPBakery which don’t rely on the classic editor or the new block-based editor. While most builders support shortcodes, users have to write and format shortcodes manually. Especially for folks new to shortcodes, this can be a daunting task. The method outlined in this document allows any user to embed GiveWP shortcode elements into their website.

How to Use The WPBakery Shortcode Mapper with GiveWP

GiveWP provides multiple unique elements, like the Donor Wall and Form Grid, using shortcodes. To show them on a page or post using the WPBakery editor, you first need to map the shortcode attributes correctly. This makes it so that the WPBakery editor can output the element. This is all handled “behind the scenes” by the WPBakery builder’s Shortcode Mapper.

The process involves these steps:

Create a reference shortcode using the classic editor
Use the WPBakery Shortcode Mapper to map fields to shortcode attributes
Add a custom shortcode to your posts and pages

Create a Reference Shortcode

Shortcodes use individual bits of information called “attributes” to create the shortcode. Some of those attributes are required, while others are optional.

Before mapping the shortcode attributes to their respective fields, create a reference shortcode. This acts as a “cheat sheet,” providing WPBakery with everything necessary to create the shortcode.

For this step, you’ll need to temporarily disable the Gutenberg block-based editor. There are several plugins in the Plugin Directory to help with that. Disable Gutenberg completely disables all mention of Gutenberg. The Classic Editor plugin has some calls to test out the Gutenberg editor.

With the block-based editor disabled, create a new draft of a page at Pages > Add New.

Then use the shortcode generator to create a reference shortcode. When you use the shortcode generator, it only uses the required values, unless you select a value in the dropdown for each attribute. This results in a shortcode with only required values.

For example, the Donation Form shortcode only requires the form ID. If you select that shortcode and pick a form while changing nothing else, the shortcode would look like this: [[give_form id=”43”]].

While that embeds a valid form, it’ doesn’t give you all of the possible values that can be configured, which is what you need to correctly map all possible attributes to WPBakery fields.

To list all of the shortcode attributes, select something for each field, as seen in the below image. Note that some fields only display based on the value selected for other fields. For the Donation Form shortcode, the Continue Button text is only displayed for reveal, modal, or button mode displays.

That created shortcode will serve as a reference for the Shortcode Mapper.

Use The WPBakery Shortcode Mapper to Create a Custom Shortcode

Navigate to WPBakery > Shortcode Mapper, and click the “Map Shortcode” button. Paste in the full shortcode from your draft in step one above, and parse the shortcode.

This populates a list of the attributes included in the GiveWP [give_form] shortcode. By default, the parser attempts to guess the best type of field to make each one, but it is not 100% accurate. Each of the parameters in the shortcode (except the form ID and the Continue Button Text) only accept selected types of input. As a result, it makes the most sense to restrict the input to those exact bits of data, using the dropdown field type.

Here are the options you should give each dropdown:

Parameter: id

Field type: textfield
Default Value: 1
Description: Enter the ID of the Donation Form to embed. This is a required field.

Parameter: show_title

Field type: drop down
Default Value: true,false
Description: To display the Form Title, select “true.” To hide the Form Title, select “false.”

Parameter: show_goal

Field type: drop down
Default Value: true,false
Description: To show the form goal, select “true.” Only forms with goals enabled will display the goal.

Parameter: show_content

Field type: drop down
Default Value: none, above, below
Description: If the form has content, this option lets you show it above or below the form fields, or not at all.

Parameter: display_style

Field type: drop down
Default Value: onpage, modal, button, reveal
Description: This determines whether to display the form on the page, as a button, as a modal, or revealed on click.

Parameter: continue_button_title

Field type: textfield
Default Value: Donate Now
Description: For reveal, button, and modal display modes, this option sets the text for the continue button. It will not affect “onpage” display mode.

Map those fields in exactly that way to prevent users from entering invalid text and running into errors. You can leave the Heading values the same or change them to suit your specific purposes.

Add a custom shortcode to your posts and pages

After saving your settings, you can access the shortcode from the WPBakery editor. Just go to the the “My Shortcodes” section of the “Add element” interface. You can also search for it by typing “GiveWP” into the search bar.

Select that element, and add it to the content in the correct spot. Then select the form ID and any other element settings that you configured. The only tricky part in adding the element to the page is correctly identifying the form ID in question. To find your form’s ID, you can hover over the “copy shortcode” button on the Forms table at Donations > All Forms.

Reference materials for additional GiveWP Shortcodes:

The other GiveWP shortcodes necessary to create a site are [give_receipt] and [donation_history].

`[give_receipt]`

Param Name: price

Field type: dropdown
Default Value: true, false
Description: To display the donation amount, select “true.” To hide it, select “false”

Param Name: donor

Field type: dropdown
Default Value: true, false
Description: To display the Donor Name, select “true.” To hide the Form Title, select “false.”

Param Name: date

Field type: dropdown
Default Value: true, false
Description: To show the donation date, select “true.”

Param Name: payment_method

Field type: dropdown
Default Value: true, false
Description: To show the payment method, select “true.”

Param Name: payment_id

Field type: dropdown
Default Value: true, false
Description: To show the donation ID, select “true.”

Param Name: company_name

Field type: dropdown
Default Value: true, false
Description: To show the company name, select “true.”

`[donation_history]`

Unlike the other examples, the donation history shortcode does not have any additional parameters. It can be added without them. You’ll still want to have the shortcode mapper parse the shortcode, but you don’t need to add any parameters. Add [donation_history] to the shortcode mapper, and save the changes.

Conclusion

WordPress sites using page builders like WPBakery have a bit of extra work to do to make add GiveWP elements to posts and pages. But with the WPBakery Shortcode Mapper, all editors and authors on the site can add GiveWP shortcodes confidently.