Givewp: feat(shortcode): add `[give_totals]` shortcode

[mathetos]

Issue Overview

User wants to be able to show the progress of a form dynamically in text only, or sometimes as a progress bar. This is particularly helpful when you have several forms that are each part of a larger project within the organization.

For example a homeless shelter might have 4 different forms, but they are all part of their "Spring Fundraising Campaign". If they wanted to show how much they've raised for that campaign, a shortcode like this would be really useful.

@Benunc has already started in this direction with this snippet:
https://github.com/WordImpress/Give-Snippet-Library/blob/46846070b7cec12247a5f641506e7e8df1189355/custom-shortcodes/total-earnings-shortcode.php

But there are several important elements that I think it would need in order to be good in Give Core.

1. All Forms the multi_id attribute should be able to take either a comma-separated list of unique form ids (like it does currently) or if set to all or 0 it would show the progress of ALL forms on the site.
2. Categories and Tags you should be able to display the total of all forms in a category or a tag
3. Display Style -- there should be a new attribute called display_style which takes either text or progress_bar are arguments. "Text" would only output the total as plain-text. "Progress" would show our Give Goal progress bar and total but of course be the total of all forms along with the goal of all those forms together.

[kevinwhoffman]

Looks like @Benunc has a good start on the snippet. Here are some suggestions that could simplify the number of attributes required.

Replace form_id and multi_id with ids

This one ids attribute could handle all use cases without the need for both form_id and multi_id.

• 0 = all forms (default setting)
• positive integer = single form
• array = multiple forms

Benefits

• Reduces total number of attributes required.
• Removes the need for conflict detection between form_id and multi_id.
• This is similar to how WordPress core handles attachment IDs in the [gallery] shortcode, so it is in line with WP conventions.

Replace 3 message_* attributes with message

One message attribute could replace the three separate attributes currently required to compose a message:

Current (3 message atts)

[givetotal message_before="Hey! We've raised " message_between=" of the " message_after=" we are trying to raise for this campaign!" total="10000"]

Proposed (1 message att)

[givetotal message="Hey! We've raised %1$s of the %2$s we are trying to raise for this campaign!" total="10000"]

Output would look something like this:

printf( esc_html( $message), $total, $total_goal );
// Hey! We've raised $500 of the $10,000 we are trying to raise for this campaign!

Benefits

• Reduces total number of attributes required.
• Improves flexibility of the message since current $total and $total_goal can be rearranged in the message.

Add progress_bar instead of display_style

Users may want to display the progress bar _with_ the text message, so we can give them the option to display only the progress bar, only the message, or both together depending on whether each attribute has been defined by the user.

Summary

Here's my proposed list default attributes combining Ben's existing snippet, Matt's suggestions, and my own suggestions above:

'total_goal'   => 0, // integer
'ids'          => 0, // integer|array
'cats'         => 0, // integer|array
'tags'         => 0, // integer|array
'message'      => '', // string
'link'         => '', // URL
'link_text'    => 'Donate Now', // string,
'progress_bar' => true // boolean

[Benunc]

@kevinwhoffman I really like all of those changes. can you make modifications to the existing snippet with those changes? And I worry about users who are already using this shortcode, how will we ensure that adding this to core doesn't break their implementations?

[mathetos]

@Benunc In order to be consistent with our existing shortcode formatting, we call this one give_totals

[Benunc]

This is a frequently (relatively) requested feature. Would be handy to have implemented. Can this be put in a milestone?

[Benunc]

ANother followup here. Have another user that I am sending the old shortcode to.

[DevinWalker]

@jaydeeprami please take this one on

[jaydeeprami]

@DevinWalker and @mathetos,

I have started working on it and have a below queries for the same:

1) 'progress_bar' => true // boolean: If Progress bar set as a True then we have to show text along with progress bar. if set false then only need to show text. Please confirm.

2) As per @mathetos comment:

Display Style -- there should be a new attribute called display_style which takes either text or progress_bar are arguments. "Text" would only output the total as plain-text. "Progress" would show our Give Goal progress bar and total but of course be the total of all forms along with the goal of all those forms together.

=> As I have discussed this with @ravinderk, We have to show each progress bar separately for each form. Currently in Give Core, we can output Goal progress bar for each form through this function give_show_goal_progress( $form_id, $args); where we can only pass one Form ID.

so we can not show the progress of all form's total along with the goal of all those forms.

3) In Give Short Code generator, We can only select one Form ID in the current list box. I have checked Mult select HTML element but it's not working so Do we need to create a Multiselect option for the same in Core?

@DevinWalker Please let me know your thoughts on the same.

[mathetos]

@jaydeeprami
This is a new shortcode that is intended to show the Total amount of several forms regardless of whether they have goals enabled or not. See the original snippet mention in the issue above as a reference.

