Merge pull request #409 from wtforms/html5-field-docs

Added HTML5 field documentation

docs/fields.rst

@@ -319,6 +319,38 @@ refer to a single input from the form.
 
         {{ form.username(size=30, maxlength=50) }}
 
+HTML5 Fields
+------------
+
+In addition to basic HTML fields, WTForms also supplies fields for the HTML5
+standard. These fields can be accessed under the :mod:`wtforms.fields.html5` namespace.
+In reality, these fields are just convenience fields that extend basic fields
+and implement HTML5 specific widgets. These widgets are located in the :mod:`wtforms.widgets.html5`
+namespace and can be overridden or modified just like any other widget.
+
+.. autoclass:: SearchField(default field arguments)
+
+.. autoclass:: TelField(default field arguments)
+
+.. autoclass:: URLField(default field arguments)
+
+.. autoclass:: EmailField(default field arguments)
+
+.. autoclass:: DateTimeField(default field arguments,  format='%Y-%m-%d %H:%M:%S')
+
+.. autoclass:: DateField(default field arguments, format='%Y-%m-%d')
+
+.. autoclass:: TimeField(default field arguments, format='%H:%M')
+
+.. autoclass:: DateTimeLocalField(default field arguments, format='%Y-%m-%d %H:%M:%S')
+
+.. autoclass:: IntegerField(default field arguments)
+
+.. autoclass:: DecimalField(default field arguments)
+
+.. autoclass:: IntegerRangeField(default field arguments)
+
+.. autoclass:: DecimalRangeField(default field arguments)
 
 Convenience Fields
 ------------------

tests/test_fields.py

@@ -10,7 +10,7 @@
 
 from wtforms import validators, widgets, meta
 from wtforms.fields import *
-from wtforms.fields import Label, Field, SelectFieldBase, html5
+from wtforms.fields import Label, Field, SelectFieldBase
 from wtforms.form import Form
 from wtforms.compat import text_type
 from wtforms.utils import unset_value
@@ -469,9 +469,9 @@ def test(self):
         form = self.F(DummyPostData(a=['v'], b=['-15']))
         self.assertEqual(form.a.data, None)
         self.assertEqual(form.a.raw_data, ['v'])
-        self.assertEqual(form.a(), """<input id="a" name="a" type="text" value="v">""")
+        self.assertEqual(form.a(), """<input id="a" name="a" type="number" value="v">""")
         self.assertEqual(form.b.data, -15)
-        self.assertEqual(form.b(), """<input id="b" name="b" type="text" value="-15">""")
+        self.assertEqual(form.b(), """<input id="b" name="b" type="number" value="-15">""")
         self.assertTrue(not form.a.validate(form))
         self.assertTrue(form.b.validate(form))
         form = self.F(DummyPostData(a=[], b=['']))
@@ -617,9 +617,9 @@ def test_basic(self):
         # Basic test with both inputs
         form = self.F(DummyPostData(a=['4:30'], b=['04:30']))
         self.assertEqual(form.a.data, d)
-        self.assertEqual(form.a(), """<input id="a" name="a" type="text" value="4:30">""")
+        self.assertEqual(form.a(), """<input id="a" name="a" type="time" value="4:30">""")
         self.assertEqual(form.b.data, d)
-        self.assertEqual(form.b(), """<input id="b" name="b" type="text" value="04:30">""")
+        self.assertEqual(form.b(), """<input id="b" name="b" type="time" value="04:30">""")
         self.assertTrue(form.validate())
 
         # Test with a missing input
@@ -638,9 +638,9 @@ def test_basic(self):
         # Basic test with both inputs
         form = self.F(DummyPostData(a=['2008-05-05', '04:30:00'], b=['2008-05-05 04:30']))
         self.assertEqual(form.a.data, d)
-        self.assertEqual(form.a(), """<input id="a" name="a" type="text" value="2008-05-05 04:30:00">""")
+        self.assertEqual(form.a(), """<input id="a" name="a" type="datetime" value="2008-05-05 04:30:00">""")
         self.assertEqual(form.b.data, d)
-        self.assertEqual(form.b(), """<input id="b" name="b" type="text" value="2008-05-05 04:30">""")
+        self.assertEqual(form.b(), """<input id="b" name="b" type="datetime" value="2008-05-05 04:30">""")
         self.assertTrue(form.validate())
 
         # Test with a missing input
@@ -900,17 +900,17 @@ def test_default_impls(self):
 
 class HTML5FieldsTest(TestCase):
     class F(Form):
-        search = html5.SearchField()
-        telephone = html5.TelField()
-        url = html5.URLField()
-        email = html5.EmailField()
-        datetime = html5.DateTimeField()
-        date = html5.DateField()
-        dt_local = html5.DateTimeLocalField()
-        integer = html5.IntegerField()
-        decimal = html5.DecimalField()
-        int_range = html5.IntegerRangeField()
-        decimal_range = html5.DecimalRangeField()
+        search = SearchField()
+        telephone = TelField()
+        url = URLField()
+        email = EmailField()
+        datetime = DateTimeField()
+        date = DateField()
+        dt_local = DateTimeLocalField()
+        integer = IntegerField()
+        decimal = DecimalField()
+        int_range = IntegerRangeField()
+        decimal_range = DecimalRangeField()
 
     def _build_value(self, key, form_input, expected_html, data=unset_value):
         if data is unset_value:

wtforms/fields/__init__.py

@@ -2,6 +2,8 @@
 
 from wtforms.fields.simple import *
 
+from wtforms.fields.html5 import *
+
 # Compatibility imports
 from wtforms.fields.core import Label, Field, SelectFieldBase, Flags
 from wtforms.utils import unset_value as _unset_value