Skip to end of metadata
Go to start of metadata

Summary

This is a new feature which allows site administrators to configure and include "Tell a Friend" functionality for Online Contribution and Event Registration pages. Administrators will be able to configure the following elements:

  • Introductory text for Tell a Friend form
  • Thank-you message displayed after form is submitted
  • An optional "get more information" URL to be included in the emails sent to the "friends"

This configuration will be stored in a new table - and linked to a given Online Contribution page or Event form via entity_table/entity_id. This model allows us to extend usage to other interactions (petitiions, profiles, etc.) as needed.

The Tell A Friend form displayed to contributors has:

  • Intro text (admin configured)
  • First, Last Name and Email of "sender" (pre-filled from session)
  • Sender "Message"
  • 3 rows for friends' Names / Emails

On submit, end-users will get a "success" page with a configurable thank-you message.

Each tell-a-friend recipient is saved as a contact record. To facilitate tracking, the contact source is set to "Tall a Friend" + $contibPageTile. Tell-a-friend actions are recorded as "Activity" items - with the donor as the source contact, and the recipients ("friends") as the target contacts.

Schema changes

New table: civicrm_tell_friend

  • id
  • entity_table VARCHAR(64), Which object table is this tell a friend page linked to (civicrm_contribution_page, civicrm_event)
  • entity_id INT, FK to actual linked object (civicrm_contribution.id, civicrm_event.id)
  • title VARCHAR(255), Used for link text to Tell a Friend form, as well as page header and HTML title
  • intro TEXT, Introductory message to contributor or participant displayed on the Tell a Friend form - allows HTML
  • suggested_message TEXT, Suggested message to friends, provided as default on the Tell A Friend form. Text only.
  • general_link VARCHAR(255), URL for general info about the organization - included in the email sent to friends.
  • thankyou_title VARCHAR(255), Text for Tell a Friend thank you page header and HTML title
  • thankyou_text TEXT, Thank you message displayed on success page
  • is_active BOOLEAN

Modify xml/templates/civicrm_add_domain.tpl to add an Activity Type - "Tell a Friend" - to civicrm_option_value data (option_group = activity_type).

Code Structure

Because this functionality will be used by Contribute and Event (and other components at some point) - it should be in it's own class tree - probably CRM/Friend.

Admin (Configuration) Interface

Build a new form to configure Tell A Friend for a given Contribution Page or Event Reg page. The form elements will be the same. We can pass a parameter into the template ($pageType = "contribution" or "registration") - that can be used to make conditional modifications in descriptive / help text.

  • Form is linked from "Configure Contribution Page" (CRM/Contribute/Page/ContributionPageEdit.tpl) after "Thanks and Receipt" row.
  • Form is linked from "Configure Event" (CRM/Event/Page/ManageEventEdit.tpl) - after "Online Registration" row.
  • Form is added to Controller for New Contribution Page AFTER step 4
  • Form is added to Controller for New Event AFTER step 4

Admin Form Elements

NOTE: In order to simplify configuring this feature, we will provide default values (text strings) via setDefaults() in the form code. Of course the text should be ts() wrapped. Defaults are listed with the form fields below.

  • Tell A Friend enabled? - field type=checkbox. When checked, remaining fields are 'shown'. (is_active)
  • Title - field type=text (title)
    • DEFAULT: "Tell A Friend"
  • Introduction - textarea (intro)
    • DEFAULT (contribute): "Help us spread the word and leverage the power of your contribution by telling your friends. Use the space below to personalize your email message - let your friends know why you support us. Then fill in the name(s) and email address(es) and click "Send Your Message".
    • DEFAULT (event): "Help us spread the word about this event. Use the space below to personalize your email message - let your friends know why you're attending. Then fill in the name(s) and email address(es) and click "Send Your Message".
  • Suggested Message - textarea (suggested_message)
    • DEFAULT (contribute): "Thought you might be interested in learning about and helping this organization. I think they do important work."
    • DEFAULT: (event) "Thought you might be interested in checking out this event. I'm planning on attending."
  • Info Page Link - text (general_link)
  • Thank-you Title - text (thankyou_title)
    • DEFAULT: "Thanks for Spreading the Word"
  • Thank-you Message - textarea (thankyou_text)
    • DEFAULT (contribute): "Thanks for telling your friends about us and supporting our efforts. Together we can make a difference."
    • DEFAULT (event): "Thanks for telling spreading the word about this event to your friends."

Form Validation

If is_active = TRUE, then ALL fields are required EXCEPT:

  • Suggested Message
  • Info Page Link

End User (Contributor/Registrant) Interface

This is the form that contributors / event registrants see if they click the "Tell a Friend" link from the Thankyou page in either sequence. The link TO this form should be placed prominently in the Thankyou Page just below the Thankyou_text. The link query string must include entity table and entity id info (so we know which Contrib Page or Event is being "told about". The text for this link is the value in civicrm_tell_friend.title value.

Form Elements

  • HTML <title> and <h2> page title is civicrm_tell_friend.title
  • <div id="intro_text">civicrm_tell_friend.intro</div>
  • Your Name [ first ] [ last ]
    • DEFAULT: Contributor/participant contact first and last name
  • Your Email
    • DEFAULT: Contributor/participant primary email address
  • Message
    • DEFAULT: (from civicrm_tell_friend.suggested_message)
  • Friend's Name(s) and Email Address(es)
    [ first ] [ last ] [ email ]
    [ first ] [ last ] [ email ]
    [ first ] [ last ] [ email ]

Form Validation

Sender name, valid sender email address, message, and at least one row with friend's first, last, email are all required.

Post Process

Post processing tasks are:

  • Insert a Contact record for each "friend".
    • civicrm_contact.source = "Tell a Friend: " + title of associated entity (online contrib page or event)
  • Insert Activity records (one civicrm_activity record and a civicrm_activity_target record for each recipient):
    • source_contact_id = contributor/participant contact.id
    • source_record_id = contribution or participant record id if available, else NULL
    • activity_type_id = id of "Tell a Friend" option value record
    • activity_date = now()
    • subject = "Tell a Friend: " + title of associated entity (online contrib page or event)
    • details = sender's message
    • is_test = passed as action in query string (e.g. action=preview -> is_test = 1)
    • civicrm_activity_target.target_contact_id = friend's contact id
  • Format and send email to each "friend" via built-in SMTP using templates/CRM/Friend/Form/Message templates.
    • Create template set corresponding to those used in Event/Register (Subject.tpl, Message.tpl, PreviewHeader.tpl).
    • Email SUBJECT: "$senderContactFirstName $senderContactLastName wants you to know about $contribPageTitle/$eventTitle"
    • Email REPLY-TO: $senderContactEmailAddress
    • Email FROM: Construct the double-quote delimited FROM Name by parsing the domain from the receipt_from_email and combining it with the sender first and last name (see below). Use the receipt_from_email as the FROM email address.
Email Body (pseudo code)

$senderMessage

if $general_link

  • For more information, visit $general_link

if $contribute

  • To make a contribution, go to: $contributionPageURL
    • $contributionPageURL = civicrm/contribute/transact?id=$contribPageID&reset=1

if $event

  • To find out more about this event, go to :$eventPageURL
    • $eventPageURL = civicrm/event/info?id=$eventID&reset=1
Labels
  • None

Creative Commons License
Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution-Share Alike 3.0 United States Licence.