We would need a way to output the progress bar markup without reference to one specific form.

The shortcode also sets the total goal itself, the goal amount is not pulled from any particular form, again, reference the original snippet as an example.

[DevinWalker]

@jaydeeprami please ping me when you come online to discuss.

[jaydeeprami]

Thanks @mathetos , I understood. Please see below screenshot with text and Progress bar.

[mathetos]

@jaydeeprami Yes, that looks awesome.

I took a look at the code you committed, and I don't see the support for the 'progress_bar' => true/false per @kevinwhoffman comment above. I do think that some users will want to show the progress bar, while others will simply want the text alone. I think the markup could get a little complicated if we take these factors into mind:

• Progress bar == true/false
• If text only, then display as a <div> or inline so it can be placed within an existing paragraph of text like so: <p>Our campaign has been going for a long time already. [give_totals multi_id="7,8,9"]

I think progress bar true/false is important to have. The text only as div or inline is bonus, it would be nice, but perhaps not totally necessary, users might never use that option. @Benunc in your experience, how to users typically use this shortcode snippet already? As a block of text, or within an existing paragraph or both?

@DevinWalker Maybe you have concluding thoughts to wrap this up?

[jaydeeprami]

I have discussed with @DevinWalker on Call and He has suggested below changes:

1) Add Information paragraph from the @mathetos Comment:

This is a new shortcode that is intended to show the Total amount of several forms regardless of whether they have goals enabled or not.

• See the Mockup:

2) Allow Admin to Choose Multiple IDs from the ShortCode Generator for the Donation Forms, Category, and Tags:
=> For that, We have to change in ShortCode Generator API to support this.

Also, @mathetos, I have done for the Progress Bar as well.

Please check here:
https://github.com/jaydeeprami/Give/blob/issue/1472/includes/shortcodes.php#L602-L605

As per @kevinwhoffman Comment, If Progress Bar set as a true then it will display along with Progress Bar and Text. Otherwise, it only shows Text.

3) Used template tag {total} and {total_goal} in message to replace with actual amount:
https://github.com/jaydeeprami/Give/blob/issue/1472/includes/shortcodes.php#L508

=> We will add a Text/Textarea in ShortCode generator to modify that message from the Backend.

[DevinWalker]

1. @jaydeeprami thanks for the mockup. The description should be:

This shortcode shows the total amount raised towards a custom goal for one or several forms regardless of whether they have goals enabled or not.

1. Yes, please extend shortcode API to support this.

a. Make sure true is the default for the progress bar option.

1. I think a text area would be best for this since it's going to be multilines.

[DevinWalker]

We just need to ensure that the shortcode inserter has an easy way to select multiple forms for this new shortcode before this one is wrapped up.

[mathetos]

@DevinWalker Feedback from a customer: Can we make sure this new shortcode does NOT reflect the Fees, similarly to how our Goals already work currently. The snippet that this all started from currently includes the Fees:
https://github.com/WordImpress/Give-Snippet-Library/blob/master/custom-shortcodes/total-earnings-shortcode.php

[DevinWalker]

@Sidsector9

To close out this issue please:

• [ ] Limit the width of the modal so it's not redonkulously wide:

• [ ] Create a new field for the chosen2 dropdown so that it's multiselect functional within the shortcode inserter. See https://codepen.io/creativekinetix/pen/pydLyx

• [x] Address Matt's concern with Fee Recovery above to ensure it's not pulling fees within the singular or combined goals.

• [x] Fully and thoroughly test the functionality and do a code review making improvements along the way.

• [x] Verify code is ready for release and submit PR.

[Sidsector9]

Slack Call Summary

Participants: @Sidsector9, @ravinderk
Topic: Convert Listbox to ComboBox
Result: Requires more research whether WordPress supports ComboBox for TinyMCE

[Sidsector9]

Slack Call Summary

Participants: @Sidsector9, @jaydeeprami
Topic: Convert Listbox to ComboBox and Jaydeep's research
Result: Jaydeep already invested a good amount of time in this figuring out ways to implement multi-select box, he and I both have reached the same conclusion that WordPress's version of TinyMCE API does not support Multi-select fields.

@DevinWalker as conveyed to you in out chat.

[DevinWalker]

The entire point of the shortcode is to be able to display one or combine _multiple_ donation forms as a singular goal. We need to figure out a resolution to the inability to select multiple donation forms within the modal window that displays before this is closed out.

[DevinWalker]

Like the guys said it's not possible within TinyMCE to add a multi-select dropdown or checkbox. So, in order to get this through the gates I changed the single form select a text area that can have comma separated form IDs which is compatible with the shortcode.

I couldn't do anything about the width.