# copyright 2003-2012 LOGILAB S.A. (Paris, FRANCE), all rights reserved.

# contact http://www.logilab.fr/ -- mailto:contact@logilab.fr

#

# This file is part of CubicWeb.

#

# CubicWeb is free software: you can redistribute it and/or modify it under the

# terms of the GNU Lesser General Public License as published by the Free

# Software Foundation, either version 2.1 of the License, or (at your option)

# any later version.

#

# CubicWeb is distributed in the hope that it will be useful, but WITHOUT

# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS

# FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more

# details.

#

# You should have received a copy of the GNU Lesser General Public License along

# with CubicWeb.  If not, see <http://www.gnu.org/licenses/>.

"""

The Field class and basic fields

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. 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 concrete 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.BigIntField()

.. 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()

.. autoclass:: cubicweb.web.formfields.TimeIntervalField()

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, timedelta

from logilab.mtconverter import xml_escape

from logilab.common import nullobject

from logilab.common.date import ustrftime

from logilab.common.configuration import format_time

from logilab.common.textutils import apply_units, TIME_UNITS

from yams.schema import KNOWN_METAATTRIBUTES, role_name

from yams.constraints import (SizeConstraint, StaticVocabularyConstraint,

                              FormatConstraint)

from cubicweb import Binary, tags, uilib

from cubicweb.utils import support_args

from cubicweb.web import INTERNAL_FIELD_VALUE, ProcessFormError, eid_param, \

     formwidgets as fw, uicfg

class UnmodifiedField(Exception):

    """raise this when a field has not actually been edited and you want to skip

    it

    """

def normalize_filename(filename):

    return filename.split('\\')[-1]

def vocab_sort(vocab):

    """sort vocabulary, considering option groups"""

    result = []

    partresult = []

    for label, value in vocab:

        if value is None: # opt group start

            if partresult:

                result += sorted(partresult)

                partresult = []

            result.append( (label, value) )

        else:

            partresult.append( (label, value) )

    result += sorted(partresult)

    return result

_MARKER = nullobject()

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

    concrete field.

    **Attributes**

    All the attributes described below have sensible default value which may be

    overriden by named arguments given to field's constructor.

    :attr:`name`

       base name of the field (basestring). The actual input name is returned by

       the :meth:`input_name` method and may differ from that name (for instance

       if `eidparam` is true).

    :attr:`id`

       DOM identifier (default to the same value as `name`), should be unique in

       a form.

    :attr:`label`

       label of the field (default to the same value as `name`).

    :attr:`help`

       help message about this field.

    :attr:`widget`

       widget associated to the field. Each field class has a default widget

       class which may be overriden per instance.

    :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.

    :attr:`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.

    :attr:`internationalizable`

       bool flag telling if the vocabulary labels should be translated using the

       current request language.

    :attr:`eidparam`

       bool flag telling if this field is linked to a specific entity

    :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'). If this is

       not an attribute or relation of the edited entity, `role` should be

       `None`.

    :attr:`fieldset`

       optional fieldset to which this field belongs to

    :attr:`order`

       key used by automatic forms to sort fields

    :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

    needs_multipart = False

    # class attribute used for ordering of fields in a form

    __creation_rank = 0

    eidparam = False

    role = None

    id = None

    help = None

    required = False

    choices = None

    sort = True

    internationalizable = False

    fieldset = None

    order = None

    value = _MARKER

    fallback_on_none_attribute = False

    ignore_req_params = False

    def __init__(self, name=None, label=_MARKER, widget=None, **kwargs):

        for key, val in kwargs.items():

            assert hasattr(self.__class__, key) and not key[0] == '_', key

            setattr(self, key, val)

        self.name = name

        if label is _MARKER:

            label = name or _MARKER

        self.label = label

        # has to be done after other attributes initialization

        self.init_widget(widget)

        # ordering number for this field instance

        self.creation_rank = Field.__creation_rank

        Field.__creation_rank += 1

    def as_string(self, repr=True):

        l = [u'<%s' % self.__class__.__name__]

        for attr in ('name', 'eidparam', 'role', 'id', 'value'):

            value = getattr(self, attr)

            if value is not None and value is not _MARKER:

                l.append('%s=%r' % (attr, value))

        if repr:

            l.append('@%#x' % id(self))

        return u'%s>' % ' '.join(l)

    def __unicode__(self):

        return self.as_string(False)

    def __str__(self):

        return self.as_string(False).encode('UTF8')

    def __repr__(self):

        return self.as_string(True).encode('UTF8')

    def init_widget(self, widget):

        if widget is not None:

            self.widget = widget

        elif self.choices and not self.widget.vocabulary_widget:

            self.widget = fw.Select()

        if isinstance(self.widget, type):

            self.widget = self.widget()

    def set_name(self, name):

        """automatically set .label when name is set"""

        assert name

        self.name = name

        if self.label is _MARKER:

            self.label = name

    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):

        """Fields may be composed of other fields. For instance the

        :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

        of values

        """

        if isinstance(value, (list, tuple)):

            return [self.format_single_value(req, val) for val in value]

        return self.format_single_value(req, value)

    def format_single_value(self, req, value):

        """return value suitable for display"""

        if value is None or value is False:

            return u''

        if value is True:

            return u'1'

        return unicode(value)

    def get_widget(self, form):

        """return the widget instance associated to this field"""

        return self.widget

    def input_name(self, form, suffix=None):

        """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).

        #

        # note that you should NOT use @cached else it will create a memory leak

        # on persistent fields (eg created once for all on a form class) because

        # of the 'form' appobject argument: the cache will keep growing as new

        # form are created...

        try:

            return form.formvalues[(self, 'input_name', suffix)]

        except KeyError:

            name = self.role_name()

            if suffix is not None:

                name += suffix

            if self.eidparam:

                name = eid_param(name, form.edited_entity.eid)

            form.formvalues[(self, 'input_name', suffix)] = name

            return name

    def role_name(self):

        """return <field.name>-<field.role> if role is specified, else field.name"""

        if self.role is not None:

            return role_name(self.name, self.role)

        return self.name

    def dom_id(self, form, suffix=None):

        """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.cw_attr_cache:

                    value = getattr(entity, self.name)

                    if value is not None or not self.fallback_on_none_attribute:

                        return value

            elif entity.has_eid() or entity.cw_relation_cached(self.name, self.role):

                value = [r[0] for r in entity.related(self.name, self.role)]

                if value or not self.fallback_on_none_attribute:

                    return value

        return self.initial_typed_value(form, load_bytes)

    def initial_typed_value(self, form, load_bytes):

        if self.value is not _MARKER:

            if callable(self.value):

                # pylint: disable=E1102

                if support_args(self.value, 'form', 'field'):

                    return self.value(form, self)

                else:

                    warn("[3.10] field's value callback must now take form and "

                         "field as argument (%s)" % self, DeprecationWarning)

                    return self.value(form)

            return self.value

        formattr = '%s_%s_default' % (self.role, self.name)

        if self.eidparam and self.role is not None:

            if form._cw.vreg.schema.rschema(self.name).final:

                return form.edited_entity.e_schema.default(self.name)

            return ()

        return None

    def example_format(self, req):

        """return a sample string describing what can be given as input for this

        field

        """

        return u''

    def render(self, form, renderer):

        """render this field, which is part of form, using the given form

        renderer

        """

        widget = self.get_widget(form)

        return widget.render(form, self, renderer)

    def vocabulary(self, form, **kwargs):

        """return vocabulary for this field. This method will be

        called by widgets which requires a vocabulary.

        It should return a list of tuple (label, value), where value

        *must be an unicode string*, not a typed value.

        """

        assert self.choices is not None

        if callable(self.choices):

            # pylint: disable=E1102

            if getattr(self.choices, 'im_self', None) is self:

                vocab = self.choices(form=form, **kwargs)

            else:

                vocab = self.choices(form=form, field=self, **kwargs)

        else:

            vocab = self.choices

        if vocab and not isinstance(vocab[0], (list, tuple)):

            vocab = [(x, x) for x in vocab]

        if self.internationalizable:

            # the short-cirtcuit 'and' boolean operator is used here