cubicweb: comparison web/formfields.py

equal deleted inserted replaced

-:4176a50c81c9
+:d321e4b62a10
-"""Fields are used to control what's displayed in forms. It makes the link
+# organization: Logilab
-between something to edit and its display in the form. Actual display is handled
+# copyright: 2009-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.
-by a widget associated to the field.
+# contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
+# license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses
-:organization: Logilab
+"""
-:copyright: 2009-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.
+The Field class and basic fields
-:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-:license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses
+.. Note::
+Fields are used to control what's edited in forms. They makes the link between
+something to edit and its display in the form. Actual display is handled by a
+widget associated to the field.
+Let first see the base class for fields:
+.. autoclass:: cubicweb.web.formfields.Field
+Now, you usually don't use that class but one of the concret field classes
+described below, according to what you want to edit.
+Basic fields
+''''''''''''
+.. autoclass:: cubicweb.web.formfields.StringField()
+.. autoclass:: cubicweb.web.formfields.PasswordField()
+.. autoclass:: cubicweb.web.formfields.IntField()
+.. autoclass:: cubicweb.web.formfields.FloatField()
+.. autoclass:: cubicweb.web.formfields.BooleanField()
+.. autoclass:: cubicweb.web.formfields.DateField()
+.. autoclass:: cubicweb.web.formfields.DateTimeField()
+.. autoclass:: cubicweb.web.formfields.TimeField()
+Compound fields
+''''''''''''''''
+.. autoclass:: cubicweb.web.formfields.RichTextField()
+.. autoclass:: cubicweb.web.formfields.FileField()
+.. autoclass:: cubicweb.web.formfields.CompoundField()
+.. autoclass cubicweb.web.formfields.EditableFileField() XXX should be a widget
+Entity specific fields and function
+'''''''''''''''''''''''''''''''''''
+.. autoclass:: cubicweb.web.formfields.RelationField()
+.. autofunction:: cubicweb.web.formfields.guess_field
 """
 __docformat__ = "restructuredtext en"
 from warnings import warn
 from datetime import datetime
 class Field(object):
 """This class is the abstract base class for all fields. It hold a bunch
 of attributes which may be used for fine control of the behaviour of a
 concret field.
+**Attributes**
 All the attributes described below have sensible default value which may be
-overriden by value given to field's constructor.
+overriden by named arguments given to field's constructor.
-:name:
+:attr:`name`
-name of the field (basestring), should be unique in a form.
+base name of the field (basestring). The actual input name is returned by
-:id:
+the :meth:`input_name` method and may differ from that name (for instance
-dom identifier (default to the same value as `name`), should be unique in
+if `eidparam` is true).
+:attr:`id`
+DOM identifier (default to the same value as `name`), should be unique in
 a form.
-:label:
+:attr:`label`
 label of the field (default to the same value as `name`).
-:help:
+:attr:`help`
 help message about this field.
-:widget:
+:attr:`widget`
 widget associated to the field. Each field class has a default widget
 class which may be overriden per instance.
-:required:
+:attr:`value`
+field value. May be an actual value or a callable which should take the
+form as argument and return a value.
+:attr:`choices`
+static vocabulary for this field. May be a list of values, a list of
+(label, value) tuples or a callable which should take the form and field
+as arguments and return a list of values or a list of (label, value).
+:attr:`required`
 bool flag telling if the field is required or not.
-:value:
+:attr:`sort`
-field value (may be an actual value, a default value or nothing)
-:choices:
-static vocabulary for this field. May be a list of values or a list of
-(label, value) tuples if specified.
-:sort:
 bool flag telling if the vocabulary (either static vocabulary specified
 in `choices` or dynamic vocabulary fetched from the form) should be
 sorted on label.
-:internationalizable:
+:attr:`internationalizable`
 bool flag telling if the vocabulary labels should be translated using the
 current request language.
-:eidparam:
+:attr:`eidparam`
 bool flag telling if this field is linked to a specific entity
-:role:
+:attr:`role`
 when the field is linked to an entity attribute or relation, tells the
 role of the entity in the relation (eg 'subject' or 'object')
-:fieldset:
+:attr:`fieldset`
 optional fieldset to which this field belongs to
-:order:
+:attr:`order`
 key used by automatic forms to sort fields
