feat(template): implement optional honorifics/titles for Donor name.

[Benunc]

User Story

As a administrator, I want the ability to collect honorifics/titles (Mr./Mrs./Ms./Dr./Major/General/Rev etc) in the event that the organization has use for that data.

Though I don't know of a law or legal requirement for such data to be collected, it's often a client/end customer's request and the designer/developer/implementer is tasked with adding the honorific.

Current Behavior

I currently have to custom code the additional form field or use Form Field Manager and some additional custom code to place the field in the logical spot on the form.

Expected Behavior

I expect to be able to check a box to be able to collect (or require) the honorific.

Possible Solution

1. (not preferred) Add in a filter or action hook within the form itself, and a custom snippet/add-on for adding the honorific field to that hook.
2. (preferred) add in the option to display that field programmatically within the Give core interface.

Tasks

• [ ] mock up field placement
• [ ] ensure that the option defaults to NOT collecting the data

Help Scout Tickets

https://secure.helpscout.net/conversation/562421819/17018/?folderId=848135 https://secure.helpscout.net/conversation/563124009/0/?folderId=672194

[Benunc]

additional context from the second user requesting this feature:

Quote from user

For us it is hard to believe that we are the only or second organisation using Give who needs a salutation field for Mr./Mrs./Dr. The default form for the personal info must be extendable so it is meeting many use cases in many countries. In Fundraising the donor experience it is very important, so if it is required in a country to say "Dear Mr. Smith" the form should be able to collect the salutation info. Besides we use Salesforce as a CRM and there is a salutation field by default. So if we want to send donor infos from Give to Salesforce the Salutation data is always missing. And by that the gender information is missing as well. Not all names are in that way we could easily say if the donor is a woman or a man. Here the salutation is the missing link which helps our fundraisers to write donor letters with a proper salutation. So, you notice that we are not confident with the solution to wait until the developer team will implement our request one day. Actually we think it is not a feature but it belongs to every app who collects donations. Please help us to find a stable solution for our problem, so we can begin to use GiveWP that is a really a great work and plugin!

[slewisma]

FWIW almost every donor management system has either a separate field for Mr/Mrs/Ms/Dr/etc. or two addressee name fields, an informal (Scott Lewis) and a formal (Mr. Scott Lewis). I've got more than a dozen clients using Give now and about half of them would like to have Give collect the correct salutation. As the integrator tying Give to their Donor Management systems, I'd prefer a separate field so I can assemble the formal addressee for those with a field for it and send the separate fields for those that do not.

For donors that care whether you address them formally or not, this is an important field. For others, it is not important. The best way to handle the field is as a donor optional field. If they fill it out, we assume they care how we address them. If they don't, we know they don't care.

[DevinWalker]

Proposed Direction

I have reviewed @slewisma's recommendations as well as @Benunc's and come up with the following functional proposal.

Per Form Settings

There will be a new section within each donation form to customize the donation Name Title Prefix. I chose this title because it's more understandable than Honorific or just Donor Title:

By default it will inherit the global options. If you choose to customize it a repeater field will display with preset options of several common title prefixes: Mr., Mrs., Ms., Miss, and Dr.

Global Options

The "Name Title Prefix" global option will appear under Settings > Display Options > Display:

It will be disabled by default and when enabled the same repeater field as displayed on the per form settings will appear beneath the option.

The Donation Form

When enabled a new dropdown will appear that is not a required field. This field should only display if one or more titles are provided by the admin:

Donation Receipt

If the donor provides a title then they will see it first on the donation receipt:

Emails

If a donor has a title within their donor profile then all emails that are sent out should include this title. That means the {name} field needs to update from just the donor's first name to the title + last name. For instance, if the donor has no title then it will be "John", if they do the tag will display "Mr. Doe".

The description for the {name} field should be updated to:

{name} - The donor's first name or title followed by last name if a name title prefix is provided. For instance, "John" or "Mr. Doe".

The {fullname} tag will also include the prefix if provided. The description for this tag will be updated to:

{fullname} - The donor's full name. This includes the prefix if provided followed by first and last name.

Donor Edit Screen

An admin can update donor's prefixes by clicking edit and they will see a text input which they can customize the prefix to anything they're like.

The donor's prefix will display when viewing the donor's profile page, not in the H1 tag but next to the avatar:

Note: The donor prefix will not display on the donor listing screen

Give API

The donors endpoint needs to include a new title_prefix attribute:

This will enable folks to easily pass the data off using Zapier.

[slewisma]

This works. I can tell you the word "title" is always confusing in this use since it also gets used for job title. I've seen people get it wrong many times when importing data into Donor Management and CRM systems. Combining it with "Prefix" makes it clearer and should suffice. "Salutation prefix" would be even clearer and very accurate as this is the prefix portion of a formal salutation.

[mehul0810]

Tasks

• [x] Add global settings under Settings > Display Options > Display
• [x] Add per form settings with repeater field to provide titles for title prefix
• [x] Add new title prefix field on donation form in front end
• [x] Add new title prefix field on donation detail page
• [x] Add new title prefix field on donor listing page
• [x] Add new title prefix field on donor detail page with edit screen
• [x] Add title prefix in donation receipt
• [x] Add title prefix to email tags used in emails
• [x] Add title prefix in Give API

[mehul0810]

Slack Call Summary

Participants: @mehul0810 @ravinderk Topic: Discussed repeater field implementation Result: We have discussed repeater field implementation and noticed that using multiple select by chosen will be more neat and clean UI for a single title field. We will research on it and wait for @DevinWalker thoughts on implementing Chosen multi-select

[ravinderk]

@DevinWalker As discuss with @mehul0810 I suggest something like this for per form and global setting instead of repeater field:

Code Sample: https://codepen.io/ravinderk/pen/qYZoMx?editors=1010

Let us know what do you think

[DevinWalker]

@ravinderk - it looks pretty good. Let's go that route.

[mehul0810]

Slack Call Summary

Participants: @ravinderk @Sidsector9 @mehul0810 Topic: Discussion about grid implementation in honorifics Result: I'll use manipulate the width of the fields working in a current way and we can implement CSS grid later on when we revamp the form API.

[ravinderk]

@mehul0810 I am finding few issues with this feature

1. Getting notice.

2. As we discussed over call please review the various case of this feature because I found that title prefix field is required even if it is optional in the global setting.

3. Value does not save properly on single form.