Merge pull request #5 from codem/update-validation

Update validation

Author: MrJamesEllis

README.md

@@ -4,11 +4,11 @@ This module provides a set of bare bones HTML5 inputs with no Javascript or CSS.
 
 You can use these fields in your projects as-is or extend them to provide additional features or shims.
 
-The supported inputs are listed at https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input tagged 'HTML5'
+The supported inputs are listed at https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input:
 
 + colour (color)
-+ date, datetime, time
-+ email (extends core EmailField)
++ date, datetime-local, time
++ email (extends core Silverstripe EmailField)
 + month, week
 + number
 + range
@@ -20,9 +20,22 @@ Browser support for these fields is varying although nearly all modern browsers
 
 Date, datetime and time fields are particularly difficult to support, due to locale differences and even different user expectations within those locales.
 
+## Traits
+
+Various field types support certain traits that allow setting/getting of common attributes
+
++ Step - https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#step
++ DataList - https://developer.mozilla.org/en-US/docs/Web/HTML/Element/datalist
++ Spellcheck - https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/spellcheck
++ Min/Max - https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#min / max
++ Pattern - https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#pattern
++ Multiple - https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#multiple
+
 ### Datalist
 
-Certain inputs support a `<datalist>`, [e.g the colour field](./docs/en/002_inputs.md) to restrict initial selection. Browser implementation varies.
+Certain inputs support a `<datalist>`, [e.g the colour field](./docs/en/002_inputs.md) to restrict initial selection.
+
+This works somewhat like a `<select>` element, except that browser implementation and support varies.
 
 
 ## Requirements
@@ -54,7 +67,6 @@ Hopefully none !
 
 + Codem
 
-
 ## Bugtracker
 
 Please use the Github issue tracker to report bugs and request features

src/Forms/ColorField.php

@@ -2,24 +2,62 @@
 
 namespace Codem\Utilities\HTML5;
 
-use Silverstripe\Forms\TextField;
+use Silverstripe\Forms\FormField;
 use SilverStripe\Forms\Validator;
 
 /**
  * Provides a colour picker / field
+ *
  * @see https://www.w3.org/wiki/Html/Elements/input/color
  * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/color
  * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/color#Value wrt value
+ * @see https://html.spec.whatwg.org/multipage/input.html#color-state-(type=color) (default colour)
+ *
+ * Default value
+ * =============
+ * The colour input is special in that it does not allow an empty value within the current spec.
+ * The browser will always send through the default colour in the spec (#000000) if none is supplied
+ *
+ * In this implementation, the default field value set is static::WHITE
  */
-class ColorField extends TextField
+class ColorField extends FormField
 {
 
     use Core;
     use Datalist;
 
+    /**
+     * @var string
+     */
+    const WHITE = "#ffffff";
+
+    /**
+     * @var string
+     */
     protected $inputType = 'color';
 
-    protected $defaultValue = "#ffffff";
+    /**
+     * This is the default colour for the input,
+     * if no value is set, or if the value provided is not a valid hex colour string
+     * On field construction this will be set to white
+     * @var string|null
+     */
+    protected $defaultValue = null;
+
+    /**
+     * Returns a colour input field
+     *
+     * @param string $name
+     * @param null|string $title
+     * @param string $value
+     * @param string $defaultValue the default value to use for the input
+     *
+     */
+    public function __construct($name, $title = null, $value = '', $defaultValue = '')
+    {
+        $this->setDefaultValue($defaultValue);
+        parent::__construct($name, $title, $value);
+    }
 
     /**
      * Returns the value saved as a 6 chr RGB colour with # prefixed
@@ -42,18 +80,39 @@ public function Value()
     /**
      * When the value is set, handle incorrect values
      * @param string $value an RGB colour value as a 'valid simple colour'
-     * @return void
      */
     public function setValue($value, $data = null)
     {
         $this->value = $this->getValidRGB($value);
+        return $this;
+    }
+
+
+    /**
+     * Set the default value to be used if an invalid colour is detected
+     * The default is static::WHITE
+     *
+     * @param string $defaultValue an RGB colour value as a 'valid simple colour'
+     */
+    public function setDefaultValue(string $defaultValue) : self
+    {
+        $this->defaultValue = $this->getValidRGB($defaultValue);
+        return $this;
+    }
+
+    /**
+     * Get the current default value
+     */
+    public function getDefaultValue() : string
+    {
+        return $this->defaultValue;
     }
 
     /**
      * Base on the value return either the defaultValue colour value or the value
      * @return string
      * @param string $value the value to check
-     * @param Validator $validator optional, if set relevant errors will be added
+     * @param Validator $validator optional, see isValidRGB
      *
      * The only valid value here is defined by the "valid simple colour" definition at
      * https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-simple-colour
@@ -64,15 +123,34 @@ public function setValue($value, $data = null)
      *    representing the red component, the middle two digits representing the green component,
      *  and the last two digits representing the blue component, in hexadecimal.</blockquote>
      */
-    public function getValidRGB($value, Validator $validator = null)
+    public function getValidRGB(?string $value, Validator $validator = null) : string
     {
 
-        // empty values default to the empty value value
+        $simpleColourValue = $this->defaultValue ?? static::WHITE;
+
         if(!$value) {
-            return $this->defaultValue;
+            // no value provided .. return the defaultValue if set or WHITE
+            return $simpleColourValue;
         }
 
         $value = strtolower($value);
+        if(!$this->isValidRGB($value, $validator)) {
+            $value = $simpleColourValue;
+        }
+
+        // Let result be a simple color.
+        return $value;
+    }
+
+    /**
+     * Check if the value provided is a valid RGB value
+     * @param string $value
+     * @param Validator $validator an optional validator. If provided specific errors will be stored in the validator
+     */
+    public function isValidRGB(?string $value, Validator $validator = null) : bool {
+
+        // Ensure a string value
+        $value = $value ?? '';
 
         // If input is not exactly seven characters long, then return an error.
         if(mb_strlen($value) != 7) {
@@ -86,7 +164,7 @@ public function getValidRGB($value, Validator $validator = null)
                     "validation"
                 );
             }
-            return $this->defaultValue;
+            return false;
         }
 
         // If the first character in input is not a U+0023 NUMBER SIGN character (#), then return an error.
