def multiple(self, values, rows=None, list_type=True, show_link=True):
        """
            Represent multiple values as a comma-separated list.

            @param values: list of values
            @param rows: the referenced rows (if values are foreign keys)
            @param show_link: render each representation as link
        """

        self._setup()
        show_link = show_link and self.show_link

        # Get the values
        if rows and self.table:
            key = self.key
            values = [row[key] for row in rows]
        elif self.list_type and list_type:
            from itertools import chain
            try:
                hasnone = None in values
                if hasnone:
                    values = [i for i in values if i != None]
                values = list(set(chain.from_iterable(values)))
                if hasnone:
                    values.append(None)
            except TypeError:
                raise ValueError("List of lists expected, got %s" % values)
        else:
            values = [values] if type(values) is not list else values

        # Lookup the representations
        if values:
            default = self.default
            items = self._lookup(values, rows=rows)
            if show_link:
                link = self.link
                labels = [[link(v, s3_unicode(items[v])), ", "]
                          if v in items else [default, ", "]
                          for v in values]
                if labels:
                    from itertools import chain
                    return TAG[""](list(chain.from_iterable(labels))[:-1])
                else:
                    return ""
            else:
                labels = [s3_unicode(items[v])
                          if v in items else default for v in values]
                if labels:
                    return ", ".join(labels)
        return self.none

    def format_date(self, dt, dtfmt=None, local=False):
        """
            Format a date according to this calendar

            @param dt: the date (datetime.date or datetime.datetime)
            @return: the date as string
        """

        if dt is None:
            return current.messages["NONE"]

        # Default format
        if dtfmt is None:
            if local:
                dtfmt = current.deployment_settings.get_L10n_date_format()
            else:
                dtfmt = "%Y-%m-%d" # ISO Date Format

        # Deal with T's
        try:
            dtfmt = str(dtfmt)
        except (UnicodeDecodeError, UnicodeEncodeError):
            dtfmt = s3_unicode(dtfmt).encode("utf-8")

        return self.calendar._format(dt, dtfmt)

    def format_datetime(self, dt, dtfmt=None, local=False):
        """
            Format a datetime according to this calendar

            @param dt: the datetime (datetime.datetime)
            @return: the datetime as string
        """

        if dt is None:
            return current.messages["NONE"]

        # Default format
        if dtfmt is None:
            if local:
                dtfmt = current.deployment_settings.get_L10n_datetime_format()
            else:
                dtfmt = ISOFORMAT # ISO Date/Time Format

        # Deal with T's
        try:
            dtfmt = str(dtfmt)
        except (UnicodeDecodeError, UnicodeEncodeError):
            dtfmt = s3_unicode(dtfmt).encode("utf-8")

        # Remove microseconds
        # - for the case that the calendar falls back to .isoformat
        if isinstance(dt, datetime.datetime):
           dt = dt.replace(microsecond=0)

        return self.calendar._format(dt, dtfmt)

    def ajax_options(self, resource):
        """
            Method to Ajax-retrieve the current options of this widget

            @param resource: the S3Resource
        """

        opts = self.opts
        attr = self._attr(resource)
        ftype, options, noopt = self._options(resource)

        if noopt:
            options = {attr["_id"]: noopt}
        else:
            widget_type = opts["widget"]
            if widget_type in ("multiselect-bootstrap", "multiselect"):
                # Produce a simple list of tuples
                options = {attr["_id"]: [(k, s3_unicode(v))
                                         for k, v in options]}
            else:
                # Use the widget method to group and sort the options
                widget = S3GroupedOptionsWidget(
                                options = options,
                                multiple = True,
                                cols = opts["cols"],
                                size = opts["size"] or 12,
                                help_field = opts["help_field"])
                options = {attr["_id"]:
                           widget._options({"type": ftype}, [])}
        return options

    def json_message(success=True,
                     statuscode=None,
                     message=None,
                     **kwargs):
        """
            Provide a nicely-formatted JSON Message

            @param success: action succeeded or failed
            @param status_code: the HTTP status code
            @param message: the message text
            @param kwargs: other elements for the message

            @keyword tree: error tree to include as JSON object (rather
                           than as string) for easy decoding
        """

        if statuscode is None:
            statuscode = success and 200 or 404

        status = success and "success" or "failed"
        code = str(statuscode)

        output = {"status": status, "statuscode": str(code)}

        tree = kwargs.get("tree", None)
        if message:
            output["message"] = s3_unicode(message)
        for k, v in kwargs.items():
            if k != "tree":
                output[k] = v
        output = json.dumps(output)
        if message and tree:
            output = output[:-1] + ', "tree": %s}' % tree
        return output

    def widget(self, field, attr):
        """ Widget renderer (parameter description see base class) """

        attr["_readonly"] = "true"
        attr["_default"] = s3_unicode(field.default)

        return TAG["input"](self.label(), **attr)

    def represent_row(self, row):
        """
            Represent the referenced row.
            (in foreign key representations)

            @param row: the row

            @return: the representation of the Row, or None if there
                     is an error in the Row
        """

        labels = self.labels

        if self.slabels:
            # String Template
            v = labels % row
        elif self.clabels:
            # External Renderer
            v = labels(row)
        else:
            # Default
            values = [row[f] for f in self.fields if row[f] not in (None, "")]
            if values:
                v = " ".join([s3_unicode(v) for v in values])
            else:
                v = self.none
        if self.translate and not type(v) is lazyT:
            return current.T(v)
        else:
            return v

    def render_list(self, value, labels, show_link=True):
        """
            Helper method to render list-type representations from
            bulk()-results.

            @param value: the list
            @param labels: the labels as returned from bulk()
            @param show_link: render references as links, should
                              be the same as used with bulk()
        """

        show_link = show_link and self.show_link
        if show_link:
            labels = [(labels[v], ", ")
                      if v in labels else (self.default, ", ")
                      for v in value]
            if labels:
                from itertools import chain
                return TAG[""](list(chain.from_iterable(labels))[:-1])
            else:
                return ""
        else:
            return ", ".join([s3_unicode(labels[v])
                              if v in labels else self.default
                              for v in value])

    def render_node(self, element, attributes, name):
        """
            Render as text or attribute of an XML element

            @param element: the element
            @param attributes: the attributes dict of the element
            @param name: the attribute name
        """

        # Render value
        text = self.represent()
        text = s3_unicode(text)

        # Strip markup + XML-escape
        if text and "<" in text:
            try:
                stripper = S3MarkupStripper()
                stripper.feed(text)
                text = stripper.stripped()
            except:
                pass

        # Add to node
        if text is not None:
            if element is not None:
                element.text = text
            else:
                attributes[name] = text
            return

    def _html(self, node_id, widget_id, represent=None):
        """
            Recursively render a node as list item (with subnodes
            as unsorted list inside the item)

            @param node_id: the node ID
            @param widget_id: the unique ID for the outermost list
            @param represent: the node ID representation method

            @return: the list item (LI)
        """

        node = self.nodes.get(node_id)
        if not node:
            return None

        label = self.label(node_id, represent=represent)
        if label is None:
            label = s3_unicode(node_id)

        subnodes = node["s"]
        item = LI(A(label, _href="#", _class="s3-hierarchy-node"),
                  _id = "%s-%s" % (widget_id, node_id),
                  _rel = "parent" if subnodes else "leaf")

        html = self._html
        if subnodes:
            sublist = UL([html(n, widget_id, represent=represent)
                         for n in subnodes])
            item.append(sublist)
        return item

    def aadata(self, totalrows, displayrows, id, sEcho, flist, stringify=True, action_col=None, **attr):
        """
            Method to render the data into a json object

            @param totalrows: The total rows in the unfiltered query.
            @param displayrows: The total rows in the filtered query.
            @param id: The id of the table for which this ajax call will
                       respond to.
            @param sEcho: An unaltered copy of sEcho sent from the client used
                          by dataTables as a draw count.
            @param flist: The list of fields
            @param attr: dictionary of attributes which can be passed in
                   dt_action_col: The column where the action buttons will be placed
                   dt_bulk_actions: list of labels for the bulk actions.
                   dt_bulk_col: The column in which the checkboxes will appear,
                                by default it will be the column immediately
                                before the first data item
                   dt_group_totals: The number of record in each group.
                                    This will be displayed in parenthesis
                                    after the group title.
        """

        data = self.data
        if not flist:
            flist = self.lfields
        start = self.start
        end = self.end
        if action_col is None:
            action_col = attr.get("dt_action_col", 0)
        structure = {}
        aadata = []
        for i in xrange(start, end):
            row = data[i]
            details = []
            for field in flist:
                if field == "BULK":
                    details.append(
                        "<INPUT id='select%s' type='checkbox' class='bulkcheckbox'>" % row[flist[action_col]]
                    )
                else:
                    details.append(s3_unicode(row[field]))
            aadata.append(details)
        structure["dataTable_id"] = id
        structure["dataTable_filter"] = self.filterString
        structure["dataTable_groupTotals"] = attr.get("dt_group_totals", [])
        structure["dataTable_sort"] = self.orderby
        structure["aaData"] = aadata
        structure["iTotalRecords"] = totalrows
        structure["iTotalDisplayRecords"] = displayrows
        structure["sEcho"] = sEcho
        if stringify:
            from gluon.serializers import json

            return json(structure)
        else:
            return structure

    def _setup(self):
        """ Lazy initialization of defaults """

        if self.setup:
            return

        self.queries = 0

        # Default representations
        messages = current.messages
        if self.default is None:
            self.default = s3_unicode(messages.UNKNOWN_OPT)
        if self.none is None:
            self.none = messages["NONE"]

        # Initialize theset
        if self.options is not None:
            self.theset = self.options
        else:
            self.theset = {}

        # Lookup table parameters and linkto
        if self.table is None:
            tablename = self.tablename
            if tablename:
                table = current.s3db.table(tablename)
                if table is not None:
                    if self.key is None:
                        self.key = table._id.name
                    if not self.fields:
                        if "name" in table:
                            self.fields = ["name"]
                        else:
                            self.fields = [self.key]
                    self.table = table
                if self.linkto is None and self.show_link:
                    c, f = tablename.split("_", 1)
                    self.linkto = URL(c=c, f=f, args=["[id]"], extension="")

        # What type of renderer do we use?
        labels = self.labels
        # String template?
        self.slabels = isinstance(labels, basestring)
        # External renderer?
        self.clabels = callable(labels)

        # Hierarchy template
        if isinstance(self.hierarchy, basestring):
            self.htemplate = self.hierarchy
        else:
            self.htemplate = "%s > %s"

        self.setup = True
        return

    def ajax_options(self, resource):
        """
            Method to Ajax-retrieve the current options of this widget

            @param resource: the S3Resource
        """

        attr = self._attr(resource)
        ftype, options, noopt = self._options(resource)
        if noopt:
            return {attr["_id"]: noopt}
        else:
            return {attr["_id"]: [(k, s3_unicode(v)) for k,v in options]}

    def _represent(self, node_ids=None, renderer=None):
        """
            Represent nodes as labels, the labels are stored in the
            nodes as attribute "l".

            @param node_ids: the node IDs (None for all nodes)
            @param renderer: the representation method (falls back
                             to the "name" field in the target table
                             if present)
        """

        theset = self.theset
        LABEL = "l"

        if node_ids is None:
            node_ids = self.nodes.keys()

        pending = set()
        for node_id in node_ids:
            node = theset.get(node_id)
            if not node:
                continue
            if LABEL not in node:
                pending.add(node_id)

        if renderer is None:
            renderer = self.represent
        if renderer is None:
            tablename = self.tablename
            table = current.s3db.table(tablename) if tablename else None
            if table and "name" in table.fields:
                from s3fields import S3Represent
                self.represent = renderer = S3Represent(lookup = tablename,
                                                        key = self.pkey.name)
            else:
                renderer = s3_unicode
        if hasattr(renderer, "bulk"):
            labels = renderer.bulk(list(pending), list_type = False)
            for node_id, label in labels.items():
                if node_id in theset:
                    theset[node_id][LABEL] = label
        else:
            for node_id in pending:
                try:
                    label = renderer(node_id)
                except:
                    label = s3_unicode(node_id)
                theset[node_id][LABEL] = label
        return

    def html_render_group_footer(self, tbody, group, level=0):
        """
            Render the group footer (=group totals)

            @param tbody: the TBODY or TABLE to append to
            @param group: the group dict
            @param level: the grouping level

            @todo: add group label to footer if no group headers
            @todo: add totals label
        """

        data = self.data

        columns = data.get("c")
        totals = group.get("t")
        value = group.get("v")

        footer_row = TR(_class="gi-group-footer gi-level-%s" % level)
        if not totals:
            if not self.group_headers:
                footer_row.append(TD(value, _colspan = len(columns)))
                tbody.append(footer_row)
            return

        if columns:
            label = None
            span = 0
            for column in columns:
                has_value = column in totals
                if label is None:
                    if not has_value:
                        span += 1
                        continue
                    else:
                        label = TD("%s %s" % (s3_unicode(s3_strip_markup(value)),
                                              self.totals_label,
                                              ),
                                   _class = "gi-group-footer-label",
                                   _colspan = span,
                                   )
                        footer_row.append(label)
                value = totals[column] if has_value else ""
                footer_row.append(TD(value))

        tbody.append(footer_row)

    def link(self, k, v):
        """
            Represent a (key, value) as hypertext link.

                - Typically, k is a foreign key value, and v the
                  representation of the referenced record, and the link
                  shall open a read view of the referenced record.

                - In the base class, the linkto-parameter expects a URL (as
                  string) with "[id]" as placeholder for the key.

            @param k: the key
            @param v: the representation of the key
        """

        if self.linkto:
            k = s3_unicode(k)
            return A(v, _href=self.linkto.replace("[id]", k).replace("%5Bid%5D", k))
        else:
            return v

    def represent_row(self, row, prefix=None):
        """
            Represent the referenced row.
            (in foreign key representations)

            @param row: the row

            @return: the representation of the Row, or None if there
                     is an error in the Row
        """

        labels = self.labels

        if self.slabels:
            # String Template
            v = labels % row
        elif self.clabels:
            # External Renderer
            v = labels(row)
        else:
            # Default
            values = [row[f] for f in self.fields if row[f] not in (None, "")]
            if values:
                sep = self.field_sep
                v = sep.join([s3_unicode(v) for v in values])
            else:
                v = self.none
        if self.translate and not type(v) is lazyT:
            output = current.T(v)
        else:
            output = v

        if prefix and self.hierarchy:
            return self.htemplate % (prefix, output)

        return output

