Docs update for 0.4.4 release

mecachisenros · Oct 8, 2018 · 0964d3d · 0964d3d
1 parent 3a17edf
commit 0964d3d
Show file tree

Hide file tree

Showing 35 changed files with 156 additions and 17 deletions.
diff --git a/README.md b/README.md
@@ -12,6 +12,8 @@ The Caldera Forms CiviCRM plugin contains a set of form processors that interact
 * Map Custom Fields data
 * Add Relationships to each contact
 * Create Activities on form submission
+* Select Email Template for notification (requires [Email API Extension](https://civicrm.org/extensions/e-mail-api))
+* Open a Case on form submission
 * Checksum support to auto-populate form with URLs like **example.com/some-page?cid={contact.contact_id}&{contact.checksum}**
 * Add Memberships (CiviMember)
 * Add Contributions with Line Items (for live transactions a [Caldera Forms Payment add-on](https://calderaforms.com/caldera-forms-add-ons/#/payment) is needed)
@@ -31,9 +33,10 @@ To use this plugin, the following is needed:
 * Get an [overview of Caldera Forms](/docs/overview.md)
 * Setup [CiviCRM Processors](/docs/processors.md) on your form
 * Use [Custom Fields](/docs/custom-fields.md)
+* [Examples](/docs/examples.md)
 
 ### Contribute
 
 Please help improve this plugin by using the extension issue queue to report any troubles and to make requests for feature improvements. The issue queue is here: https://github.com/mecachisenros/caldera-forms-civicrm/issues
 
-Issues submitted to the issue queue will be addressed based on time and interest. If you are a [developer contributions](/docs/dev/contribute.md) are welcome.
+Issues submitted to the issue queue will be addressed based on time and interest. If you are a developer contributions are welcome.
diff --git a/docs/custom-fields.md b/docs/custom-fields.md
@@ -8,6 +8,7 @@ When adding new fields to your Caldera form there are two new options available
 
 * CiviCRM Country
 * CiviCRM State/Provice
+* Contact Reference
 
 ![Caldera CiviCRM Special Fields Types](./images/caldera-civicrm-special-fields.jpg)
 
@@ -17,17 +18,53 @@ The default Country and State/Province used in the field will be taken from the
 
 ## Custom Data with Select fields
 
-You can create custom fields in CiviCRM that are:
+You can create custom fields in CiviCRM that are become available in the Caldera Forms integration. Custom Fields can be mapped on the [Contact](./processors.md#contact) and [Activity](./processors.md#activity) processors using [Magic Tags](./overview.md#magic-tags) field options.
+
+The field types that currently can be used are:
 
 * Dropdown Select
 * Checkbox
 * Radio
-* Date Picker
+* Date Picker (also works with `Single Text Field`, HTML 5 option `Date`)
+
+If the field doesn't exist in CiviCRM, start by creating the new custom fields in CiviCRM before adding the fields to the Caldera Form.
+
+There are several data entities available in the Auto Populate or Bulk/Insert Presets. Some of the data options available are:
+
+* Custom Fields
+* Communication Preferences and Contact fields
+* Price Set Line Items
+* Payment Method Types
+
+#### Auto Populate
+
+With the Auto Populate option it provides a quick way to add CiviCRM data fields to a Caldera Form. There are no Caldera side changes or editing options, so it allows for forms to be setup more quickly. 
+
+![Auto Populate Data Sources](./images/cfc-auto-pupulate-data-sources.png)
+
+**Admin side display**
 
-And have then select those options when you setup your Caldera Form. Start by adding a new field to the form and giving it a name. Then scroll down to the Bulk Insert/Preset option and select the field creating in CiviCRM you want to use and click Insert Options.
+![Auto Populate admin side field](./images/cfc-auto-pupulate-admin.png)
+**Front-end form side display**
+
+![Auto Populate front-end form field](./images/cfc-auto-pupulate-fe-form.png)
+
+#### Bulk/Insert Presets
+
+With using the Bulk/Insert Preset options you can bring CiviCRM data into a from and then edit within Caldera to tweak. What all **needs** to remain the same is the *Value* in Caldera, which matches the database ID in CiviCRM.
+
+![Data Sources for Bulk Insert/Preset](./images/cfc-bulk-insert-data-source-presets.png)
+
+Start by adding a new field to the form and giving it a name. Then scroll down to the Bulk Insert/Preset option and select the field creating in CiviCRM you want to use and click Insert Options.
 
 ![Bulk Insert/Preset](./images/caldera-select-bulk-insert.png)
 
+***Note:** The option you decide to use may be based on whether you need to use the field data values as conditions in a processor. For example if you have multiple member types and based on that selection provide specific options to each member type, it's best to use the Bulk/Insert Preset option, since those fields will be available for selection on conditions.*
+
 When using the Date Picker you must use the same settings that are in **Administer > Localization > Date Formats** in the **Date Input Fields** section. And adjusted by customized in **Administer > Customize Data and Screens > Date Preferences**
 
 ![Date Picker Field Format](./images/caldera-civicrm-date-format.jpg)
+
+The Single Line Text fields has an HTML 5 Date option that can also be used.
+
+![Date HTML5 field](./images/cfc-single-text-html5-date.png)
diff --git a/docs/examples.md b/docs/examples.md
@@ -0,0 +1,6 @@
+# Examples using Caldera Forms Integration
+
+There are many ways processors can be used to add/update information in CiviCRM using Caldera Forms integration. In this section we will outline examples to help understand how you can use this integration.
+
+* Newsletter or similar [subscriptions](./examples/subscriptions.md)
+* [Contact Form](./examples/contactform.md)
diff --git a/docs/examples/contactform.md b/docs/examples/contactform.md
@@ -0,0 +1,13 @@
+# Contact Forms
+
+## Simple Contact Form
+The contact form on your website could record an activity about this communication in CiviCRM. For this creating a custom Activity Type called Communication is useful. A simple contact form may look like this:
+
+![Simple Contact Form](../images/simple-contact-form.png)
+
+To get this information into CiviCRM you will need to use the [Contact](./processors.md#contact) and [Activity](./processors.md#activity) processors. The Contact processor will set the contat type, dedupe rules and the contact details in the Contact Standard Fields section. And the Activity processor will record the Subject and Message.
+
+ ![Contact Form Communication Activity](../images/activity-type-contact-form.png)
+
+ The activity source will be the contact who filled in the form and activity date can be set with Date magic tag option and show.
+
diff --git a/docs/examples/subscriptions.md b/docs/examples/subscriptions.md
@@ -0,0 +1,39 @@
+# Subscription Examples
+
+## Simple Subscription Form
+
+A one field form that asks for their email address and adds them to the Newsletter Subscriber group.
+
+![Simple Subscribe Email Form](../images/simple-subscribe-form.png)
+
+This form just requires one field to be added and the contact processor to be configured. Check to Process group for this contact option. After setting the Contact Type and Dedupe rules, in the Contact Standard fields add the email and select the group they should be added too.
+
+![Subscriber Contact Processor Setting](../images/subscriber-newsletter.png)
+
+![Add subscriber to group](../images/subscriber-email-group.png)
+
+## Multiple Subscription Groups
+
+If your organization has multiple subscription options, where folks can select what options they receive, providing a checkboxes for them to make selections so they can be added to the right mailing group. Setup a form with the contact and subscription options set.
+
+![Subscription Options](../images/select-subscriptions.png)
+
+Then go to the Processor and add the Contact Processor. In this case we are only going to use the contact processor for contact details in the Contact Standard Fields section and use separate group processors for each selection. This way the contact will only be added to the subscription group if they select the option.
+
+To add the contact to the right group we will use the [Group processor](../processors.md#group) and use [conditions settings](../overview.md#conditions) in each processor to manage when each is used. In this example we have three subscriptions, so three group processors should be added selecting the group they should be added too and when then setting the condition for when this processor should be used.
+
+![Subscriber Set Group](../images/subscribers-set-group.png)
+
+![Subscriber Set Group Condition](../images/subscribers-set-group-condition.png)
+
+When complete, in this example, there should be four processors used, one for the contact and a group processor for each selection.
+
+## Multiple Subscription Custom Fields
+
+Another way to do this is using custom fields and then creating smart groups to create the mailing groups. To do this setup a Subscriptions custom field in CiviCRM using checkboxed and use the [Bulk/Insert Options](../custom-fields.md#bulkinsert-preset) to populate the Caldera Form.
+
+![Bulk/Insert Subscription](../images/subscribers-custom-field-options.png)
+
+Then go to Processors and only one processor is needed to add the magic tags to the Contact fields in the Contact Standard Fields and the Subscriptions in the Contact Custom Fields.
+
+![Subscription Custom Fields](../images/contact-processor-custom-field-subscriptions.png)
diff --git a/docs/images/activity-type-contact-form.png b/docs/images/activity-type-contact-form.png
diff --git a/docs/images/caldera-civicrm-special-fields.jpg b/docs/images/caldera-civicrm-special-fields.jpg
diff --git a/docs/images/caldera-field-display-condition.jpg b/docs/images/caldera-field-display-condition.jpg
diff --git a/docs/images/cfc-auto-pupulate-admin.png b/docs/images/cfc-auto-pupulate-admin.png
diff --git a/docs/images/cfc-auto-pupulate-data-sources.png b/docs/images/cfc-auto-pupulate-data-sources.png
diff --git a/docs/images/cfc-auto-pupulate-fe-form.png b/docs/images/cfc-auto-pupulate-fe-form.png
diff --git a/docs/images/cfc-bulk-insert-data-source-presets.png b/docs/images/cfc-bulk-insert-data-source-presets.png
diff --git a/docs/images/cfc-line-item-processor.png b/docs/images/cfc-line-item-processor.png
diff --git a/docs/images/cfc-membership-processor.png b/docs/images/cfc-membership-processor.png
diff --git a/docs/images/cfc-open-case-processor.png b/docs/images/cfc-open-case-processor.png
diff --git a/docs/images/cfc-order-processor.png b/docs/images/cfc-order-processor.png
diff --git a/docs/images/cfc-send-email-processor-email-api.png b/docs/images/cfc-send-email-processor-email-api.png
diff --git a/docs/images/cfc-single-text-html5-date.png b/docs/images/cfc-single-text-html5-date.png
diff --git a/docs/images/civicrm-contribution-processor.jpg b/docs/images/civicrm-contribution-processor.jpg
diff --git a/docs/images/civicrm-line-item-donation-processor.jpg b/docs/images/civicrm-line-item-donation-processor.jpg
diff --git a/docs/images/civicrm-line-item-processor.jpg b/docs/images/civicrm-line-item-processor.jpg
diff --git a/docs/images/civicrm-line-item-with-membership-processor.jpg b/docs/images/civicrm-line-item-with-membership-processor.jpg
diff --git a/docs/images/civicrm-order-processor.jpg b/docs/images/civicrm-order-processor.jpg
diff --git a/docs/images/civicrm-phone-processor.jpg b/docs/images/civicrm-phone-processor.jpg
diff --git a/docs/images/contact-processor-custom-field-subscriptions.png b/docs/images/contact-processor-custom-field-subscriptions.png
diff --git a/docs/images/select-subscriptions.png b/docs/images/select-subscriptions.png
diff --git a/docs/images/simple-contact-form.png b/docs/images/simple-contact-form.png
diff --git a/docs/images/simple-subscribe-form.png b/docs/images/simple-subscribe-form.png
diff --git a/docs/images/subscriber-email-group.png b/docs/images/subscriber-email-group.png
diff --git a/docs/images/subscriber-newsletter.png b/docs/images/subscriber-newsletter.png
diff --git a/docs/images/subscribers-custom-field-options.png b/docs/images/subscribers-custom-field-options.png
diff --git a/docs/images/subscribers-set-group-condition.png b/docs/images/subscribers-set-group-condition.png
diff --git a/docs/images/subscribers-set-group.png b/docs/images/subscribers-set-group.png
diff --git a/docs/overview.md b/docs/overview.md
@@ -36,7 +36,7 @@ Conditions are used to manage the logic used for each processor. Without adding
 
 Variables are dynamic form values that have use in either other areas of your form or in different parts of your website. Use a static variable to hold data that you might need to use as a magic tag in some other part of the Caldera Forms Builder. Use a passback variable to send data to the next HTTP request as query variables when using the redirect proccesor. For example you can send fields from one form to another.
 
-The variables are set in the first form simiarl to this:
+The variables are set in the first form similar to this:
 
 ![Caldera Variables Set](./images/caldera-variables-set.jpg)
 

diff --git a/docs/processors.md b/docs/processors.md
@@ -2,7 +2,7 @@
 
 The following Processors are added when the CiviCRM Caldera Forms plugin is activated. Multiple processors of each type can be used to accomplish for each Caldera form.
 
-### Contact entity
+### Contact
 
 This processor is the one that needs to be used before others can be used, as it defines that contact the information is being applied to in CiviCRM. Rquired fields for using this processor are Contact Type and Dedupe Rule.
 
@@ -18,62 +18,103 @@ The contact processor has some of the processors outlined below built in, so tha
 
 However, keep in mind that if some of the fields are not required separate processors may need to be used with condition set, see [overview of Caldera Forms](./overview.md).
 
-### Activity entity
+### Activity
 
 The Activity Processor provides the ability to record an activity for one more contacts on form submission. The activities available are all the activities available in CiviCRM and custom fields for those Activity Types can also be processed.
 
 ![CiviCRM Activity Processor](./images/civicrm-activity-processor.jpg)
 
-### Relationship entity
+### Relationships
 
 The Relationship processor provides a way to assign a relationship to two contacts on form submission. The Relationship Types are selected from the ones avaialbe in your CiviCRM instance.
 
 ![CiviCRM Relationships Processor](./images/civicrm-relationship-processor.jpg)
 
-### Group entity
+### Groups
 
 The Group processor allows for a contact to be added to a group on form submission.
 
 ![CiviCRM Group Processor](./images/civicrm-group-processor.jpg)
 
-### Tag entity
+### Tags
 
 The Tag processor allows for a tag to be added to a contact on on form submission.
 
 ![CiviCRM Tag Processor](./images/civicrm-tag-processor.jpg)
 
-### Address entity
+### Address
 
 The Address processor provides the ability for a specific address type to be added or update for that contact in CiviCRM.
 
 ![CiviCRM Address Processor](./images/civicrm-address-processor.jpg)
 
-### Email entity
+### Email
 
 The Email processor provides the ability for a specific email address type to be added or update for that contact in CiviCRM.
 
 ![CiviCRM Email Processor](./images/civicrm-email-processor.jpg)
 
-### Phone entity
+### Phone
 
-The Phone processor provides the ability for a specific phone number and type to be added or update for that contact in CiviCRM.
+The Phone processor provides the ability for a specific phone number and type to be added or update for that contact in CiviCRM, you'll need to select the Contact to link it too, the Phone Location Type, Phone Type and the Phone field at a minimum.
 
 ![CiviCRM Phone Processor](./images/civicrm-phone-processor.jpg)
 
-### Note entity
+### Note
 
 The Note processor allows for a subject and note to be added to a contact on on form submission.
 
 ![CiviCRM Note Processor](./images/civicrm-note-processor.jpg)
 
-### Website entity
+### Website
 
 The Website processor provides the ability for a specific URL and type to be added or update for that contact in CiviCRM.
 
 ![CiviCRM Website Processor](./images/civicrm-website-processor.jpg)
 
-### IM (Instant Messenger) entity
+### IM (Instant Messenger)
 
 The IM processor provides the ability for a specific IM and type to be added or update for that contact in CiviCRM.
 
 ![CiviCRM IM (Instant Messenger) Processor](./images/civicrm-im-processor.jpg)
+
+### Send Email 
+
+If you install and enable the [E-mail API Extension](https://civicrm.org/extensions/e-mail-api) the Send Email processor becomes available and you can select from CiviCRM Message Templates a email notification that can be sent on form submission. 
+
+![CFC Send Email with Email API extension](./images/cfc-send-email-processor-email-api.png)
+
+### Case
+
+When CiviCase is enabled a Case processor is available that allows for a case to be opened on form submission. 
+
+![CFC Open a Case](./images/cfc-open-case-processor.png)
+
+
+### Contributions
+
+The CiviCRM Contribution provides a way to use a Caldera Forms calculation fields and payment processor and send contribution details to CiviCRM. 
+
+![CiviCRM Contribution Processor](./images/civicrm-contribution-processor.jpg)
+
+### Memberships
+
+The CiviCRM Membership provides the ability to register and renew memberships. By using this processor you can renew existing memberships as is done using a contribution page, or create new memberships at each renewal. 
+
+![CFC Membership Processor](./images/cfc-membership-processor.png)
+
+
+### Price Set Line Items
+
+The CiviCRM Line Item connects Caldera form fields to Line Items in a price set to record transaction details. When using the CiviCRM Membership Processor you can connect the contributions details to the membership record. Once the membership processor is setup a unique variable ID is created and available for selection in the Line Item processor to connect these two entities. 
+
+![CiviCRM Line Item with Memberhips Processor](./images/civicrm-line-item-with-membership-processor.jpg)
+
+![CiviCRM Line Item Donation Processor](./images/civicrm-line-item-donation-processor.jpg)
+
+### Orders
+
+The CiviCRM Order processor is where you can connect everything into one contribution record, by mapping all line items into one order.
+
+![CiviCRM Order Processor](./images/cfc-order-processor.png)
+