@@ -101,7 +179,7 @@ public function getValidRGB($value, Validator $validator = null)
                     "validation"
                 );
             }
-            return $this->defaultValue;
+            return false;
         }
 
         // If the last six characters of input are not all ASCII hex digits, then return an error.
@@ -117,11 +195,11 @@ public function getValidRGB($value, Validator $validator = null)
                     "validation"
                 );
             }
-            return $this->defaultValue;
+            return false;
         }
 
-        // Let result be a simple color.
-        return $value;
+        // all tests pass
+        return true;
     }
 
     /**
@@ -132,10 +210,7 @@ public function getValidRGB($value, Validator $validator = null)
      */
     public function validate($validator)
     {
-        if(!$this->getValidRGB($this->value, $validator)) {
-            return false;
-        }
-        return true;
+        return $this->isValidRGB($this->Value(), $validator);
     }
 
 }

src/Forms/DateField.php

@@ -16,23 +16,41 @@ class DateField extends TextField
     use Step;
     use MinMax;
 
+    /**
+     * @inheritdoc
+     */
     protected $inputType = 'date';
 
+    /**
+     * @var string
+     */
     protected $datetime_format = "Y-m-d";
 
+    /**
+     * @var string
+     */
     protected $example = "2020-12-31";
 
-    protected function formatDate(\Datetime $datetime)
+    /**
+     * Format a date based on the field's formatr string
+     */
+    protected function formatDate(\Datetime $datetime) : string
     {
         return $datetime->format($this->datetime_format);
     }
 
-    public function setMin(\DateTime $min)
+    /**
+     * Set minimum accepted date
+     */
+    public function setMin(\DateTime $min) : self
     {
         return $this->setAttribute('min', $this->formatDate($min));
     }
 
-    public function setMax(\DateTime $max)
+    /**
+     * Set maximum accepted date
+     */
+    public function setMax(\DateTime $max) : self
     {
         return $this->setAttribute('max', $this->formatDate($max));
     }
@@ -47,25 +65,27 @@ public function setMax(\DateTime $max)
     public function validate($validator)
     {
         try {
-            $this->value = trim($this->value);
-            $dt = new \Datetime($this->value);
+            $value = trim($this->Value() ?? '');
+            if($value === '') {
+                // empty values are valid
+                return true;
+            }
+            $dt = new \Datetime($value);
             $formatted = $this->formatDate($dt);
-            if($formatted != $this->value) {
+            if($formatted != $value) {
                 throw new \Exception("Invalid date value passed");
             }
             return true;
         } catch (\Exception $e) {
             $validator->validationError(
                 $this->name,
-                sprintf(
-                    _t(
-                        'Codem\\Utilities\\HTML5\\DateField.VALIDATION',
-                        'Please enter a valid date in the format {format} (example:{example})',
-                        [
-                            'format' => $this->datetime_format,
-                            'example' => $this->example
-                        ]
-                    )
+                _t(
+                    'Codem\\Utilities\\HTML5\\DateField.VALIDATION',
+                    'Please enter a valid date in the format {format} (example:{example})',
+                    [
+                        'format' => $this->datetime_format,
+                        'example' => $this->example
+                    ]
                 ),
                 'validation'
             );

src/Forms/DatetimeField.php

@@ -10,10 +10,20 @@
 class DatetimeField extends DateField
 {
 
+    /**
+     * @inheritdoc
+     */
     protected $inputType = 'datetime-local';
 
+    /**
+     * @var string
+     * The browser will always send the datetime in this format
+     */
     protected $datetime_format = "Y-m-d\TH:i";
 
+    /**
+     * @var string
+     */
     protected $example = "2020-12-31T14:45";
 
 }

src/Forms/NumberField.php

@@ -27,17 +27,20 @@ class NumberField extends TextField
      */
     public function validate($validator)
     {
-        $this->value = trim($this->value);
-
-        if (!is_numeric($this->value)) {
+        $value = trim($this->Value() ?? '');
+        if($value === '') {
+            // empty values are valid
+            return true;
+        } else if (!is_numeric($value)) {
             $validator->validationError(
                 $this->name,
                 _t('Codem\\Utilities\\HTML5\\NumberField.VALIDATION', 'Please enter a number value'),
                 'validation'
             );
             return false;
+        } else {
+            return true;
         }
-        return true;
     }
 
 }