#.........这里部分代码省略.........
            import re
            match = re.match("(\w+)\((\w+),(\w+)\)", tooltip)
            if match:
                function_name, kname, vname = match.groups()
                # Try to resolve the function name
                tooltip_function = current.s3db.get(function_name)
                if tooltip_function:
                    if kname not in fields:
                        fields.append(kname)
                    if vname not in fields:
                        fields.append(vname)
            else:
                if tooltip not in fields:
                    fields.append(tooltip)

        # Get the data
        _rows = resource.select(fields,
                                start=start,
                                limit=limit,
                                orderby=orderby,
                                represent=represent).rows

        # Simplify to plain fieldnames for fields in this table
        tn = "%s." % resource.tablename
        rows = []
        rappend = rows.append
        for _row in _rows:
            row = {}
            for f in _row:
                v = _row[f]
                if tn in f:
                    f = f.split(tn, 1)[1]
                row[f] = v
            rappend(row)

        if tooltip:
            if tooltip_function:
                # Resolve key and value names against the resource
                try:
                    krfield = resource.resolve_selector(kname)
                    vrfield = resource.resolve_selector(vname)
                except (AttributeError, SyntaxError):
                    import sys
                    current.log.error(sys.exc_info()[1])
                else:
                    # Extract key and value fields from each row and
                    # build options dict for function call
                    options = []
                    items = {}
                    for row in rows:
                        try:
                            k = krfield.extract(row)
                        except KeyError:
                            break
                        try:
                            v = vrfield.extract(row)
                        except KeyError:
                            break
                        items[k] = row
                        options.append((k, v))
                    # Call tooltip rendering function
                    try:
                        tooltips = tooltip_function(options)
                    except:
                        import sys
                        current.log.error(sys.exc_info()[1])
                    else:
                        # Add tooltips as "_tooltip" to the corresponding rows
                        if isinstance(tooltips, dict):
                            from s3utils import s3_unicode
                            for k, v in tooltips.items():
                                if k in items:
                                    items[k]["_tooltip"] = s3_unicode(v)

            else:
                # Resolve the tooltip field name against the resource
                try:
                    tooltip_rfield = resource.resolve_selector(tooltip)
                except (AttributeError, SyntaxError):
                    import sys
                    current.log.error(sys.exc_info()[1])
                else:
                    # Extract the tooltip field from each row
                    # and add it as _tooltip
                    from s3utils import s3_unicode
                    for row in rows:
                        try:
                            value = tooltip_rfield.extract(row)
                        except KeyError:
                            break
                        if value:
                            row["_tooltip"] = s3_unicode(value)

        # Return as JSON
        response = current.response
        if response:
            response.headers["Content-Type"] = "application/json"

        from gluon.serializers import json as jsons
        return jsons(rows)