-:ignore_req_params:
+:attr:`ignore_req_params`
 when true, this field won't consider value potentialy specified using
 request's form parameters (eg you won't be able to specify a value using for
 instance url like http://mywebsite.com/form?field=value)
+.. currentmodule:: cubicweb.web.formfields
+**Generic methods**
+.. automethod:: Field.input_name
+.. automethod:: Field.dom_id
+.. automethod:: Field.actual_fields
+**Form generation methods**
+.. automethod:: form_init
+.. automethod:: typed_value
+**Post handling methods**
+.. automethod:: process_posted
+.. automethod:: process_form_value
 """
 # default widget associated to this class of fields. May be overriden per
 # instance
 widget = fw.TextInput
 # does this field requires a multipart form
 def is_visible(self):
 """return true if the field is not an hidden field"""
 return not isinstance(self.widget, fw.HiddenInput)
 def actual_fields(self, form):
-"""return actual fields composing this field in case of a compound
+"""Fields may be composed of other fields. For instance the
-field, usually simply return self
+:class:`~cubicweb.web.formfields.RichTextField` is containing a format
+field to define the text format. This method returns actual fields that
+should be considered for display / edition. It usually simply return
+self.
 """
 yield self
 def format_value(self, req, value):
 """return value suitable for display where value may be a list or tuple
 def get_widget(self, form):
 """return the widget instance associated to this field"""
 return self.widget
 def input_name(self, form, suffix=None):
-"""return 'qualified name' for this field"""
+"""Return the 'qualified name' for this field, e.g. something suitable
+to use as HTML input name. You can specify a suffix that will be
+included in the name when widget needs several inputs.
+"""
 # caching is necessary else we get some pb on entity creation :
 # entity.eid is modified from creation mark (eg 'X') to its actual eid
 # (eg 123), and then `field.input_name()` won't return the right key
 # anymore if not cached (first call to input_name done *before* eventual
 # eid affectation).
 if self.role is not None:
 return role_name(self.name, self.role)
 return self.name
 def dom_id(self, form, suffix=None):
-"""return an html dom identifier for this field"""
+"""Return the HTML DOM identifier for this field, e.g. something
+suitable to use as HTML input id. You can specify a suffix that will be
+included in the name when widget needs several inputs.
+"""
 id = self.id or self.role_name()
 if suffix is not None:
 id += suffix
 if self.eidparam:
 return eid_param(id, form.edited_entity.eid)
 return id
 def typed_value(self, form, load_bytes=False):
+"""Return the correctly typed value for this field in the form context.
+"""
 if self.eidparam and self.role is not None:
 entity = form.edited_entity
 if form._cw.vreg.schema.rschema(self.name).final:
 if entity.has_eid() or self.name in entity:
 value = getattr(entity, self.name)
 entity.has_eid() or '%s_encoding' % self.name in entity):
 return form.edited_entity.attr_metadata(self.name, 'encoding')
 return form._cw.encoding
 def form_init(self, form):
-"""method called before by build_context to trigger potential field
+"""Method called at form initialization to trigger potential field
-initialization requiring the form instance
+initialization requiring the form instance. Do nothing by default.
 """
 pass
 def has_been_modified(self, form):
 # fields not corresponding to an entity attribute / relations
 if previous_value == new_value:
 return False # not modified
 return True
 def process_form_value(self, form):
