From 07d4bf92a16ad4b8b7f8b5fd9a9c73ef6e4a07b1 Mon Sep 17 00:00:00 2001
From: Billie Thompson <billie@purplebooth.co.uk>
Date: Thu, 5 Oct 2017 20:30:09 +0100
Subject: [PATCH] [Validator] Html5 Email Validation

Add documentation about the new mode parameter. Adds descriptions for
the 'loose', 'strict', and 'html5' options.
---
 email/testing.rst               |  4 ++--
 reference/constraints/Email.rst | 33 +++++++++++++++++++++++++++------
 2 files changed, 29 insertions(+), 8 deletions(-)

diff --git a/email/testing.rst b/email/testing.rst
index 477db8f5474..6cc61da7436 100644
--- a/email/testing.rst
+++ b/email/testing.rst
@@ -73,8 +73,8 @@ Problem: The Collector Object Is ``null``
 The email collector is only available when the profiler is enabled and collects
 information, as explained in :doc:`/testing/profiling`.
 
-Problem: The Collector Doesn't Contain the E-Mail
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Problem: The Collector Doesn't Contain the Email
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If a redirection is performed after sending the email (for example when you send
 an email after a form is processed and before redirecting to another page), make
diff --git a/reference/constraints/Email.rst b/reference/constraints/Email.rst
index 985c6a2dafd..f8927c1c8cf 100644
--- a/reference/constraints/Email.rst
+++ b/reference/constraints/Email.rst
@@ -7,7 +7,7 @@ cast to a string before being validated.
 +----------------+---------------------------------------------------------------------+
 | Applies to     | :ref:`property or method <validation-property-target>`              |
 +----------------+---------------------------------------------------------------------+
-| Options        | - `strict`_                                                         |
+| Options        | - `mode`_                                                           |
 |                | - `message`_                                                        |
 |                | - `checkMX`_                                                        |
 |                | - `checkHost`_                                                      |
@@ -91,14 +91,34 @@ Basic Usage
 Options
 -------
 
+mode
+~~~~
+
+**type**: ``string`` **default**: ``loose``
+
+This option is optional and defines the pattern the email address is validated against.
+Valid values are:
+
+* ``loose``
+* ``strict``
+* ``html5``
+
+loose
+.....
+
+A simple regular expression. Allows all values with an "@" symbol in, and a "."
+in the second host part of the email address.
+
 strict
-~~~~~~
+......
 
-**type**: ``boolean`` **default**: ``false``
+Uses the `egulias/email-validator`_ library to perform an RFC compliant
+validation. You will need to install that library to use this mode.
+
+html5
+.....
 
-When false, the email will be validated against a simple regular expression.
-If true, then the `egulias/email-validator`_ library is required to perform
-an RFC compliant validation.
+This matches the pattern used for the `HTML5 email input element`_.
 
 message
 ~~~~~~~
@@ -127,3 +147,4 @@ of the given email.
 .. include:: /reference/constraints/_payload-option.rst.inc
 
 .. _egulias/email-validator: https://packagist.org/packages/egulias/email-validator
+.. _HTML5 email input element: https://www.w3.org/TR/html5/sec-forms.html#email-state-typeemail