#.........这里部分代码省略.........
                        kappend = opt_keys.append
                        for row in rows:
                            v = row[colname]
                            if v not in opt_keys:
                                kappend(v)
            else:
                opt_keys = []

        # No options?
        if len(opt_keys) < 1 or len(opt_keys) == 1 and not opt_keys[0]:
            return (ftype, None, opts.get("no_opts", NOOPT))

        # Represent the options

        opt_list = [] # list of tuples (key, value)

        # Custom represent? (otherwise fall back to field represent)
        represent = opts.represent
        if not represent or ftype[:9] != "reference":
            represent = field.represent

        if options is not None:
            # Custom dict of {value:label} => use this label
            opt_list = options.items()

        elif callable(represent):
            # Callable representation function:

            if hasattr(represent, "bulk"):
                # S3Represent => use bulk option
                opt_dict = represent.bulk(opt_keys,
                                          list_type=False,
                                          show_link=False)
                if None in opt_keys:
                    opt_dict[None] = EMPTY
                elif None in opt_dict:
                    del opt_dict[None]
                if "" in opt_keys:
                    opt_dict[""] = EMPTY
                opt_list = opt_dict.items()

            else:
                # Simple represent function
                args = {"show_link": False} \
                       if "show_link" in represent.func_code.co_varnames else {}
                if multiple:
                    repr_opt = lambda opt: opt in (None, "") and (opt, EMPTY) or \
                                           (opt, represent([opt], **args))
                else:
                    repr_opt = lambda opt: opt in (None, "") and (opt, EMPTY) or \
                                           (opt, represent(opt, **args))
                opt_list = map(repr_opt, opt_keys)

        elif isinstance(represent, str) and ftype[:9] == "reference":
            # Represent is a string template to be fed from the
            # referenced record

            # Get the referenced table
            db = current.db
            ktable = db[ftype[10:]]

            k_id = ktable._id.name

            # Get the fields referenced by the string template
            fieldnames = [k_id]
            fieldnames += re.findall("%\(([a-zA-Z0-9_]*)\)s", represent)
            represent_fields = [ktable[fieldname] for fieldname in fieldnames]

            # Get the referenced records
            query = (ktable.id.belongs([k for k in opt_keys
                                              if str(k).isdigit()])) & \
                    (ktable.deleted == False)
            rows = db(query).select(*represent_fields).as_dict(key=k_id)

            # Run all referenced records against the format string
            opt_list = []
            ol_append = opt_list.append
            for opt_value in opt_keys:
                if opt_value in rows:
                    opt_represent = represent % rows[opt_value]
                    if opt_represent:
                        ol_append((opt_value, opt_represent))

        else:
            # Straight string representations of the values (fallback)
            opt_list = [(opt_value, s3_unicode(opt_value))
                        for opt_value in opt_keys if opt_value]

        # Sort the options
        opt_list.sort(key = lambda item: item[1])
        options = []
        empty = None
        for k, v in opt_list:
            if k is None:
                empty = ("NONE", v)
            else:
                options.append((k, v))
        if empty:
            options.append(empty)
        return (ftype, options, None)

    def json(self, resource,
             start=None,
             limit=None,
             fields=None,
             orderby=None,
             tooltip=None):
        """
            Export a resource as JSON

            @param resource: the resource to export from
            @param start: index of the first record to export
            @param limit: maximum number of records to export
            @param fields: list of field selectors for fields to include in
                           the export (None for all fields)
            @param orderby: ORDERBY expression
            @param tooltip: additional tooltip field, either a field selector
                            or an expression "f(k,v)" where f is a function
                            name that can be looked up from s3db, and k,v are
                            field selectors for the row, f will be called with
                            a list of tuples (k,v) for each row and is expected
                            to return a dict {k:tooltip} => used by
                            filterOptionsS3 to extract onhover-tooltips for
                            Ajax-update of options
        """

        if fields is None:
            fields = [f.name for f in resource.table if f.readable]

        tooltip_function = None
        if tooltip:
            if type(tooltip) is list:
                tooltip = tooltip[-1]
            import re
            match = re.match("(\w+)\((\w+),(\w+)\)", tooltip)
            if match:
                function_name, kname, vname = match.groups()
                # Try resolve the function name
                tooltip_function = current.s3db.get(function_name)
                if tooltip_function:
                    if kname not in fields:
                        fields.append(kname)
                    if vname not in fields:
                        fields.append(vname)
            else:
                if tooltip not in fields:
                    fields.append(tooltip)

        # Get the rows and return as json
        rows = resource.select(fields,
                               start=start,
                               limit=limit,
                               orderby=orderby,
                               as_rows=True)

        if tooltip:
            import sys
            from s3utils import s3_unicode
            if tooltip_function:
                # Resolve key and value names against the resource
                try:
                    krfield = resource.resolve_selector(kname)
                    vrfield = resource.resolve_selector(vname)
                except (AttributeError, SyntaxError):
                    current.log.error(sys.exc_info()[1])
                else:
                    # Extract key and value fields from each row and
                    # build options dict for function call
                    options = []
                    items = {}
                    for row in rows:
                        try:
                            k = krfield.extract(row)
                        except KeyError:
                            break
                        try:
                            v = vrfield.extract(row)
                        except KeyError:
                            break
                        items[k] = row
                        options.append((k, v))
                    # Call tooltip rendering function
                    try:
                        tooltips = tooltip_function(options)
                    except:
                        current.log.error(sys.exc_info()[1])
                    else:
                        # Add tooltips as "_tooltip" to the corresponding rows
                        if isinstance(tooltips, dict):
                            for k, v in tooltips.items():
                                if k in items:
                                    items[k]["_tooltip"] = s3_unicode(v)
                pass
            else:
                # Resolve the tooltip field name against the resource
                try:
                    tooltip_rfield = resource.resolve_selector(tooltip)
                except (AttributeError, SyntaxError):
                    current.log.error(sys.exc_info()[1])
                else:
                    # Extract the tooltip field from each row
#.........这里部分代码省略.........