Merge pull request #278 from open-sausages/feature/email-rules

API Custom rules for email recipients

.travis.yml

@@ -2,17 +2,17 @@
 
 language: php 
 php: 
- - 5.3
+ - 5.4
 
 env:
- - DB=MYSQL CORE_RELEASE=3.1
  - DB=MYSQL CORE_RELEASE=3
+ - DB=MYSQL CORE_RELEASE=3.1
  - DB=PGSQL CORE_RELEASE=3.1
 
 matrix:
   include:
-    - php: 5.4
+    - php: 5.3
-      env: DB=MYSQL CORE_RELEASE=master
+      env: DB=MYSQL CORE_RELEASE=3.1
 
 before_script:
  - git clone git://github.com/silverstripe-labs/silverstripe-travis-support.git ~/travis-support

code/model/UserDefinedForm.php

@@ -83,6 +83,7 @@ class UserDefinedForm extends Page {
 			// define tabs
 			$fields->findOrMakeTab('Root.FormContent', _t('UserDefinedForm.FORM', 'Form'));
 			$fields->findOrMakeTab('Root.FormOptions', _t('UserDefinedForm.CONFIGURATION', 'Configuration'));
+			$fields->findOrMakeTab('Root.Recipients', _t('UserDefinedForm.RECIPIENTS', 'Recipients'));
 			$fields->findOrMakeTab('Root.Submissions', _t('UserDefinedForm.SUBMISSIONS', 'Submissions'));
 			
 			// field editor
@@ -99,21 +100,19 @@ class UserDefinedForm extends Page {
 			$editor->setRows(3);
 			$label->addExtraClass('left');
 			
-			// Set the summary fields of UserDefinedForm_EmailRecipient dynamically via config system
+			// Define config for email recipients
-			Config::inst()->update(
+			$emailRecipientsConfig = GridFieldConfig_RecordEditor::create(10);
-				'UserDefinedForm_EmailRecipient',
+			$emailRecipientsConfig->getComponentByType('GridFieldAddNewButton')
-				'summary_fields',
+				->setButtonName(
-				array(
+					_t('UserDefinedForm.ADDEMAILRECIPIENT', 'Add Email Recipient')
-					'EmailAddress' => _t('UserDefinedForm.EMAILADDRESS', 'Email'),
-					'EmailSubject' => _t('UserDefinedForm.EMAILSUBJECT', 'Subject'),
-					'EmailFrom' => _t('UserDefinedForm.EMAILFROM', 'From'),
-				)
 				);
 			
 			// who do we email on submission
-			$emailRecipients = new GridField('EmailRecipients', _t('UserDefinedForm.EMAILRECIPIENTS', 'Email Recipients'), $self->EmailRecipients(), GridFieldConfig_RecordEditor::create(10));
+			$emailRecipients = new GridField(
-			$emailRecipients->getConfig()->getComponentByType('GridFieldAddNewButton')->setButtonName(
+				'EmailRecipients',
-				_t('UserDefinedForm.ADDEMAILRECIPIENT', 'Add Email Recipient')
+				_t('UserDefinedForm.EMAILRECIPIENTS', 'Email Recipients'),
+				$self->EmailRecipients(),
+				$emailRecipientsConfig
 			);
 			$emailRecipients
 				->getConfig()
@@ -121,7 +120,7 @@ class UserDefinedForm extends Page {
 				->setItemRequestClass('UserDefinedForm_EmailRecipient_ItemRequest');
 			
 			$fields->addFieldsToTab('Root.FormOptions', $onCompleteFieldSet);
-			$fields->addFieldToTab('Root.FormOptions', $emailRecipients);
+			$fields->addFieldToTab('Root.Recipients', $emailRecipients);
 			$fields->addFieldsToTab('Root.FormOptions', $self->getFormOptions());
 			
 			
@@ -322,7 +321,12 @@ SQL;
 	 * @return ArrayList
 	 */
 	public function FilteredEmailRecipients($data = null, $form = null) {
-		$recipients = new ArrayList($this->getComponents('EmailRecipients')->toArray());
+		$recipients = new ArrayList($this->EmailRecipients()->toArray());
+
+		// Filter by rules
+		$recipients = $recipients->filterByCallback(function($recipient) use ($data, $form) {
+			return $recipient->canSend($data, $form);
+		});
 
 		$this->extend('updateFilteredEmailRecipients', $recipients, $data, $form);
 
@@ -1185,7 +1189,8 @@ class UserDefinedForm_EmailRecipient extends DataObject {
 		'EmailBodyHtml' => 'HTMLText',
 		'EmailTemplate' => 'Varchar',
 		'SendPlain' => 'Boolean',
-		'HideFormData' => 'Boolean'
+		'HideFormData' => 'Boolean',
+		'CustomRulesCondition' => 'Enum("And,Or")'
 	);
 
 	private static $has_one = array(
@@ -1195,80 +1200,225 @@ class UserDefinedForm_EmailRecipient extends DataObject {
 		'SendEmailSubjectField' => 'EditableFormField'
 	);
 
-	private static $summary_fields = array();
+	private static $has_many = array(
+		'CustomRules' => 'UserDefinedForm_EmailRecipientCondition'
+	);
+
+	private static $summary_fields = array(
+		'EmailAddress',
+		'EmailSubject',
+		'EmailFrom'
+	);
+
+	public function summaryFields() {
+		$fields = parent::summaryFields();
+		if(isset($fields['EmailAddress'])) {
+			$fields['EmailAddress'] = _t('UserDefinedForm.EMAILADDRESS', 'Email');
+		}
+		if(isset($fields['EmailSubject'])) {
+			$fields['EmailSubject'] = _t('UserDefinedForm.EMAILSUBJECT', 'Subject');
+		}
+		if(isset($fields['EmailFrom'])) {
+			$fields['EmailFrom'] = _t('UserDefinedForm.EMAILFROM', 'From');
+		}
+		return $fields;
+	}
+
+	/**
+	 * Get instance of UserDefinedForm when editing in getCMSFields
+	 *
+	 * @return UserDefinedFrom
+	 */
+	protected function getFormParent() {
+		$formID = $this->FormID
+			? $this->FormID
+			: Session::get('CMSMain.currentPage');
+		return UserDefinedForm::get()->byID($formID);
+	}
+
+	public function getTitle() {
+		if($this->EmailAddress) {
+			return $this->EmailAddress;
+		}
+		if($this->EmailSubject) {
+			return $this->EmailSubject;
+		}
+		return parent::getTitle();
+	}
+
+	/**
+	 * Generate a gridfield config for editing filter rules
+	 *
+	 * @return GridFieldConfig
+	 */
+	protected function getRulesConfig() {
+		$formFields = $this->getFormParent()->Fields();
+
+		$config = GridFieldConfig::create()
+			->addComponents(
+				new GridFieldButtonRow('before'),
+				new GridFieldToolbarHeader(),
+				new GridFieldAddNewInlineButton(),
+				new GridState_Component(),
+				new GridFieldDeleteAction(),
+				$columns = new GridFieldEditableColumns()
+			);
+
+		$columns->setDisplayFields(array(
+			'ConditionFieldID' => function($record, $column, $grid) use ($formFields) {
+				return DropdownField::create($column, false, $formFields->map('ID', 'Title'));
+			},
+			'ConditionOption' => function($record, $column, $grid) {
+				$options = UserDefinedForm_EmailRecipientCondition::config()->condition_options;
+				return DropdownField::create($column, false, $options);
+			},
+			'ConditionValue' => function($record, $column, $grid) {
+				return TextField::create($column);
+			}
+		));
+
+		return $config;
+	}
 
 	/**
 	 * @return FieldList
 	 */
 	public function getCMSFields() {
+		// Determine optional field values
+		$form = $this->getFormParent();
 
-		// Only show the preview link if the recipient has been saved.
+		// predefined choices are also candidates
-		if (!empty($this->EmailTemplate)) {
+		$multiOptionFields = EditableMultipleOptionField::get()->filter('ParentID', $form->ID);
-			$translatableKey = 'UserDefinedForm.EMAILPREVIEWAVAILABLE';
-			$previewHTML = '<p><a href="admin/pages/edit/EditForm/field/EmailRecipients/item/' . $this->ID . '/preview" target="_blank" class="ss-ui-button">Preview email</a></p>' . 
-				'<em>Note: Unsaved changes will not appear in the preview.</em>';
-		} else {
-			$translatableKey = 'UserDefinedForm.EMAILPREVIEWUNAVAILABLE';
-			$previewHTML = '<em>You can preview this email once you have saved the Recipient.</em>';
-		}
 
-		$fields = new FieldList(
+		// if they have email fields then we could send from it
-			new TextField('EmailSubject', _t('UserDefinedForm.EMAILSUBJECT', 'Email subject')),
+		$validEmailFromFields = EditableEmailField::get()->filter('ParentID', $form->ID);
-			new LiteralField('EmailFromContent', '<p>'._t(
+
+		// For the subject, only one-line entry boxes make sense
+		$validSubjectFields = EditableTextField::get()
+			->filter('ParentID', $form->ID)
+			->filterByCallback(function($item, $list) {
+				return (int)$item->getSetting('Rows') === 1;
+			});
+		$validSubjectFields->merge($multiOptionFields);
+
+		// To address can only be email fields or multi option fields
+		$validEmailToFields = new ArrayList($validEmailFromFields->toArray());
+		$validEmailToFields->merge($multiOptionFields);
+
+		// Build fieldlist
+		$fields = FieldList::create(Tabset::create('Root')->addExtraClass('EmailRecipientForm'));
+
+		// Configuration fields
+		$fields->addFieldsToTab('Root.EmailDetails', array(
+			// Subject
+			FieldGroup::create(
+				TextField::create('EmailSubject', _t('UserDefinedForm.TYPESUBJECT', 'Type subject'))
+					->setAttribute('style', 'min-width: 400px;'),
+				DropdownField::create(
+					'SendEmailSubjectFieldID',
+					_t('UserDefinedForm.SELECTAFIELDTOSETSUBJECT', '.. or select a field to use as the subject'),
+					$validSubjectFields->map('ID', 'Title')
+				)->setEmptyString('')
+			)
+				->setTitle(_t('UserDefinedForm.EMAILSUBJECT', 'Email subject')),
+
+			// To
+			FieldGroup::create(
+				TextField::create('EmailAddress', _t('UserDefinedForm.TYPETO', 'Type to address'))
+					->setAttribute('style', 'min-width: 400px;'),
+				DropdownField::create(
+					'SendEmailToFieldID',
+					_t('UserDefinedForm.ORSELECTAFIELDTOUSEASTO', '.. or select a field to use as the to address'),
+					$validEmailToFields->map('ID', 'Title')
+				)->setEmptyString(' ')
+			)
+				->setTitle(_t('UserDefinedForm.SENDEMAILTO','Send email to'))
+				->setDescription(_t(
+					'UserDefinedForm.SENDEMAILTO_DESCRIPTION',
+					'You may enter multiple email addresses as a comma separated list.'
+				)),
+
+
+			// From
+			TextField::create('EmailFrom', _t('UserDefinedForm.FROMADDRESS','Send email from'))
+				->setDescription(_t(
 					'UserDefinedForm.EmailFromContent',
 					"The from address allows you to set who the email comes from. On most servers this ".
 					"will need to be set to an email address on the same domain name as your site. ".
 					"For example on yoursite.com the from address may need to be something@yoursite.com. ".
 					"You can however, set any email address you wish as the reply to address."
-			) . "</p>"),
+				)),
-			new TextField('EmailFrom', _t('UserDefinedForm.FROMADDRESS','Send email from')),
+
-			new TextField('EmailReplyTo', _t('UserDefinedForm.REPLYADDRESS', 'Email for reply to')),
+
-			new TextField('EmailAddress', _t('UserDefinedForm.SENDEMAILTO','Send email to')),
+			// Reply-To
+			FieldGroup::create(
+				TextField::create('EmailReplyTo', _t('UserDefinedForm.TYPEREPLY', 'Type reply address'))
+					->setAttribute('style', 'min-width: 400px;'),
+				DropdownField::create(
+					'SendEmailFromFieldID',
+					_t('UserDefinedForm.ORSELECTAFIELDTOUSEASFROM', '.. or select a field to use as reply to address'),
+					$validEmailFromFields->map('ID', 'Title')
+				)->setEmptyString(' ')
+			)
+				->setTitle(_t('UserDefinedForm.REPLYADDRESS', 'Email for reply to'))
+				->setDescription(_t(
+					'UserDefinedForm.REPLYADDRESS_DESCRIPTION',
+					'The email address which the recipient is able to \'reply\' to.'
+				))
+		));
+		
+		// Only show the preview link if the recipient has been saved.
+		if (!empty($this->EmailTemplate)) {
+			$preview = sprintf(
+				'<p><a href="%s" target="_blank" class="ss-ui-button">%s</a></p><em>%s</em>',
+				"admin/pages/edit/EditForm/field/EmailRecipients/item/{$this->ID}/preview",
+				_t('UserDefinedForm.PREVIEW_EMAIL', 'Preview email'),
+				_t('UserDefinedForm.PREVIEW_EMAIL_DESCRIPTION', 'Note: Unsaved changes will not appear in the preview.')
+			);
+		} else {
+			$preview = sprintf(
+				'<em>%s</em>',
+				_t(
+					'UserDefinedForm.PREVIEW_EMAIL_UNAVAILABLE',
+					'You can preview this email once you have saved the Recipient.'
+				)
+			);
+		}
+
+		// Email templates
+		$fields->addFieldsToTab('Root.EmailContent', array(
 			new CheckboxField('HideFormData', _t('UserDefinedForm.HIDEFORMDATA', 'Hide form data from email?')),
 			new CheckboxField('SendPlain', _t('UserDefinedForm.SENDPLAIN', 'Send email as plain text? (HTML will be stripped)')),
 			new DropdownField('EmailTemplate', _t('UserDefinedForm.EMAILTEMPLATE', 'Email template'), $this->getEmailTemplateDropdownValues()),
 			new HTMLEditorField('EmailBodyHtml', _t('UserDefinedForm.EMAILBODYHTML','Body')),
 			new TextareaField('EmailBody', _t('UserDefinedForm.EMAILBODY','Body')),
-			new LiteralField('EmailPreview', '<div id="EmailPreview">' . _t($translatableKey, $previewHTML) . '</div>')
+			new LiteralField('EmailPreview', '<div id="EmailPreview">' . $preview . '</div>')
+		));
+
+		// Custom rules for sending this field
+		$grid = new GridField(
+			"CustomRules",
+			_t('EditableFormField.CUSTOMRULES', 'Custom Rules'),
+			$this->CustomRules(),
+			$this->getRulesConfig()
 		);
-		
+		$grid->setDescription(_t(
-		$formID = ($this->FormID != 0) ? $this->FormID : Session::get('CMSMain.currentPage');
+			'UserDefinedForm.RulesDescription',
-		$dropdowns = array();
+			'Emails will only be sent to the recipient if the custom rules are met. If no rules are defined, this receipient will receive notifications for every submission.'
-		// if they have email fields then we could send from it
+		));
-		$validEmailFields = EditableEmailField::get()->filter('ParentID', (int)$formID);
+		$fields->addFieldsToTab('Root.CustomRules', array(
-		// for the subject, only one-line entry boxes make sense
+			new DropdownField(
-		$validSubjectFields = EditableTextField::get()->filter('ParentID', (int)$formID)->filterByCallback(function($item, $list) { return (int)$item->getSetting('Rows') === 1; });
+				'CustomRulesCondition',
-		// predefined choices are also candidates
+				_t('UserDefinedForm.SENDIF', 'Send condition'),
-		$multiOptionFields = EditableMultipleOptionField::get()->filter('ParentID', (int)$formID);
+				array(
-
+					'Or' => 'Any conditions are true',
-		$fields->insertAfter($dropdowns[] = new DropdownField(
+					'And' => 'All conditions are true'
-			'SendEmailFromFieldID',
+				)
-			_t('UserDefinedForm.ORSELECTAFIELDTOUSEASFROM', '.. or select a field to use as reply to address'),
+			),
-			$validEmailFields->map('ID', 'Title')
+			$grid
-		), 'EmailReplyTo');
+		));
-
-		$validEmailFields = new ArrayList($validEmailFields->toArray());
-		$validEmailFields->merge($multiOptionFields);
-		$validSubjectFields->merge($multiOptionFields);
-
-		$fields->insertAfter($dropdowns[] = new DropdownField(
-			'SendEmailToFieldID',
-			_t('UserDefinedForm.ORSELECTAFIELDTOUSEASTO', '.. or select a field to use as the to address'),
-			$validEmailFields->map('ID', 'Title')
-		), 'EmailAddress');
-		$fields->insertAfter($dropdowns[] = new DropdownField(
-			'SendEmailSubjectFieldID',
-			_t('UserDefinedForm.SELECTAFIELDTOSETSUBJECT', '.. or select a field to use as the subject'),
-			$validSubjectFields->map('ID', 'Title')
-		), 'EmailSubject');
-
-		foreach($dropdowns as $dropdown) {
-			$dropdown->setHasEmptyDefault(true);
-			$dropdown->setEmptyString(" ");
-		}
 
 		$this->extend('updateCMSFields', $fields);
-
 		return $fields;
 	}
 
@@ -1308,6 +1458,36 @@ class UserDefinedForm_EmailRecipient extends DataObject {
 		return $this->Form()->canDelete();
 	}
 
+	/*
+	 * Determine if this recipient may receive notifications for this submission
+	 *
+	 * @param array $data
+	 * @param Form $form
+	 * @return bool
+	 */
+	public function canSend($data, $form) {
+		// Skip if no rules configured
+		$customRules = $this->CustomRules();
+		if(!$customRules->count()) {
+			return true;
+		}
+
+		// Check all rules
+		$isAnd = $this->CustomRulesCondition === 'And';
+		foreach($customRules as $customRule) {
+			$matches = $customRule->matches($data, $form);
+			if($isAnd && !$matches) {
+				return false;
+			}
+			if(!$isAnd && $matches) {
+				return true;
+			}
+		}
+
+		// Once all rules are checked
+		return $isAnd;
+	}
+
 	/**
 	 * Make sure the email template saved against the recipient exists on the file system.
 	 *
@@ -1382,6 +1562,58 @@ class UserDefinedForm_EmailRecipient_ItemRequest extends GridFieldDetailForm_Ite
 	}
 }
 
+/**
+ * Declares a condition that determines whether an email can be sent to a given recipient
+ */
+class UserDefinedForm_EmailRecipientCondition extends DataObject {
+
+	/**
+	 * List of options
+	 *
+	 * @config
+	 * @var array
+	 */
+	private static $condition_options = array(
+		"IsBlank" => "Is blank",
+		"IsNotBlank" => "Is not blank",
+		"Equals" => "Equals",
+		"NotEquals" => "Doesn't equal"
+	);
+
+	private static $db = array(
+		'ConditionOption' => 'Enum("IsBlank,IsNotBlank,Equals,NotEquals")',
+		'ConditionValue' => 'Varchar'
+	);
+
+	private static $has_one = array(
+		'Parent' => 'UserDefinedForm_EmailRecipient',
+		'ConditionField' => 'EditableFormField'
+	);
+
+	/**
+	 * Determine if this rule matches the given condition
+	 *
+	 * @param array $data
+	 * @param Form $form
+	 * @return bool
+	 */
+	public function matches($data, $form) {
+		$fieldName = $this->ConditionField()->Name;
+		$fieldValue = isset($data[$fieldName]) ? $data[$fieldName] : null;
+		switch($this->ConditionOption) {
+			case 'IsBlank':
+				return empty($fieldValue);
+			case 'IsNotBlank':
+				return !empty($fieldValue);
+			default:
+				$matches = is_array($fieldValue)
+					? in_array($this->ConditionValue, $fieldValue)
+					: $this->ConditionValue === (string)$fieldValue;
+				return ($this->ConditionOption === 'Equals') === (bool)$matches;
+		}
+	}
+}
+
 /**
  * Email that gets sent to the people listed in the Email Recipients when a 
  * submission is made.

composer.json

@@ -10,7 +10,8 @@
 	}],
 	"require": {
 		"silverstripe/framework": ">=3.1.0",
-		"silverstripe/cms": ">=3.1.0"
+		"silverstripe/cms": ">=3.1.0",
+		"silverstripe-australia/gridfieldextensions": "1.1.0"
 	},
 	"suggest": {
 		"colymba/gridfield-bulk-editing-tools": "Allows for bulk management of form submissions"

css/FieldEditor.css

@@ -51,6 +51,19 @@ li.class-UserDefinedForm > a .jstree-pageicon { background-position: 0 -64px; }
 }
 */
 
+/* Email Recipient Form
+---------------------------------------- */
+.EmailRecipientForm .fieldgroup .fieldgroup-field {
+	padding-top: 0;
+}
+
+.EmailRecipientForm .fieldgroup .fieldgroup-field.last {
+	padding-bottom: 0;
+}
+
+.EmailRecipientForm .ss-ui-button {
+	margin-bottom: 4px;
+}
 
 
 /* Field Listing

docs/en/user-documentation.md

@@ -4,7 +4,8 @@ In this section:
 
 * Learn how to create and edit forms
 * Learn how to add fields to a form
-* Learn how to view submissions and reply to them automatically
+* Learn how to view submissions
+* Learn how to set up automated emails upon form completion
 
 ## Before we begin:
 
@@ -29,8 +30,6 @@ You will notice that a new page has been created, with the name of "New UserDefi
 Simply click on the new page in the content page to bring it up in the editing pane.
 
 <div class="note" markdown="1">
-### Notes:
-
 Don't worry if you create your page in the "wrong" place. Pages can be moved and re-ordered
 easily, and we will cover that under "Managing Your Site."
 </div>
@@ -175,9 +174,19 @@ to determine the size and the number of rows in a text field.
 
 * Use [HTML Block](#html-block), with the appropriate level [Heading](#heading).
 
-## Sending emails
+## Viewing form submissions
 
-The UserForms module allows you to email form submissions to multiple people.
+To view form submissions navigate to the 'Submissions' tab. You can click any of the listed submissions to view the content of each submission.
+
+![Viewing submissions](_images/viewing-submissions.png)
+
+## Setting up automated emails
+
+It is possible to set up automated emails upon each form submission, to do this navigate to the "Recipients" tab and click "Add Email Recipient".
+
+![Add email recipient](_images/add-email-recipient.png)
+
+You will be prompted with a form where you can fill in the details of the email.
 
 ### Using form fields in submission emails
 
@@ -188,3 +197,67 @@ Each form field has a unique merge field located under the field's options.
 Simply insert the merge field into the email content, and the field's value will be displayed, when the email is sent.
 
 ![Merge field in content](_images/mergefieldcontent.png)
+
+### Email details
+
+#### Email Subject
+
+The subject of the email, you can either type a custom subject here or select a field from the form to use as the email subject.
+
+#### Send email to
+
+This is the recipient's address where the email will be sent.
+
+#### Send email from
+
+This shows where the email was sent from, and will most likely need to be an email address on the same domain as your site. For example If your website is yoursite.com, the email address for this field should be something@yoursite.com.
+
+#### Email for reply to
+
+This will be the address which the email recipient will be able to 'reply' to.
+
+#### Email content
+
+In this field you can add a custom message to add to the email
+
+#### Hide form data from email?
+
+You can check this if you do not wish for the email recipient to see the form submission's data in the email.
+
+#### Send email as plain text?
+
+You can check this if you want to remove all of the HTML from the email, this means the email
+will have no custom styling and the recipient will only see the plain text.
+
+If `Send email as plain text?` is unselected, several additional options for HTML editing are displayed.
+
+If sending as HTML, there is the option to preview the HTML that is sent in the editor. Additionally, a HTML
+template can be selected to provide a standard formatted email to contain the editable HTML content.
+
+The list of available templates can be controlled by specifying the folder for these template files in yaml config.
+
+
+	:::yaml
+	UserDefinedForm:
+	  email_template_directory: mysite/templates/useremails/
+
+
+### Custom Rules
+
+In this section you can determine whether to send the email to the recipient based on the data in the form submission.
+
+#### Send conditions
+
+This decides whether to send the email based on two options
+
+1. *All* conditions are true (Every single custom rule must be met in order to send the email)
+2. *Any* conditions are true (At least one of the custom rules must be met in order to send the email)
+
+#### Adding a custom rule
+
+* Click 'Add' to add a custom sending rule.
+* Select the field which you want the custom rule to apply to
+* Select the condition the field must follow
+* enter for the condition (the 'is blank' and 'is not blank' conditions do not require any text)
+
+

tests/UserDefinedFormTest.php

@@ -55,6 +55,7 @@ class UserDefinedFormTest extends FunctionalTest {
 		$form = $this->objFromFixture('UserDefinedForm', 'basic-form-page');
 
 		$popup = new UserDefinedForm_EmailRecipient();
+		$popup->FormID = $form->ID;
 
 		$fields = $popup->getCMSFields();
 
@@ -69,11 +70,10 @@ class UserDefinedFormTest extends FunctionalTest {
 		$email = $this->objFromFixture('EditableEmailField','email-field');
 		$form->Fields()->add($email);
 
-		$popup->FormID = $form->ID;
 		$popup->write();
 
 		$fields = $popup->getCMSFields();
-		$this->assertThat($fields->fieldByName('SendEmailToFieldID'), $this->isInstanceOf('DropdownField'));
+		$this->assertThat($fields->dataFieldByName('SendEmailToFieldID'), $this->isInstanceOf('DropdownField'));
 
 		// if the front end has checkboxs or dropdown they can select from that can also be used to send things
 		$dropdown = $this->objFromFixture('EditableDropdown', 'department-dropdown');
@@ -264,4 +264,97 @@ class UserDefinedFormTest extends FunctionalTest {
 		$this->assertEquals($submit->Title(), 'Text on submit button:');
 		$this->assertEquals($reset->Title(), 'Show Clear Form Button');
 	}
+
+	public function testEmailRecipientFilters() {
+		$form = $this->objFromFixture('UserDefinedForm', 'filtered-form-page');
+
+		// Check unfiltered recipients
+		$result0 = $form
+			->EmailRecipients()
+			->sort('EmailAddress')
+			->column('EmailAddress');
+		$this->assertEquals(
+			array(
+				'filtered1@example.com',
+				'filtered2@example.com',
+				'unfiltered@example.com'
+			),
+			$result0
+		);
+
+		// check filters based on given data
+		$result1 = $form->FilteredEmailRecipients(
+			array(
+				'your-name' => 'Value',
+				'address' => '',
+				'street' => 'Anything',
+				'city' => 'Matches Not Equals',
+				'colours' => array('Red') // matches 2
+			), null
+		)
+			->sort('EmailAddress')
+			->column('EmailAddress');
+		$this->assertEquals(
+			array(
+				'filtered2@example.com',
+				'unfiltered@example.com'
+			),
+			$result1
+		);
+
+		// Check all positive matches
+		$result2 = $form->FilteredEmailRecipients(
+			array(
+				'your-name' => '',
+				'address' => 'Anything',
+				'street' => 'Matches Equals',
+				'city' => 'Anything',
+				'colours' => array('Red', 'Blue') // matches 2
+			), null
+		)
+			->sort('EmailAddress')
+			->column('EmailAddress');
+		$this->assertEquals(
+			array(
+				'filtered1@example.com',
+				'filtered2@example.com',
+				'unfiltered@example.com'
+			),
+			$result2
+		);
+
+
+		$result3 = $form->FilteredEmailRecipients(
+			array(
+				'your-name' => 'Should be blank but is not',
+				'address' => 'Anything',
+				'street' => 'Matches Equals',
+				'city' => 'Anything',
+				'colours' => array('Blue')
+			), null
+		)->column('EmailAddress');
+		$this->assertEquals(
+			array(
+				'unfiltered@example.com'
+			),
+			$result3
+		);
+
+
+		$result4 = $form->FilteredEmailRecipients(
+			array(
+				'your-name' => '',
+				'address' => 'Anything',
+				'street' => 'Wrong value for this field',
+				'city' => '',
+				'colours' => array('Blue', 'Green')
+			), null
+		)->column('EmailAddress');
+		$this->assertEquals(
+			array(
+				'unfiltered@example.com'
+			),
+			$result4
+		);
+	}
 }

tests/UserDefinedFormTest.yml

@@ -31,23 +31,17 @@ EditableOption:
     Name: Option6
     Title: Option 6
 
-UserDefinedForm_EmailRecipient:
+  option-7:
-    recipient-1:
+    Name: Option7
-        EmailAddress: test@example.com
+    Title: Red
-        EmailSubject: Email Subject
-        EmailFrom: no-reply@example.com
 
-    no-html:
+  option-8:
-        EmailAddress: nohtml@example.com
+    Name: Option8
-        EmailSubject: Email Subject
+    Title: Blue
-        EmailFrom: no-reply@example.com
-        SendPlain: true
 
-    no-data:
+  option-9:
-        EmailAddress: nodata@example.com
+    Name: Option9
-        EmailSubject: Email Subject
+    Title: Green
-        EmailFrom: no-reply@example.com  
-        HideFormData: true
   
 EditableTextField:
   basic-text:
@@ -58,6 +52,22 @@ EditableTextField:
     Name: basic-text-name
     Title: Basic Text Field
  
+  your-name-field:
+    Name: your-name
+    Title: Name
+ 
+  address-field:
+    Name: address
+    Title: Address
+    
+  street-field:
+    Name: street
+    Title: Street
+    
+  city-field:
+    Name: city
+    Title: City
+          
   required-text:
     Name: required-text-field
     Title: Required Text Field
@@ -90,18 +100,90 @@ EditableCheckboxGroupField:
     Title: Check box group
     Options: =>EditableOption.option-3, =>EditableOption.option-4
 
+  colour-checkbox-group:
+    Name: colours
+    Title: 'Select Colours'
+    Options: =>EditableOption.option-7, =>EditableOption.option-8, =>EditableOption.option-9
+
 EditableEmailField:
   email-field:
     Name: email-field
     Title: Email
 
-
 EditableRadioField:
   radio-field:
     Name: radio-option
     Title: Radio Option
     Options: =>EditableOption.option-5, =>EditableOption.option-6
 
+UserDefinedForm_EmailRecipientCondition:
+# filtered recipient 1
+  blank-rule:
+    ConditionOption: IsBlank
+    ConditionField: =>EditableTextField.your-name-field
+
+  not-blank-rule:
+    ConditionOption: IsNotBlank
+    ConditionField: =>EditableTextField.address-field
+
+  equals-rule:
+    ConditionOption: Equals
+    ConditionField: =>EditableTextField.street-field
+    ConditionValue: 'Matches Equals'
+
+  not-equals-rule:
+    ConditionOption: NotEquals
+    ConditionField: =>EditableTextField.city-field
+    ConditionValue: 'Matches Not Equals'
+
+# filtered recipient 2
+  group-equals-rule:
+    ConditionOption: Equals
+    ConditionField: =>EditableCheckboxGroupField.colour-checkbox-group
+    ConditionValue: Red
+
+  group-not-equals-rule:
+    ConditionOption: NotEquals
+    ConditionField: =>EditableCheckboxGroupField.colour-checkbox-group
+    ConditionValue: Blue
+
+
+UserDefinedForm_EmailRecipient:
+  recipient-1:
+    EmailAddress: test@example.com
+    EmailSubject: Email Subject
+    EmailFrom: no-reply@example.com
+    
+  no-html:
+    EmailAddress: nohtml@example.com
+    EmailSubject: Email Subject
+    EmailFrom: no-reply@example.com
+    SendPlain: true
+    
+  no-data:
+    EmailAddress: nodata@example.com
+    EmailSubject: Email Subject
+    EmailFrom: no-reply@example.com  
+    HideFormData: true
+    
+  unfiltered-recipient-1:
+    EmailAddress: unfiltered@example.com
+    EmailSubject: Email Subject
+    EmailFrom: no-reply@example.com
+    
+  filtered-recipient-1:
+    EmailAddress: filtered1@example.com
+    EmailSubject: Email Subject
+    EmailFrom: no-reply@example.com
+    CustomRules: =>UserDefinedForm_EmailRecipientCondition.blank-rule,  =>UserDefinedForm_EmailRecipientCondition.not-blank-rule, =>UserDefinedForm_EmailRecipientCondition.equals-rule,  =>UserDefinedForm_EmailRecipientCondition.not-equals-rule
+    CustomRulesCondition: 'And'
+    
+  filtered-recipient-2:
+    EmailAddress: filtered2@example.com
+    EmailSubject: Email Subject
+    EmailFrom: no-reply@example.com
+    CustomRules: =>UserDefinedForm_EmailRecipientCondition.group-equals-rule, =>UserDefinedForm_EmailRecipientCondition.group-not-equals-rule
+    CustomRulesCondition: 'Or'
 
 UserDefinedForm:
   basic-form-page:
@@ -124,4 +206,7 @@ UserDefinedForm:
   empty-form:
     Title: Empty Form
 
-        
+  filtered-form-page:
+    Title: 'Page with filtered recipients'
+    Fields: =>EditableCheckboxGroupField.checkbox-group, =>EditableTextField.your-name-field, =>EditableTextField.street-field, =>EditableTextField.city-field
+    EmailRecipients: =>UserDefinedForm_EmailRecipient.unfiltered-recipient-1, =>UserDefinedForm_EmailRecipient.filtered-recipient-1, =>UserDefinedForm_EmailRecipient.filtered-recipient-2