Merge pull request #16 from bu-ist/source-id-and-extra-values

Support for SOURCE field and arbitrary preset fields.

bu-liaison-inquiry.php

@@ -6,7 +6,7 @@
 Author: Boston University IS&T (Jonathan Williams)
 Author URI: http://developer.bu.edu
 Description: Provide a form to send data to the Liaison SpectrumEMP API
-Version: 0.4
+Version: 0.5
 */
 
 
@@ -109,6 +109,11 @@ function liaison_inquiry_form( $atts ) {
 				if ( intval( $att_key ) === $att_key ) {
 					$presets[ $att_key ] = $att;
 				}
+				// There is a SOURCE value that can be set as well: is this the only non-integer field label?
+				if ( 'source' === $att_key ) {
+					// Shortcode attributes appear to be processed as lower case, while Liaison uses UPPERCASE for this field label.
+					$presets['SOURCE'] = $att;
+				}
 			}
 		}
 
@@ -193,6 +198,8 @@ function minify_form_definition( $inquiry_form, $field_ids, $presets ) {
 							$field->hidden = true;
 							if ( isset( $presets[ $field->id ] ) ) {
 								$field->hidden_value = $presets[ $field->id ];
+								// Now remove it from the $presets array so that we don't double process it.
+								unset( $presets[ $field->id ] );
 							} else {
 								$field->hidden_value = self::MINI_DUMMY_VALUE;
 							}
@@ -201,6 +208,27 @@ function minify_form_definition( $inquiry_form, $field_ids, $presets ) {
 				}
 			}
 		}
+		// Any other preset values that weren't covered by the minify function should be inserted as hidden values.
+		foreach ( $presets as $preset_key => $preset_val ) {
+			// Prepend any preset fields to the $section->fields array as hidden inputs.
+			// First check if it is already a visible field. If so, throw an error in to the error logs and drop it from the preset.
+			$field_exists = false;
+			foreach ( $inquiry_form->sections as $section ) {
+				if ( array_key_exists( $preset_key, $section->fields ) ) {$field_exists = true;}
+			}
+
+			if ( $field_exists ) {
+				// Don't want to preset a hidden value for an existing field.  Who knows what might happen?
+				error_log( sprintf( 'Field key %s was found in a shortcode, but it already exists in the liason form. Dropping preset value.' , $preset_key ) );
+			} else {
+				$hidden_field = new stdClass;
+				$hidden_field->hidden = true;
+				$hidden_field->id = $preset_key;
+				$hidden_field->hidden_value = $preset_val;
+				array_unshift( $inquiry_form->sections[0]->fields, $hidden_field );
+			}
+		}
+
 		return $inquiry_form;
 	}
 

readme.md

@@ -2,12 +2,28 @@
 Inquiry form for Liaison Inc.'s SpectrumEMP enrollment CRM
 ## Description
 This Wordpress plugin provides an inquiry form for prospective students.  It uses the SpectrumEMP API to get the form parameters from Liaison, and submit the form data back to Liaison. It is based on example code from `https://github.com/Liaison-Intl/EMP_API-Example`
-## Usage
+## Basic Usage
 ### Admin
 The plugin provides an option page in the Wordpress admin, under the main `Settings` menu called `Liaison API Keys`.  Enter the API Key and Client ID provided by Liaison for the relevant account here.
 ### Inquiry Form shortcode
 Once the API Key and Client ID have been set, the inquiry form can be placed anywhere in the site by using the following shortcode:
 
 `[liaison_inquiry_form]`
 
-When the page or post is displayed, the shortcode will be replaced by the Liaison iquiry form.  Prospective students can fill out the form and submit it directly from the Wordpress site, and will be redirected to their personal URL on the Spectrum EMP site.
+When the page or post is displayed, the shortcode will be replaced by the Liaison inquiry form.  Prospective students can fill out the form and submit it directly from the Wordpress site, and will be redirected to their personal URL on the Spectrum EMP site.
+##Advanced Usage
+### Mini-form
+
+A mini-form can be created by adding a shortcode attribute named `fields` containing a comma delimited list of integer field ids.  The field ids that are listed will appear in the shortened form.  
+
+* Any unlisted fields that are not required will be dropped from the form
+* Any unlisted required fields with no preset values set in the shortcode will be included as hidden field with a default value (currently `mini-form`)
+* Any unlisted required fields that have a preset value set in the shortcode will be included as a hidden field with the preset value
+
+Preset values can be added to the shortcode by adding an attribute with the field id and value like this: `11="PN"`.  Here `11` is the field id for the Country, and `PN` is a country code that will be used as the preset value.
+
+###Arbitrary preset values
+Any other values can be set by including a shortcode attribute of the form `field_id="preset value"`.  As long as there is a valid field id, any field can be preset in this way regardless of whether the field is part of the inquiry form.
+
+###SOURCE
+Liaison uses a special field called `source` that can track where a lead originated.  It appears to be the only field in the Liaison forms that uses something other than an integer for the field id.  The source can be set in a shortcode attribute like any other field like this: `source="12345"`.