-"""process posted form and return correctly typed value"""
+"""Return the correctly typed value posted for this field."""
 try:
 return form.formvalues[(self, form)]
 except KeyError:
 value = form.formvalues[(self, form)] = self._process_form_value(form)
 return value
 Override this method to type the value if necessary
 """
 return value or None
 def process_posted(self, form):
+"""Return an iterator on (field, value) that has been posted for
+field returned by :meth:`~cubicweb.web.formfields.Field.actual_fields`.
+"""
 for field in self.actual_fields(form):
 if field is self:
 try:
 value = field.process_form_value(form)
 if value is None and field.required:
 for field, value in field.process_posted(form):
 yield field, value
 class StringField(Field):
+"""Use this field to edit unicode string (`String` yams type). This field
+additionaly support a `max_length` attribute that specify a maximum size for
+the string (`None` meaning no limit).
+Unless explicitly specified, the widget for this field will be:
+* :class:`~cubicweb.web.formwidgets.Select` if some vocabulary is specified
+using `choices` attribute
+* :class:`~cubicweb.web.formwidgets.TextInput` if maximum size is specified
+using `max_length` attribute and this length is inferior to 257.
+* :class:`~cubicweb.web.formwidgets.TextArea` in all other cases
+"""
 widget = fw.TextArea
 size = 45
 def __init__(self, name=None, max_length=None, **kwargs):
 self.max_length = max_length # must be set before super call
 widget.attrs.setdefault('cols', 60)
 widget.attrs.setdefault('rows', 5)
 class PasswordField(StringField):
+"""Use this field to edit password (`Password` yams type, encoded python
+string).
+Unless explicitly specified, the widget for this field will be
+a :class:`~cubicweb.web.formwidgets.PasswordInput`.
+"""
 widget = fw.PasswordInput
 def form_init(self, form):
 if self.eidparam and form.edited_entity.has_eid():
 # see below: value is probably set but we can't retreive it. Ensure
 # the field isn't show as a required field on modification
 return self.initial_typed_value(form, load_bytes)
 return super(PasswordField, self).typed_value(form, load_bytes)
 class RichTextField(StringField):
+"""This compound field allow edition of text (unicode string) in
+a particular format. It has an inner field holding the text format,
+that can be specified using `format_field` argument. If not specified
+one will be automaticall generated.
+Unless explicitly specified, the widget for this field will be a
+:class:`~cubicweb.web.formwidgets.FCKEditor` or a
+:class:`~cubicweb.web.formwidgets.TextArea`. according to the field's
+format and to user's preferences.
+"""
 widget = None
 def __init__(self, format_field=None, **kwargs):
 super(RichTextField, self).__init__(**kwargs)
 self.format_field = format_field
 result = u''
 return result + self.get_widget(form).render(form, self, renderer)
 class FileField(StringField):
+"""This compound field allow edition of binary stream (`Bytes` yams
+type). Three inner fields may be specified:
+* `format_field`, holding the file's format.
+* `encoding_field`, holding the file's content encoding.
+* `name_field`, holding the file's name.
+Unless explicitly specified, the widget for this field will be a
+:class:`~cubicweb.web.formwidgets.FileInput`. Inner fields, if any,
+will be added to a drop down menu at the right of the file input.
+"""
 widget = fw.FileInput
 needs_multipart = True
 def __init__(self, format_field=None, encoding_field=None, name_field=None,
 **kwargs):
 return value
 # XXX turn into a widget
 class EditableFileField(FileField):
+"""This compound field allow edition of binary stream as
+:class:`~cubicweb.web.formfields.FileField` but expect that stream to
+actually contains some text.
+If the stream format is one of text/plain, text/html, text/rest,
+then a :class:`~cubicweb.web.formwidgets.TextArea` will be additionaly
+displayed, allowing to directly the file's content when desired, instead
+of choosing a file from user's file system.
+"""
 editable_formats = ('text/plain', 'text/html', 'text/rest')
 def render(self, form, renderer):
 wdgs = [super(EditableFileField, self).render(form, renderer)]
 if self.format(form) in self.editable_formats:
 return Binary(value.encode(self.encoding(form)))
 return super(EditableFileField, self)._process_form_value(form)
 class IntField(Field):
+"""Use this field to edit integers (`Int` yams type). This field additionaly
+support `min` and `max` attributes that specify a minimum and/or maximum
+value for the integer (`None` meaning no boundary).
+Unless explicitly specified, the widget for this field will be a
+:class:`~cubicweb.web.formwidgets.TextInput`.
+"""
 def __init__(self, min=None, max=None, **kwargs):
 super(IntField, self).__init__(**kwargs)
 self.min = min
 self.max = max
 if isinstance(self.widget, fw.TextInput):
 raise ProcessFormError(form._cw._('an integer is expected'))
 return value
 class BooleanField(Field):
+"""Use this field to edit booleans (`Boolean` yams type).
+Unless explicitly specified, the widget for this field will be a
+:class:`~cubicweb.web.formwidgets.Radio` with yes/no values. You
+can change that values by specifing `choices`.
+"""
 widget = fw.Radio
 def vocabulary(self, form):
 if self.choices:
 return super(BooleanField, self).vocabulary(form)
 def _ensure_correctly_typed(self, form, value):
 return bool(value)
 class FloatField(IntField):
+"""Use this field to edit floats (`Float` yams type). This field additionaly
+support `min` and `max` attributes as the
+:class:`~cubicweb.web.formfields.IntField`.
+Unless explicitly specified, the widget for this field will be a
+:class:`~cubicweb.web.formwidgets.TextInput`.
+"""
 def format_single_value(self, req, value):
 formatstr = req.property_value('ui.float-format')
 if value is None:
 return u''
 return formatstr % float(value)
 raise ProcessFormError(form._cw._('a float is expected'))
 return None
 class DateField(StringField):
+"""Use this field to edit date (`Date` yams type).
+Unless explicitly specified, the widget for this field will be a
+:class:`~cubicweb.web.formwidgets.JQueryDatePicker`.
+"""
 widget = fw.JQueryDatePicker
 format_prop = 'ui.date-format'
 etype = 'Date'
 def format_single_value(self, req, value):
 raise ProcessFormError(unicode(ex))
 return value
 class DateTimeField(DateField):
+"""Use this field to edit datetime (`Datetime` yams type).
+Unless explicitly specified, the widget for this field will be a
+:class:`~cubicweb.web.formwidgets.JQueryDateTimePicker`.
+"""
 widget = fw.JQueryDateTimePicker
 format_prop = 'ui.datetime-format'
 etype = 'Datetime'
 class TimeField(DateField):
+"""Use this field to edit time (`Time` yams type).
+Unless explicitly specified, the widget for this field will be a
+:class:`~cubicweb.web.formwidgets.JQueryTimePicker`.
+"""
 widget = fw.JQueryTimePicker
 format_prop = 'ui.time-format'
 etype = 'Time'
+# XXX use cases where we don't actually want a better widget?
+class CompoundField(Field):
+"""This field shouldn't be used directly, it's designed to hold inner
+fields that should be conceptually groupped together.
+"""
+def __init__(self, fields, *args, **kwargs):
+super(CompoundField, self).__init__(*args, **kwargs)
+self.fields = fields
+def subfields(self, form):
+return self.fields
+def actual_fields(self, form):
+# don't add [self] to actual fields, compound field is usually kinda
+# virtual, all interesting values are in subfield. Skipping it may avoid
+# error when processed by the editcontroller : it may be marked as required
+# while it has no value, hence generating a false error.
+return list(self.fields)
 # relation vocabulary helper functions #########################################
 def relvoc_linkedto(entity, rtype, role):
 res.append((entity.view('combobox'), entity.eid))
 return res
 class RelationField(Field):
-"""the relation field to edit non final relations of an entity"""
+"""Use this field to edit a relation of an entity.
+Unless explicitly specified, the widget for this field will be a
+:class:`~cubicweb.web.formwidgets.Select`.
+"""
 @staticmethod
 def fromcardinality(card, **kwargs):
 kwargs.setdefault('widget', fw.Select(multiple=card in '*+'))
 return RelationField(**kwargs)
 form._cw.data['pendingfields'].add( (form, self) )
 return None
 eids.add(typed_eid)
 return eids
-# XXX use cases where we don't actually want a better widget?
-class CompoundField(Field):
-def __init__(self, fields, *args, **kwargs):
-super(CompoundField, self).__init__(*args, **kwargs)
-self.fields = fields
-def subfields(self, form):
-return self.fields
-def actual_fields(self, form):
-# don't add [self] to actual fields, compound field is usually kinda
-# virtual, all interesting values are in subfield. Skipping it may avoid
-# error when processed by the editcontroller : it may be marked as required
-# while it has no value, hence generating a false error.
-return list(self.fields)
 _AFF_KWARGS = uicfg.autoform_field_kwargs
 def guess_field(eschema, rschema, role='subject', skip_meta_attr=True, **kwargs):
-"""return the most adapated widget to edit the relation
+"""This function return the most adapted field to edit the given relation
-'subjschema rschema objschema' according to information found in the schema
+(`rschema`) where the given entity type (`eschema`) is the subject or object
+(`role`).
+The field is initialized according to information found in the schema,
+though any value can be explicitly specified using `kwargs`.
+The `skip_meta_attr` flag is used to specify wether this function should
+return a field for attributes considered as a meta-attributes
+(e.g. describing an other attribute, such as the format or file name of a
+file (`Bytes`) attribute).
 """
 fieldclass = None
 rdef = eschema.rdef(rschema, role)
 if role == 'subject':
 targetschema = rdef.object

branch	stable
changeset 5368	d321e4b62a10
parent 5367	4176a50c81c9
child 5385	b6e250dd7a7d
child 5421	8167de96c523