===================== Hint (title) Adapters ===================== A widget can provide a hint. Hints are not a standard concept, the implementations can be very different in each project. Hints are most of the time implemented with JavaScript since the default ``input title`` hint in browsers are almost unusable. Our hint support is limited and only offers some helpers. Which means we will offer an adapter that shows the schema field description as the title. Since this is very specific we only provide a ``FieldDescriptionAsHint`` adapter which you can configure as a named IValue adapter. >>> import zope.interface >>> import zope.component >>> from z3c.form import form >>> from z3c.form import field >>> from z3c.form import hint We also need to setup the form defaults: >>> from z3c.form import testing >>> testing.setupFormDefaults() Let's create a couple of simple widgets and forms first: >>> class IContent(zope.interface.Interface): ... ... textLine = zope.schema.TextLine( ... title=u'Title', ... description=u'A TextLine description') ... ... anotherLine = zope.schema.TextLine( ... title=u'Other') >>> class Content(object): ... zope.interface.implements(IContent) ... ... textLine = None ... otherLine = None ... >>> content = Content() >>> from z3c.form.testing import TestRequest >>> request = TestRequest() >>> class HintForm(form.Form): ... fields = field.Fields(IContent) >>> hintForm = HintForm(content, request) As you can see, there is no title value set for our widgets: >>> hintForm.update() >>> print hintForm.widgets['textLine'].render() >>> print hintForm.widgets['anotherLine'].render() Let's configure our IValue ``hint`` adapter: >>> from z3c.form.hint import FieldDescriptionAsHint >>> zope.component.provideAdapter(FieldDescriptionAsHint, name='title') If we update our form, we can see that the title is used based on the schema field description: >>> hintForm.update() >>> print hintForm.widgets['textLine'].render() If the field has no description as it is with the second one, no "title" will be set for the widget: >>> print hintForm.widgets['anotherLine'].render() Check all fields ---------------- Just to make sure that all the widgets are handled correctly, we will go through all of them. This sample can be useful if you need to implement a JavaScript based hint concept: >>> import datetime >>> import decimal >>> from zope.schema import vocabulary Let's setup a simple vocabulary: >>> vocab = vocabulary.SimpleVocabulary([ ... vocabulary.SimpleVocabulary.createTerm(1, '1', u'One'), ... vocabulary.SimpleVocabulary.createTerm(2, '2', u'Two'), ... vocabulary.SimpleVocabulary.createTerm(3, '3', u'Three'), ... vocabulary.SimpleVocabulary.createTerm(4, '4', u'Four'), ... vocabulary.SimpleVocabulary.createTerm(5, '5', u'Five') ... ]) >>> class IAllInOne(zope.interface.Interface): ... ... asciiField = zope.schema.ASCII( ... title=u'ASCII', ... description=u'This is an ASCII field.', ... default='This is\n ASCII.') ... ... asciiLineField = zope.schema.ASCIILine( ... title=u'ASCII Line', ... description=u'This is an ASCII-Line field.', ... default='An ASCII line.') ... ... boolField = zope.schema.Bool( ... title=u'Boolean', ... description=u'This is a Bool field.', ... default=True) ... ... checkboxBoolField = zope.schema.Bool( ... title=u'Boolean (Checkbox)', ... description=u'This is a Bool field displayed suing a checkbox.', ... default=True) ... ... bytesLineField = zope.schema.BytesLine( ... title=u'Bytes Line', ... description=u'This is a bytes line field.', ... default='A Bytes line.') ... ... choiceField = zope.schema.Choice( ... title=u'Choice', ... description=u'This is a choice field.', ... default=3, ... vocabulary=vocab) ... ... optionalChoiceField = zope.schema.Choice( ... title=u'Choice (Not Required)', ... description=u'This is a non-required choice field.', ... vocabulary=vocab, ... required=False) ... ... promptChoiceField = zope.schema.Choice( ... title=u'Choice (Explicit Prompt)', ... description=u'This is a choice field with an explicit prompt.', ... vocabulary=vocab, ... required=False) ... ... dateField = zope.schema.Date( ... title=u'Date', ... description=u'This is a Date field.', ... default=datetime.date(2007, 4, 1)) ... ... datetimeField = zope.schema.Datetime( ... title=u'Date/Time', ... description=u'This is a Datetime field.', ... default=datetime.datetime(2007, 4, 1, 12)) ... ... decimalField = zope.schema.Decimal( ... title=u'Decimal', ... description=u'This is a Decimal field.', ... default=decimal.Decimal('12.87')) ... ... dottedNameField = zope.schema.DottedName( ... title=u'Dotted Name', ... description=u'This is a DottedName field.', ... default='z3c.form') ... ... floatField = zope.schema.Float( ... title=u'Float', ... description=u'This is a Float field.', ... default=12.8) ... ... frozenSetField = zope.schema.FrozenSet( ... title=u'Frozen Set', ... description=u'This is a FrozenSet field.', ... value_type=choiceField, ... default=frozenset([1, 3]) ) ... ... idField = zope.schema.Id( ... title=u'Id', ... description=u'This is a Id field.', ... default='z3c.form') ... ... intField = zope.schema.Int( ... title=u'Integer', ... description=u'This is a Int field.', ... default=12345) ... ... listField = zope.schema.List( ... title=u'List', ... description=u'This is a List field.', ... value_type=choiceField, ... default=[1, 3]) ... ... passwordField = zope.schema.Password( ... title=u'Password', ... description=u'This is a Password field.', ... default=u'mypwd', ... required=False) ... ... setField = zope.schema.Set( ... title=u'Set', ... description=u'This is a Set field.', ... value_type=choiceField, ... default=set([1, 3]) ) ... ... sourceTextField = zope.schema.SourceText( ... title=u'Source Text', ... description=u'This is a SourceText field.', ... default=u'') ... ... textField = zope.schema.Text( ... title=u'Text', ... description=u'This is a Text field.', ... default=u'Some\n Text.') ... ... textLineField = zope.schema.TextLine( ... title=u'Text Line', ... description=u'This is a TextLine field.', ... default=u'Some Text line.') ... ... timeField = zope.schema.Time( ... title=u'Time', ... description=u'This is a Time field.', ... default=datetime.time(12, 0)) ... ... timedeltaField = zope.schema.Timedelta( ... title=u'Time Delta', ... description=u'This is a Timedelta field.', ... default=datetime.timedelta(days=3)) ... ... tupleField = zope.schema.Tuple( ... title=u'Tuple', ... description=u'This is a Tuple field.', ... value_type=choiceField, ... default=(1, 3)) ... ... uriField = zope.schema.URI( ... title=u'URI', ... description=u'This is a URI field.', ... default='http://zope.org') ... ... hiddenField = zope.schema.TextLine( ... title=u'Hidden Text Line', ... description=u'This is a hidden TextLine field.', ... default=u'Some Hidden Text.') >>> class AllInOne(object): ... zope.interface.implements(IAllInOne) ... ... asciiField = None ... asciiLineField = None ... boolField = None ... checkboxBoolField = None ... choiceField = None ... optionalChoiceField = None ... promptChoiceField = None ... dateField = None ... decimalField = None ... dottedNameField = None ... floatField = None ... frozenSetField = None ... idField = None ... intField = None ... listField = None ... passwordField = None ... setField = None ... sourceTextField = None ... textField = None ... textLineField = None ... timeField = None ... timedeltaField = None ... tupleField = None ... uriField = None ... hiddenField = None >>> allInOne = AllInOne() >>> class AllInOneForm(form.Form): ... fields = field.Fields(IAllInOne) Now test the hints in our widgets: >>> allInOneForm = AllInOneForm(allInOne, request) >>> allInOneForm.update() >>> print allInOneForm.widgets['asciiField'].render() >>> print allInOneForm.widgets['asciiLineField'].render() >>> print allInOneForm.widgets['boolField'].render() >>> print allInOneForm.widgets['checkboxBoolField'].render() >>> print allInOneForm.widgets['bytesLineField'].render() >>> print allInOneForm.widgets['choiceField'].render() >>> print allInOneForm.widgets['optionalChoiceField'].render() >>> print allInOneForm.widgets['promptChoiceField'].render() >>> print allInOneForm.widgets['dateField'].render() >>> print allInOneForm.widgets['datetimeField'].render() >>> print allInOneForm.widgets['decimalField'].render() >>> print allInOneForm.widgets['dottedNameField'].render() >>> print allInOneForm.widgets['floatField'].render() >>> print allInOneForm.widgets['frozenSetField'].render() >>> print allInOneForm.widgets['idField'].render() >>> print allInOneForm.widgets['intField'].render() >>> print allInOneForm.widgets['listField'].render() >>> print allInOneForm.widgets['passwordField'].render() >>> print allInOneForm.widgets['setField'].render() >>> print allInOneForm.widgets['sourceTextField'].render() >>> print allInOneForm.widgets['textField'].render() >>> print allInOneForm.widgets['textLineField'].render() >>> print allInOneForm.widgets['timeField'].render() >>> print allInOneForm.widgets['timedeltaField'].render() >>> print allInOneForm.widgets['tupleField'].render() >>> print allInOneForm.widgets['uriField'].render() >>> print allInOneForm.widgets['hiddenField'].render()