Merge pull request #40 from mecachisenros/0.4

0.4

README.md

@@ -4,28 +4,34 @@ A WordPress plugin that integrates the [Caldera Forms](https://wordpress.org/plu
 
 The Caldera Forms CiviCRM plugin contains a set of form processors that interact with CiviCRM's API to retrieve, create and update data in CiviCRM. With this plugin, you can create responsive forms that expose CiviCRM fields and entities like Activities, Relationships, Tags, Groups and more.
 
+### Features
+
+* Add up to **10 Contacts** on the same form
+* Auto-populate form if the user is logged in
+* Define Contact Type: Organization, Individual, Household, and Custom Contact Subtypes
+* Map Custom Fields data
+* Add Relationships to each contact
+* Create Activities on form submission
+* Checksum support to auto-populate form with URLs like **example.com/support?cid={contact.contact_id}&{contact.checksum}**
+
+### Requirements
+
+To use this plugin, the following is needed:
+
+* WordPress
+* CiviCRM 4.6.x or 4.7.x
+* [Caldera Forms](https://wordpress.org/plugins/caldera-forms/ "Caldera Forms WordPress plugin") to be installed
+
 *WARNING* This plugin is at a very early stage of development (bleeding edge alpha) and is currently being tested with CiviCRM versions 4.6.x and 4.7.x.
 
-Currently supports:
-
-### + Contact entity
-* Up to **10 Contact** prcessors on the same form
-* **Auto-populate form** if the user is logged in
-* **Checksum support** to auto-populate form with URLs like **example.com/support?cid={contact.contact_id}&{contact.checksum}**
-* **Contact Type**: Organization, Individual, Household, Custom Type
-* **Contact Subtypes**
-* **Custom Fields**
-
-### + Activity entity
-### + Relationship entity
-### + Group entity
-### + Tag entity
-### + Address entity
-### + Email entity
-### + Phone entity
-### + Note entity
-### + Website entity
-### + IM (Instant Messenger) entity
-
-### Coming soon
-+ Request a feature
+### Using Caldera Forms CiviCRM
+
+* Get an [overview of Caldera Forms](/docs/overview.md)
+* Setup [CiviCRM Processors](/docs/processors.md) on you form
+* Use [Custom Fields](/docs/custom-fields.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.

caldera-forms-civicrm.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: Caldera Forms CiviCRM
  * Description: CiviCRM integration for Caldera Forms.
- * Version: 0.3
+ * Version: 0.4
  * Author: Andrei Mondoc
  * Author URI: https://github.com/mecachisenros
  * Plugin URI: https://github.com/mecachisenros/caldera-forms-civicrm
@@ -15,7 +15,7 @@
  *
  * @since 0.1
  */
-define( 'CF_CIVICRM_INTEGRATION_VER', '0.3' );
+define( 'CF_CIVICRM_INTEGRATION_VER', '0.4' );
 define( 'CF_CIVICRM_INTEGRATION_URL', plugin_dir_url( __FILE__ ) );
 define( 'CF_CIVICRM_INTEGRATION_PATH', plugin_dir_path( __FILE__ ) );
 
@@ -64,6 +64,15 @@ class CiviCRM_Caldera_Forms {
 	 */
 	public static $templates;
 
+	/**
+	 * The form management object.
+	 *
+	 * @since 0.4
+	 * @access public
+	 * @var object $templates The form management object
+	 */
+	public static $forms;
+
 	/**
 	 * Returns a single instance of this object when called.
 	 *
@@ -110,7 +119,7 @@ public static function instance() {
 	private function check_dependencies() {
 
 		// Bail if Caldera Forms is not available
-		if ( ! defined( 'CFCORE_VER' ) ) return false;
+		if ( ! defined( 'CFCORE_VER' ) && version_compare( CFCORE_VER, '1.5', '>=' ) ) return false;
 
 		// Bail if CiviCRM is not available
 		if ( ! function_exists( 'civi_wp' ) ) return false;
@@ -143,6 +152,9 @@ private function include_files() {
 		// Include template management class
 		include CF_CIVICRM_INTEGRATION_PATH . 'includes/class-civicrm-caldera-forms-templates.php';
 
+		// Include forms management class
+		include CF_CIVICRM_INTEGRATION_PATH . 'includes/class-civicrm-caldera-forms-forms.php';
+
 	}
 
 	/**
@@ -161,6 +173,9 @@ private function setup_objects() {
 		// init templates manager
 		self::$templates = new CiviCRM_Caldera_Forms_Templates;
 
+		// init forms manager
+		self::$forms = new CiviCRM_Caldera_Forms_Forms;
+
 	}
 
 	/**

docs/custom-fields.md

@@ -0,0 +1,33 @@
+# Data fields
+
+There are a couple  of options to be aware of when syncing data to CiviCRM. This plugin adds two Special Field Types and integrates the Select Bulk/Insert to Custom Fields created in CiviCRM
+
+## Special fields
+
+When adding new fields to your Caldera form there are two new options available in the Special field type:
+
+* CiviCRM Country
+* CiviCRM State/Provice
+
+![Caldera CiviCRM Special Fields Types](./images/caldera-civicrm-special-fields.jpg)
+
+Similar to using a Profile form in CiviCRM, the Country field should be place prior to the State/Provide field so the correct options are displayed.
+
+The default Country and State/Province used in the field will be taken from the settings in **Administer > Localization > Languages, Currency, Locations**
+
+## Custom Data with Select fields
+
+You can create custom fields in CiviCRM that are:
+
+* Dropdown Select
+* Checkbox
+* Radio
+* Date Picker
+
+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.
+
+![Bulk Insert/Preset](./images/caldera-select-bulk-insert.png)
+
+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)

docs/dev/contribute.md

@@ -0,0 +1 @@
+TODO

docs/index.md

@@ -0,0 +1 @@
+../README.md

docs/overview.md

@@ -0,0 +1,47 @@
+### Caldera Forms Overview
+
+Caldera Forms uses Processors to extend what can be done with forms. By installing and activating the Caldera Forms CiviCRM plugin new processors are added to allow information from forms to be added or updated in CiviCRM.
+
+![Caldera Forms CiviCRM Processors](./images/caldera-forms-civicrm-processors.jpg)
+
+Select and configure the processors needed for each form to send the wanted information to their CiviCRM contact record.
+
+_To get acquainted with Caldera Forms check out their [getting started guide](https://calderaforms.com/getting-started/ "Caldera Forms Getting Started Guide")._
+
+#### Settings
+
+Settings are outlined in more detail in each processor see [CiviCRM Processors](./processors.md)
+
+It is important to also note that processors initiate in order from top to bottom as listed underneath the “Add Processor” button and that you can drag-and-drop the order of the processors in the list.
+
+#### Magic Tags
+
+Magic Tags are what are used to map or sync the data fields between Caldera Forms and CiviCRM. Every field in a form has a magic tag formed with the field’s slug, which is similar the field name all lower case and with _ for the spaces. That is used with % on each side to use the magic tag. For example, if you have a Email Address field in your form with the slug `email_address` and magic tag `%email_address%`.
+
+![Caldera Forms Magic Tags](./images/contact-processor-magic-tags.jpg)
+
+_For more information about this read [Using Magic Tags In Caldera Forms](https://calderaforms.com/doc/using-magic-tags-caldera-forms/ "Using Magic Tags In Caldera Forms") documentation._
+
+#### Conditions
+
+Fields in a form can be displayed based on conditions set. This is managed in the Conditions menu tab of that form.
+
+![Caldera Forms Field Display Conditions](./images/caldera-field-display-condition.jpg)
+
+Conditions are used to manage the logic used for each processor. Without adding any settings, it runs the processor each time the form is submitted. If all fields are required, no Conditions need to be set. If some fields are not required, use the Conditions to set when that processor should be used. Not doing this will cause the form to not submit. For example if you require first name, last name and email, but not phone number you would use a separate processor with a condition.
+
+![Caldera Forms Use Processor Conditions](./images/caldera-use-processor-condition.jpg)
+
+#### Variables
+
+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:
+
+![Caldera Variables Set](./images/caldera-variables-set.jpg)
+
+And received in the second form using hidden fields like this:
+
+![Caldera Variables Get](./images/caldera-variables-receive.jpg)
+
+_For more information about this read [Getting Started: Using Form Variables](https://calderaforms.com/doc/using-form-variables/ "Getting Started: Using Form Variables") documentation._

docs/processors.md

@@ -0,0 +1,79 @@
+# CiviCRM Processors
+
+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
+
+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.
+
+![CiviCRM Contact Processor](./images/caldera-contact-processor.jpg)
+
+Magic Tags are used to map the fields created in the Caldera form with fields in CiviCRM, see [overview of Caldera Forms](./overview.md) for more detail on Magic Tags.
+
+![Caldera Forms Magic Tags](./images/contact-processor-magic-tags.jpg)
+
+The contact processor has some of the processors outlined below built in, so that more information about the contact can be mapped in single processor. By checking more options, need selections appear.
+
+![CiviCRM Contact additional Checked Processors](./images/caldera-contact-checked-selections.jpg)
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+The Phone processor provides the ability for a specific phone number and type to be added or update for that contact in CiviCRM.
+
+![CiviCRM Phone Processor](./images/civicrm-phone-processor.jpg)
+
+### Note entity
+
+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
+
+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
+
+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)

fields/civicrm_state/field.php

@@ -32,7 +32,7 @@
 						var id = jQuery(this).val();
 						var options = jQuery(this).data( 'options' ).filter( '[data-crm-country-id="' + id + '"]' );
 						cfStates.html( options );
-					});
+					}).trigger('change');
 				}
 			});
 		</script>

includes/class-civicrm-caldera-forms-forms.php

@@ -0,0 +1,61 @@
+<?php
+
+/**
+ * CiviCRM Caldera Forms Forms Class
+ *
+ * @since 0.4
+ */
+class CiviCRM_Caldera_Forms_Forms {
+
+    /**
+     * Initialises this object
+     *
+     * @since 0.4
+     */
+    public function __construct() {
+        $this->register_hooks();
+    }
+
+    /**
+     * Register hooks
+     *
+     * @since 0.4
+     */
+    public function register_hooks() {
+
+        // reorder processors on save form
+        add_filter( 'caldera_forms_presave_form', array( $this, 'reorder_contact_processors' ), 20 );
+
+    }
+
+    /**
+	 * Reorder Contact processors, fires when a form is saved
+	 *
+	 * @uses 'caldera_forms_presave_form' filter
+	 * @since 0.4
+	 *
+	 * @param array $form The form
+	 * @return array $form The modified form
+	 */
+	public function reorder_contact_processors( $form ) {
+
+		$contact_processors = $rest_processors = array();
+		foreach ( $form['processors'] as $pId => $processor ) {
+			if( $processor['type'] == 'civicrm_contact' ){
+				$contact_processors[$pId] = $processor;
+			}
+			if( $processor['type'] != 'civicrm_contact' ){
+				$rest_processors[$pId] = $processor;
+			}
+		}
+
+		// Sort Contact processors based on Contact Link
+		uasort( $contact_processors, function( $a, $b ){
+            return $a['config']['contact_link'] - $b['config']['contact_link'];
+        });
+
+		$form['processors'] = array_merge( $contact_processors, $rest_processors);
+
+		return $form;
+	}
+}