INSTRUCTIONS FOR WEBFORM CIVICRM INTEGRATION


BASICS:

Most forms all start the same way: Name, Address, Phone Number, Email, etc. Creating those same fields over and over again can be tedious, not to mention then getting said data into your CiviCRM database. This module takes care of all that for you.


WHAT IT DOES:

-Auto create just about any CiviCRM contact field (including custom fields!)
-Auto-fill forms for logged in users.
-Auto-fill for anonymous users too if you send them a personalized link through CiviMail.
-Automatically log activities when users fill out your form.
-It uses your CiviCRM default strict deduping rule to decide whether to update an existing contact or create a new one when the form is submitted by an anonymous user.
-It imposes no restrictions on how you style, rename, nest, or edit your CiviCRM fields; you may do anything with them that you can do with any other webform field.


HOW TO USE IT

-Enable the module.
-Create a new webform (or go to edit an existing one).
-Click on the CiviCRM tab.
-Enable the fields you like, and optionally choose introduction text and activity settings.
-Your selected fields will be automatically created for you.
-Customize the webform settings for your new fields however you wish.
-If you wish to delete a field, you may do so through the standard webform interface, the same as any other webform field.


RETROFITTING AN EXISTING WEBFORM

You can pretty easily start recording CiviCRM contacts even for an existing webform. This falls into two scenarios:

1) You don't have any contact info fields on the form yet (name, address, etc). That's easy, just go to the CiviCRM tab of your webform, check the boxes, and the new fields will be created for you.

2) You already have contact info fields on your form. If people have already been using this form, you don't want to delete those fields because you'd lose their data for all prior submissions! Instead, you can get civicrm_webform to start processing those existing fields by changing their field keys to the ones understood by civicrm_webform. For example, click to edit the "First Name" field in your webform, and then change the field key to "civicrm_first_name". Be sure to enable civicrm on that webform (which you may safely do before, during, or after renaming your field keys). For a complete list of field keys, see the function webform_civicrm_get_fields() in the webform_civicrm_utils.inc file. They are the keys of the $fields array. Or, if you don't like reading code, just create yourself a dummy webform, have webform_civicrm auto-create the fields you want, then copy and paste those field keys into your other form.


WILL CONTACTS AND ACTIVITIES BE CREATED RETROACTIVELY IF I ENABLE THIS MODULE ON AN EXISTING WEBFORM?

No. That would require some sort of batch update script, which is not part of this module.


USING SPECIAL LINKS IN CIVIMAIL

CiviMail has the ability to generate links that have a unique "key" for each person it sends a message to. This module can read those keys and automatically pre-fill the webform for people who come to it via that link. Your constituents will thank you for not making them fill out their name, address, etc when you already know it. To send out personalized links to your form in CiviMail, simply copy and paste the provided line of code on the CiviCRM tab of your webform into your HTML CiviMail message. It looks like this:
<a href="http://mysite.org/myform?cid={contact.contact_id}&{contact.checksum}">Click here</a>

You may, of course, change the link text (Click here) to whatever you like.

Note, if you are sending a text (not rich-text/HTML) message from CiviMail, do not paste in the entire line of code, just the part inside the quotes. Text message example:
Please click this link to go to my form: http://mysite.org/myform?cid={contact.contact_id}&{contact.checksum}

The personalized links generated by CiviMail are valid for 1 week.