1 """

     2 HTML Widget classes

     3 """

     4 

     5 try:

     6     set

     7 except NameError:

     8     from sets import Set as set   # Python 2.3 fallback

     9 

    10 import copy

    11 from itertools import chain

    12 

    13 from django.utils.datastructures import MultiValueDict

    14 from django.utils.html import escape, conditional_escape

    15 from django.utils.translation import ugettext

    16 from django.utils.encoding import StrAndUnicode, force_unicode

    17 from django.utils.safestring import mark_safe

    18 from util import flatatt

    19 

    20 __all__ = (

    21     'Widget', 'TextInput', 'PasswordInput',

    22     'HiddenInput', 'MultipleHiddenInput',

    23     'FileInput', 'DateTimeInput', 'Textarea', 'CheckboxInput',

    24     'Select', 'NullBooleanSelect', 'SelectMultiple', 'RadioSelect',

    25     'CheckboxSelectMultiple', 'MultiWidget', 'SplitDateTimeWidget',

    26 )

    27 

    28 class Widget(object):

    29     is_hidden = False          # Determines whether this corresponds to an <input type="hidden">.

    30     needs_multipart_form = False # Determines does this widget need multipart-encrypted form

    31 

    32     def __init__(self, attrs=None):

    33         if attrs is not None:

    34             self.attrs = attrs.copy()

    35         else:

    36             self.attrs = {}

    37 

    38     def __deepcopy__(self, memo):

    39         obj = copy.copy(self)

    40         obj.attrs = self.attrs.copy()

    41         memo[id(self)] = obj

    42         return obj

    43 

    44     def render(self, name, value, attrs=None):

    45         """

    46         Returns this Widget rendered as HTML, as a Unicode string.

    47 

    48         The 'value' given is not guaranteed to be valid input, so subclass

    49         implementations should program defensively.

    50         """

    51         raise NotImplementedError

    52 

    53     def build_attrs(self, extra_attrs=None, **kwargs):

    54         "Helper function for building an attribute dictionary."

    55         attrs = dict(self.attrs, **kwargs)

    56         if extra_attrs:

    57             attrs.update(extra_attrs)

    58         return attrs

    59 

    60     def value_from_datadict(self, data, files, name):

    61         """

    62         Given a dictionary of data and this widget's name, returns the value

    63         of this widget. Returns None if it's not provided.

    64         """

    65         return data.get(name, None)

    66 

    67     def id_for_label(self, id_):

    68         """

    69         Returns the HTML ID attribute of this Widget for use by a <label>,

    70         given the ID of the field. Returns None if no ID is available.

    71 

    72         This hook is necessary because some widgets have multiple HTML

    73         elements and, thus, multiple IDs. In that case, this method should

    74         return an ID value that corresponds to the first ID in the widget's

    75         tags.

    76         """

    77         return id_

    78     id_for_label = classmethod(id_for_label)

    79 

    80 class Input(Widget):

    81     """

    82     Base class for all <input> widgets (except type='checkbox' and

    83     type='radio', which are special).

    84     """

    85     input_type = None # Subclasses must define this.

    86 

    87     def render(self, name, value, attrs=None):

    88         if value is None: value = ''

    89         final_attrs = self.build_attrs(attrs, type=self.input_type, name=name)

    90         if value != '':

    91             # Only add the 'value' attribute if a value is non-empty.

    92             final_attrs['value'] = force_unicode(value)

    93         return mark_safe(u'<input%s />' % flatatt(final_attrs))

    94 

    95 class TextInput(Input):

    96     input_type = 'text'

    97 

    98 class PasswordInput(Input):

    99     input_type = 'password'

   100 

   101     def __init__(self, attrs=None, render_value=True):

   102         super(PasswordInput, self).__init__(attrs)

   103         self.render_value = render_value

   104 

   105     def render(self, name, value, attrs=None):

   106         if not self.render_value: value=None

   107         return super(PasswordInput, self).render(name, value, attrs)

   108 

   109 class HiddenInput(Input):

   110     input_type = 'hidden'

   111     is_hidden = True

   112 

   113 class MultipleHiddenInput(HiddenInput):

   114     """

   115     A widget that handles <input type="hidden"> for fields that have a list

   116     of values.

   117     """

   118     def __init__(self, attrs=None, choices=()):

   119         super(MultipleHiddenInput, self).__init__(attrs)

   120         # choices can be any iterable

   121         self.choices = choices

   122 

   123     def render(self, name, value, attrs=None, choices=()):

   124         if value is None: value = []

   125         final_attrs = self.build_attrs(attrs, type=self.input_type, name=name)

   126         return mark_safe(u'\n'.join([(u'<input%s />' %

   127             flatatt(dict(value=force_unicode(v), **final_attrs)))

   128             for v in value]))

   129 

   130     def value_from_datadict(self, data, files, name):

   131         if isinstance(data, MultiValueDict):

   132             return data.getlist(name)

   133         return data.get(name, None)

   134 

   135 class FileInput(Input):

   136     input_type = 'file'

   137     needs_multipart_form = True

   138 

   139     def render(self, name, value, attrs=None):

   140         return super(FileInput, self).render(name, None, attrs=attrs)

   141 

   142     def value_from_datadict(self, data, files, name):

   143         "File widgets take data from FILES, not POST"

   144         return files.get(name, None)

   145 

   146 class Textarea(Widget):

   147     def __init__(self, attrs=None):

   148         # The 'rows' and 'cols' attributes are required for HTML correctness.

   149         self.attrs = {'cols': '40', 'rows': '10'}

   150         if attrs:

   151             self.attrs.update(attrs)

   152 

   153     def render(self, name, value, attrs=None):

   154         if value is None: value = ''

   155         value = force_unicode(value)

   156         final_attrs = self.build_attrs(attrs, name=name)

   157         return mark_safe(u'<textarea%s>%s</textarea>' % (flatatt(final_attrs),

   158                 conditional_escape(force_unicode(value))))

   159 

   160 class DateTimeInput(Input):

   161     input_type = 'text'

   162     format = '%Y-%m-%d %H:%M:%S'     # '2006-10-25 14:30:59'

   163 

   164     def __init__(self, attrs=None, format=None):

   165         super(DateTimeInput, self).__init__(attrs)

   166         if format:

   167             self.format = format

   168 

   169     def render(self, name, value, attrs=None):

   170         if value is None:

   171             value = ''

   172         elif hasattr(value, 'strftime'):

   173             value = value.strftime(self.format)

   174         return super(DateTimeInput, self).render(name, value, attrs)

   175 

   176 class CheckboxInput(Widget):

   177     def __init__(self, attrs=None, check_test=bool):

   178         super(CheckboxInput, self).__init__(attrs)

   179         # check_test is a callable that takes a value and returns True

   180         # if the checkbox should be checked for that value.

   181         self.check_test = check_test

   182 

   183     def render(self, name, value, attrs=None):

   184         final_attrs = self.build_attrs(attrs, type='checkbox', name=name)

   185         try:

   186             result = self.check_test(value)

   187         except: # Silently catch exceptions

   188             result = False

   189         if result:

   190             final_attrs['checked'] = 'checked'

   191         if value not in ('', True, False, None):

   192             # Only add the 'value' attribute if a value is non-empty.

   193             final_attrs['value'] = force_unicode(value)

   194         return mark_safe(u'<input%s />' % flatatt(final_attrs))

   195 

   196     def value_from_datadict(self, data, files, name):

   197         if name not in data:

   198             # A missing value means False because HTML form submission does not

   199             # send results for unselected checkboxes.

   200             return False

   201         return super(CheckboxInput, self).value_from_datadict(data, files, name)

   202 

   203 class Select(Widget):

   204     def __init__(self, attrs=None, choices=()):

   205         super(Select, self).__init__(attrs)

   206         # choices can be any iterable, but we may need to render this widget

   207         # multiple times. Thus, collapse it into a list so it can be consumed

   208         # more than once.

   209         self.choices = list(choices)

   210 

   211     def render(self, name, value, attrs=None, choices=()):

   212         if value is None: value = ''

   213         final_attrs = self.build_attrs(attrs, name=name)

   214         output = [u'<select%s>' % flatatt(final_attrs)]

   215         # Normalize to string.

   216         str_value = force_unicode(value)

   217         for option_value, option_label in chain(self.choices, choices):

   218             option_value = force_unicode(option_value)

   219             selected_html = (option_value == str_value) and u' selected="selected"' or ''

   220             output.append(u'<option value="%s"%s>%s</option>' % (

   221                     escape(option_value), selected_html,

   222                     conditional_escape(force_unicode(option_label))))

   223         output.append(u'</select>')

   224         return mark_safe(u'\n'.join(output))

   225 

   226 class NullBooleanSelect(Select):

   227     """

   228     A Select Widget intended to be used with NullBooleanField.

   229     """

   230     def __init__(self, attrs=None):

   231         choices = ((u'1', ugettext('Unknown')), (u'2', ugettext('Yes')), (u'3', ugettext('No')))

   232         super(NullBooleanSelect, self).__init__(attrs, choices)

   233 

   234     def render(self, name, value, attrs=None, choices=()):

   235         try:

   236             value = {True: u'2', False: u'3', u'2': u'2', u'3': u'3'}[value]

   237         except KeyError:

   238             value = u'1'

   239         return super(NullBooleanSelect, self).render(name, value, attrs, choices)

   240 

   241     def value_from_datadict(self, data, files, name):

   242         value = data.get(name, None)

   243         return {u'2': True, u'3': False, True: True, False: False}.get(value, None)

   244 

   245 class SelectMultiple(Widget):

   246     def __init__(self, attrs=None, choices=()):

   247         super(SelectMultiple, self).__init__(attrs)

   248         # choices can be any iterable

   249         self.choices = choices

   250 

   251     def render(self, name, value, attrs=None, choices=()):

   252         if value is None: value = []

   253         final_attrs = self.build_attrs(attrs, name=name)

   254         output = [u'<select multiple="multiple"%s>' % flatatt(final_attrs)]

   255         str_values = set([force_unicode(v) for v in value]) # Normalize to strings.

   256         for option_value, option_label in chain(self.choices, choices):

   257             option_value = force_unicode(option_value)

   258             selected_html = (option_value in str_values) and ' selected="selected"' or ''

   259             output.append(u'<option value="%s"%s>%s</option>' % (

   260                     escape(option_value), selected_html,

   261                     conditional_escape(force_unicode(option_label))))

   262         output.append(u'</select>')

   263         return mark_safe(u'\n'.join(output))

   264 

   265     def value_from_datadict(self, data, files, name):

   266         if isinstance(data, MultiValueDict):

   267             return data.getlist(name)

   268         return data.get(name, None)

   269 

   270 class RadioInput(StrAndUnicode):

   271     """

   272     An object used by RadioFieldRenderer that represents a single

   273     <input type='radio'>.

   274     """

   275 

   276     def __init__(self, name, value, attrs, choice, index):

   277         self.name, self.value = name, value

   278         self.attrs = attrs

   279         self.choice_value = force_unicode(choice[0])

   280         self.choice_label = force_unicode(choice[1])

   281         self.index = index

   282 

   283     def __unicode__(self):

   284         return mark_safe(u'<label>%s %s</label>' % (self.tag(),

   285                 conditional_escape(force_unicode(self.choice_label))))

   286 

   287     def is_checked(self):

   288         return self.value == self.choice_value

   289 

   290     def tag(self):

   291         if 'id' in self.attrs:

   292             self.attrs['id'] = '%s_%s' % (self.attrs['id'], self.index)

   293         final_attrs = dict(self.attrs, type='radio', name=self.name, value=self.choice_value)

   294         if self.is_checked():

   295             final_attrs['checked'] = 'checked'

   296         return mark_safe(u'<input%s />' % flatatt(final_attrs))

   297 

   298 class RadioFieldRenderer(StrAndUnicode):

   299     """

   300     An object used by RadioSelect to enable customization of radio widgets.

   301     """

   302 

   303     def __init__(self, name, value, attrs, choices):

   304         self.name, self.value, self.attrs = name, value, attrs

   305         self.choices = choices

   306 

   307     def __iter__(self):

   308         for i, choice in enumerate(self.choices):

   309             yield RadioInput(self.name, self.value, self.attrs.copy(), choice, i)

   310 

   311     def __getitem__(self, idx):

   312         choice = self.choices[idx] # Let the IndexError propogate

   313         return RadioInput(self.name, self.value, self.attrs.copy(), choice, idx)

   314 

   315     def __unicode__(self):

   316         return self.render()

   317 

   318     def render(self):

   319         """Outputs a <ul> for this set of radio fields."""

   320         return mark_safe(u'<ul>\n%s\n</ul>' % u'\n'.join([u'<li>%s</li>'

   321                 % force_unicode(w) for w in self]))

   322 

   323 class RadioSelect(Select):

   324     renderer = RadioFieldRenderer

   325 

   326     def __init__(self, *args, **kwargs):

   327         # Override the default renderer if we were passed one.

   328         renderer = kwargs.pop('renderer', None)

   329         if renderer:

   330             self.renderer = renderer

   331         super(RadioSelect, self).__init__(*args, **kwargs)

   332 

   333     def get_renderer(self, name, value, attrs=None, choices=()):

   334         """Returns an instance of the renderer."""

   335         if value is None: value = ''

   336         str_value = force_unicode(value) # Normalize to string.

   337         final_attrs = self.build_attrs(attrs)

   338         choices = list(chain(self.choices, choices))

   339         return self.renderer(name, str_value, final_attrs, choices)

   340 

   341     def render(self, name, value, attrs=None, choices=()):

   342         return self.get_renderer(name, value, attrs, choices).render()

   343 

   344     def id_for_label(self, id_):

   345         # RadioSelect is represented by multiple <input type="radio"> fields,

   346         # each of which has a distinct ID. The IDs are made distinct by a "_X"

   347         # suffix, where X is the zero-based index of the radio field. Thus,

   348         # the label for a RadioSelect should reference the first one ('_0').

   349         if id_:

   350             id_ += '_0'

   351         return id_

   352     id_for_label = classmethod(id_for_label)

   353 

   354 class CheckboxSelectMultiple(SelectMultiple):

   355     def render(self, name, value, attrs=None, choices=()):

   356         if value is None: value = []

   357         has_id = attrs and 'id' in attrs

   358         final_attrs = self.build_attrs(attrs, name=name)

   359         output = [u'<ul>']

   360         # Normalize to strings

   361         str_values = set([force_unicode(v) for v in value])

   362         for i, (option_value, option_label) in enumerate(chain(self.choices, choices)):

   363             # If an ID attribute was given, add a numeric index as a suffix,

   364             # so that the checkboxes don't all have the same ID attribute.

   365             if has_id:

   366                 final_attrs = dict(final_attrs, id='%s_%s' % (attrs['id'], i))

   367             cb = CheckboxInput(final_attrs, check_test=lambda value: value in str_values)

   368             option_value = force_unicode(option_value)

   369             rendered_cb = cb.render(name, option_value)

   370             output.append(u'<li><label>%s %s</label></li>' % (rendered_cb,

   371                     conditional_escape(force_unicode(option_label))))

   372         output.append(u'</ul>')

   373         return mark_safe(u'\n'.join(output))

   374 

   375     def id_for_label(self, id_):

   376         # See the comment for RadioSelect.id_for_label()

   377         if id_:

   378             id_ += '_0'

   379         return id_

   380     id_for_label = classmethod(id_for_label)

   381 

   382 class MultiWidget(Widget):

   383     """

   384     A widget that is composed of multiple widgets.

   385 

   386     Its render() method is different than other widgets', because it has to

   387     figure out how to split a single value for display in multiple widgets.

   388     The ``value`` argument can be one of two things:

   389 

   390         * A list.

   391         * A normal value (e.g., a string) that has been "compressed" from

   392           a list of values.

   393 

   394     In the second case -- i.e., if the value is NOT a list -- render() will

   395     first "decompress" the value into a list before rendering it. It does so by

   396     calling the decompress() method, which MultiWidget subclasses must

   397     implement. This method takes a single "compressed" value and returns a

   398     list.

   399 

   400     When render() does its HTML rendering, each value in the list is rendered

   401     with the corresponding widget -- the first value is rendered in the first

   402     widget, the second value is rendered in the second widget, etc.

   403 

   404     Subclasses may implement format_output(), which takes the list of rendered

   405     widgets and returns a string of HTML that formats them any way you'd like.

   406 

   407     You'll probably want to use this class with MultiValueField.

   408     """

   409     def __init__(self, widgets, attrs=None):

   410         self.widgets = [isinstance(w, type) and w() or w for w in widgets]

   411         super(MultiWidget, self).__init__(attrs)

   412 

   413     def render(self, name, value, attrs=None):

   414         # value is a list of values, each corresponding to a widget

   415         # in self.widgets.

   416         if not isinstance(value, list):

   417             value = self.decompress(value)

   418         output = []

   419         final_attrs = self.build_attrs(attrs)

   420         id_ = final_attrs.get('id', None)

   421         for i, widget in enumerate(self.widgets):

   422             try:

   423                 widget_value = value[i]

   424             except IndexError:

   425                 widget_value = None

   426             if id_:

   427                 final_attrs = dict(final_attrs, id='%s_%s' % (id_, i))

   428             output.append(widget.render(name + '_%s' % i, widget_value, final_attrs))

   429         return mark_safe(self.format_output(output))

   430 

   431     def id_for_label(self, id_):

   432         # See the comment for RadioSelect.id_for_label()

   433         if id_:

   434             id_ += '_0'

   435         return id_

   436     id_for_label = classmethod(id_for_label)

   437 

   438     def value_from_datadict(self, data, files, name):

   439         return [widget.value_from_datadict(data, files, name + '_%s' % i) for i, widget in enumerate(self.widgets)]

   440 

   441     def format_output(self, rendered_widgets):

   442         """

   443         Given a list of rendered widgets (as strings), returns a Unicode string

   444         representing the HTML for the whole lot.

   445 

   446         This hook allows you to format the HTML design of the widgets, if

   447         needed.

   448         """

   449         return u''.join(rendered_widgets)

   450 

   451     def decompress(self, value):

   452         """

   453         Returns a list of decompressed values for the given compressed value.

   454         The given value can be assumed to be valid, but not necessarily

   455         non-empty.

   456         """

   457         raise NotImplementedError('Subclasses must implement this method.')

   458 

   459 class SplitDateTimeWidget(MultiWidget):

   460     """

   461     A Widget that splits datetime input into two <input type="text"> boxes.

   462     """

   463     def __init__(self, attrs=None):

   464         widgets = (TextInput(attrs=attrs), TextInput(attrs=attrs))

   465         super(SplitDateTimeWidget, self).__init__(widgets, attrs)

   466 

   467     def decompress(self, value):

   468         if value:

   469             return [value.date(), value.time().replace(microsecond=0)]

   470         return [None, None]

   471