[Summary view] [Print] [Text view]

   1  <?php
   2  // $Id: views_handler_field.inc,v 1.33.2.14 2010/06/16 19:15:53 merlinofchaos Exp $
   3  /**
   4   * @defgroup views_field_handlers Views' field handlers
   5   * @{
   6   * Handlers to tell Views how to build and display fields.
   7   *
   8   */
   9  
  10  /**
  11   * Base field handler that has no options and renders an unformatted field.
  12   *
  13   * Definition terms:
  14   * - additional fields: An array of fields that should be added to the query
  15   *                      for some purpose. The array is in the form of:
  16   *                      array('identifier' => array('table' => tablename,
  17   *                      'field' => fieldname); as many fields as are necessary
  18   *                      may be in this array.
  19   * - click sortable: If TRUE, this field may be click sorted.
  20   */
  21  class views_handler_field extends views_handler {
  22    var $field_alias = 'unknown';
  23    var $aliases = array();
  24  
  25    /**
  26     * Construct a new field handler.
  27     */
  28    function construct() {
  29      parent::construct();
  30  
  31      $this->additional_fields = array();
  32      if (!empty($this->definition['additional fields'])) {
  33        $this->additional_fields = $this->definition['additional fields'];
  34      }
  35  
  36      if (!isset($this->options['exclude'])) {
  37        $this->options['exclude'] = '';
  38      }
  39    }
  40  
  41    /**
  42     * Determine if this field can allow advanced rendering.
  43     *
  44     * Fields can set this to FALSE if they do not wish to allow
  45     * token based rewriting or link-making.
  46     */
  47    function allow_advanced_render() {
  48      return TRUE;
  49    }
  50  
  51    function init(&$view, $options) {
  52      parent::init($view, $options);
  53  
  54      $this->options += array(
  55        'exclude' => FALSE,
  56      );
  57    }
  58  
  59    /**
  60     * Called to add the field to a query.
  61     */
  62    function query() {
  63      $this->ensure_my_table();
  64      // Add the field.
  65      $this->field_alias = $this->query->add_field($this->table_alias, $this->real_field);
  66  
  67      $this->add_additional_fields();
  68    }
  69  
  70    /**
  71     * Add 'additional' fields to the query.
  72     *
  73     * @param $fields
  74     * An array of fields. The key is an identifier used to later find the
  75     * field alias used. The value is either a string in which case it's
  76     * assumed to be a field on this handler's table; or it's an array in the
  77     * form of
  78     * @code array('table' => $tablename, 'field' => $fieldname) @endcode
  79     */
  80    function add_additional_fields($fields = NULL) {
  81      if (!isset($fields)) {
  82        // notice check
  83        if (empty($this->additional_fields)) {
  84          return;
  85        }
  86        $fields = $this->additional_fields;
  87      }
  88      if (!empty($fields) && is_array($fields)) {
  89        foreach ($fields as $identifier => $info) {
  90          if (is_array($info)) {
  91            if (isset($info['table'])) {
  92              $table_alias = $this->query->ensure_table($info['table'], $this->relationship);
  93            }
  94            else {
  95              $table_alias = $this->table_alias;
  96            }
  97            if (empty($table_alias)) {
  98              vpr(t('Handler @handler tried to add additional_field @identifier but @table could not be added!', array('@handler' => $this->definition['handler'], '@identifier' => $identifier, '@table' => $info['table'])));
  99              $this->aliases[$identifier] = 'broken';
 100              continue;
 101            }
 102            $this->aliases[$identifier] = $this->query->add_field($table_alias, $info['field']);
 103          }
 104          else {
 105            $this->aliases[$info] = $this->query->add_field($this->table_alias, $info);
 106          }
 107        }
 108      }
 109    }
 110  
 111    /**
 112     * Called to determine what to tell the clicksorter.
 113     */
 114    function click_sort($order) {
 115      $this->query->add_orderby($this->table, $this->field, $order, $this->field_alias);
 116    }
 117  
 118    /**
 119     * Determine if this field is click sortable.
 120     */
 121    function click_sortable() {
 122      return !empty($this->definition['click sortable']);
 123    }
 124  
 125    /**
 126     * Get this field's label.
 127     */
 128    function label() {
 129      if (!isset($this->options['label'])) {
 130        return '';
 131      }
 132      return $this->options['label'];
 133    }
 134  
 135    /**
 136     * Return DIV or SPAN based upon the field's element type.
 137     */
 138    function element_type() {
 139      if (isset($this->definition['element type'])) {
 140        return $this->definition['element type'];
 141      }
 142  
 143      return 'span';
 144    }
 145  
 146    function option_definition() {
 147      $options = parent::option_definition();
 148  
 149      $options['label'] = array('default' => $this->definition['title'], 'translatable' => TRUE);
 150      $options['alter'] = array(
 151        'contains' => array(
 152          'alter_text' => array('default' => FALSE),
 153          'text' => array('default' => '', 'translatable' => TRUE),
 154          'make_link' => array('default' => FALSE),
 155          'path' => array('default' => '', 'translatable' => TRUE),
 156          'alt' => array('default' => '', 'translatable' => TRUE),
 157          'link_class' => array('default' => ''),
 158          'prefix' => array('default' => '', 'translatable' => TRUE),
 159          'suffix' => array('default' => '', 'translatable' => TRUE),
 160          'target' => array('default' => '', 'translatable' => TRUE),
 161          'trim' => array('default' => FALSE),
 162          'max_length' => array('default' => ''),
 163          'word_boundary' => array('default' => TRUE),
 164          'ellipsis' => array('default' => TRUE),
 165          'strip_tags' => array('default' => FALSE),
 166          'html' => array('default' => FALSE),
 167        ),
 168      );
 169      $options['empty'] = array('default' => '', 'translatable' => TRUE);
 170      $options['hide_empty'] = array('default' => FALSE);
 171      $options['empty_zero'] = array('default' => FALSE);
 172  
 173      return $options;
 174    }
 175  
 176    /**
 177     * Default options form that provides the label widget that all fields
 178     * should have.
 179     */
 180    function options_form(&$form, &$form_state) {
 181      $form['label'] = array(
 182        '#type' => 'textfield',
 183        '#title' => t('Label'),
 184        '#default_value' => isset($this->options['label']) ? $this->options['label'] : '',
 185        '#description' => t('The label for this field that will be displayed to end users if the style requires it.'),
 186      );
 187      $form['exclude'] = array(
 188        '#type' => 'checkbox',
 189        '#title' => t('Exclude from display'),
 190        '#default_value' => $this->options['exclude'],
 191        '#description' => t('Check this box to not display this field, but still load it in the view.  Use this option to not show a grouping field in each record, or when doing advanced theming.'),
 192      );
 193  
 194      if ($this->allow_advanced_render()) {
 195        $form['alter']['#tree'] = TRUE;
 196        $form['alter']['alter_text'] = array(
 197          '#type' => 'checkbox',
 198          '#title' => t('Rewrite the output of this field'),
 199          '#description' => t('If checked, you can alter the output of this field by specifying a string of text with replacement tokens that can use any existing field output.'),
 200          '#default_value' => $this->options['alter']['alter_text'],
 201        );
 202  
 203        $form['alter']['text'] = array(
 204          '#title' => t('Text'),
 205          '#type' => 'textarea',
 206          '#default_value' => $this->options['alter']['text'],
 207          '#description' => t('The text to display for this field. You may include HTML. You may enter data from this view as per the "Replacement patterns" below.'),
 208          '#process' => array('views_process_dependency'),
 209          '#dependency' => array(
 210            'edit-options-alter-alter-text' => array(1)
 211          ),
 212        );
 213  
 214        $form['alter']['make_link'] = array(
 215          '#type' => 'checkbox',
 216          '#title' => t('Output this field as a link'),
 217          '#description' => t('If checked, this field will be made into a link. The destination must be given below.'),
 218          '#default_value' => $this->options['alter']['make_link'],
 219        );
 220        $form['alter']['path'] = array(
 221          '#title' => t('Link path'),
 222          '#type' => 'textfield',
 223          '#default_value' => $this->options['alter']['path'],
 224          '#description' => t('The Drupal path or absolute URL for this link. You may enter data from this view as per the "Replacement patterns" below.'),
 225          '#process' => array('views_process_dependency'),
 226          '#dependency' => array(
 227            'edit-options-alter-make-link' => array(1)
 228          ),
 229          '#maxlength' => 255,
 230        );
 231        $form['alter']['link_class'] = array(
 232          '#title' => t('Link class'),
 233          '#type' => 'textfield',
 234          '#default_value' => $this->options['alter']['link_class'],
 235          '#description' => t('The CSS class to apply to the link.'),
 236          '#process' => array('views_process_dependency'),
 237          '#dependency' => array(
 238            'edit-options-alter-make-link' => array(1)
 239          ),
 240        );
 241        $form['alter']['alt'] = array(
 242          '#title' => t('Alt text'),
 243          '#type' => 'textfield',
 244          '#default_value' => $this->options['alter']['alt'],
 245          '#description' => t('Text to place as "alt" text which most browsers display as a tooltip when hovering over the link.'),
 246          '#process' => array('views_process_dependency'),
 247          '#dependency' => array(
 248            'edit-options-alter-make-link' => array(1)
 249          ),
 250        );
 251        $form['alter']['prefix'] = array(
 252          '#title' => t('Prefix text'),
 253          '#type' => 'textfield',
 254          '#default_value' => $this->options['alter']['prefix'],
 255          '#description' => t('Any text to display before this link. You may include HTML.'),
 256          '#process' => array('views_process_dependency'),
 257          '#dependency' => array(
 258            'edit-options-alter-make-link' => array(1)
 259          ),
 260        );
 261        $form['alter']['suffix'] = array(
 262          '#title' => t('Suffix text'),
 263          '#type' => 'textfield',
 264          '#default_value' => $this->options['alter']['suffix'],
 265          '#description' => t('Any text to display after this link. You may include HTML.'),
 266          '#process' => array('views_process_dependency'),
 267          '#dependency' => array(
 268            'edit-options-alter-make-link' => array(1)
 269          ),
 270        );
 271        $form['alter']['target'] = array(
 272          '#title' => t('Target'),
 273          '#type' => 'textfield',
 274          '#default_value' => $this->options['alter']['target'],
 275          '#description' => t("Target of the link, such as _blank, _parent or an iframe's name. This field is rarely used."),
 276          '#process' => array('views_process_dependency'),
 277          '#dependency' => array(
 278            'edit-options-alter-make-link' => array(1)
 279          ),
 280        );
 281  
 282  
 283        // Get a list of the available fields and arguments for token replacement.
 284        $options = array();
 285        foreach ($this->view->display_handler->get_handlers('field') as $field => $handler) {
 286          $options[t('Fields')]["[$field]"] = $handler->ui_name();
 287          // We only use fields up to (and including) this one.
 288          if ($field == $this->options['id']) {
 289            break;
 290          }
 291        }
 292        $count = 0; // This lets us prepare the key as we want it printed.
 293        foreach ($this->view->display_handler->get_handlers('argument') as $arg => $handler) {
 294          $options[t('Arguments')]['%' . ++$count] = t('@argument title', array('@argument' => $handler->ui_name()));
 295          $options[t('Arguments')]['!' . $count] = t('@argument input', array('@argument' => $handler->ui_name()));
 296        }
 297  
 298        $this->document_self_tokens($options[t('Fields')]);
 299  
 300        // Default text.
 301        $output = t('<p>You must add some additional fields to this display before using this field. These fields may be marked as <em>Exclude from display</em> if you prefer. Note that due to rendering order, you cannot use fields that come after this field; if you need a field not listed here, rearrange your fields.</p>');
 302        // We have some options, so make a list.
 303        if (!empty($options)) {
 304          $output = t('<p>The following substitution patterns are available for this display. Use the pattern shown on the left to display the value indicated on the right. Note that due to rendering order, you cannot use fields that come after this field; if you need a field not listed here, rearrange your fields.</p>');
 305          foreach (array_keys($options) as $type) {
 306            if (!empty($options[$type])) {
 307              $items = array();
 308              foreach ($options[$type] as $key => $value) {
 309                $items[] = $key . ' == ' . $value;
 310              }
 311              $output .= theme('item_list', $items, $type);
 312            }
 313          }
 314        }
 315        // This construct uses 'hidden' and not markup because process doesn't
 316        // run. It also has an extra div because the dependency wants to hide
 317        // the parent in situations like this, so we need a second div to
 318        // make this work.
 319        $form['alter']['help'] = array(
 320          '#type' => 'hidden',
 321          '#id' => 'views-tokens-help',
 322          '#prefix' => '<div><fieldset id="views-tokens-help"><legend>' . t('Replacement patterns') . '</legend>' . $output . '</fieldset></div>',
 323          '#process' => array('views_process_dependency'),
 324          '#dependency' => array(
 325            'edit-options-alter-make-link' => array(1),
 326            'edit-options-alter-alter-text' => array(1),
 327          ),
 328        );
 329  
 330        $form['alter']['trim'] = array(
 331          '#type' => 'checkbox',
 332          '#title' => t('Trim this field to a maximum length'),
 333          '#description' => t('If checked, this field be trimmed to a maximum length in characters.'),
 334          '#default_value' => $this->options['alter']['trim'],
 335        );
 336  
 337        $form['alter']['max_length'] = array(
 338          '#title' => t('Maximum length'),
 339          '#type' => 'textfield',
 340          '#default_value' => $this->options['alter']['max_length'],
 341          '#description' => t('The maximum number of characters this field can be.'),
 342          '#process' => array('views_process_dependency'),
 343          '#dependency' => array(
 344            'edit-options-alter-trim' => array(1)
 345          ),
 346        );
 347  
 348        $form['alter']['word_boundary'] = array(
 349          '#type' => 'checkbox',
 350          '#title' => t('Trim only on a word boundary'),
 351          '#description' => t('If checked, this field be trimmed only on a word boundary. This is guaranteed to be the maximum characters stated or less. If there are no word boundaries this could trim a field to nothing.'),
 352          '#default_value' => $this->options['alter']['word_boundary'],
 353          '#process' => array('views_process_dependency'),
 354          '#dependency' => array(
 355            'edit-options-alter-trim' => array(1)
 356          ),
 357        );
 358  
 359        $form['alter']['ellipsis'] = array(
 360          '#type' => 'checkbox',
 361          '#title' => t('Add an ellipsis'),
 362          '#description' => t('If checked, a "..." will be added if a field was trimmed.'),
 363          '#default_value' => $this->options['alter']['ellipsis'],
 364          '#process' => array('views_process_dependency'),
 365          '#dependency' => array(
 366            'edit-options-alter-trim' => array(1)
 367          ),
 368        );
 369  
 370        $form['alter']['html'] = array(
 371          '#type' => 'checkbox',
 372          '#title' => t('Field can contain HTML'),
 373          '#description' => t('If checked, HTML corrector will be run to ensure tags are properly closed after trimming.'),
 374          '#default_value' => $this->options['alter']['html'],
 375          '#process' => array('views_process_dependency'),
 376          '#dependency' => array(
 377            'edit-options-alter-trim' => array(1)
 378          ),
 379        );
 380  
 381        $form['alter']['strip_tags'] = array(
 382          '#type' => 'checkbox',
 383          '#title' => t('Strip HTML tags'),
 384          '#description' => t('If checked, all HTML tags will be stripped.'),
 385          '#default_value' => $this->options['alter']['strip_tags'],
 386          '#process' => array('views_process_dependency'),
 387        );
 388      }
 389  
 390      $form['empty'] = array(
 391        '#type' => 'textfield',
 392        '#title' => t('Empty text'),
 393        '#default_value' => $this->options['empty'],
 394        '#description' => t('If the field is empty, display this text instead.'),
 395      );
 396  
 397      $form['empty_zero'] = array(
 398        '#type' => 'checkbox',
 399        '#title' => t('Count the number 0 as empty'),
 400        '#default_value' => $this->options['empty_zero'],
 401        '#description' => t('If the field contains the number zero, display the empty text instead'),
 402      );
 403  
 404      $form['hide_empty'] = array(
 405        '#type' => 'checkbox',
 406        '#title' => t('Hide if empty'),
 407        '#default_value' => $this->options['hide_empty'],
 408        '#description' => t('Do not display anything for this field if it is empty. Note that the field label may still be displayed. Check style or row style settings to hide labels for empty fields.'),
 409      );
 410    }
 411  
 412    /**
 413     * Provide extra data to the administration form
 414     */
 415    function admin_summary() {
 416      return $this->label();
 417    }
 418  
 419    /**
 420     * Run before any fields are rendered.
 421     *
 422     * This gives the handlers some time to set up before any handler has
 423     * been rendered.
 424     *
 425     * @param $values
 426     *   An array of all objects returned from the query.
 427     */
 428    function pre_render($values) { }
 429  
 430    /**
 431     * Render the field.
 432     *
 433     * @param $values
 434     *   The values retrieved from the database.
 435     */
 436    function render($values) {
 437      $value = $values->{$this->field_alias};
 438      return check_plain($value);
 439    }
 440  
 441    /**
 442     * Render a field using advanced settings.
 443     *
 444     * This renders a field normally, then decides if render-as-link and
 445     * text-replacement rendering is necessary.
 446     */
 447    function advanced_render($values) {
 448      if ($this->allow_advanced_render() && method_exists($this, 'render_item')) {
 449        $raw_items = $this->get_items($values);
 450      }
 451      else {
 452        $this->last_render = $value = $this->render($values);
 453        $this->original_value = $value;
 454      }
 455  
 456      if ($this->allow_advanced_render()) {
 457        $tokens = NULL;
 458        if (method_exists($this, 'render_item')) {
 459          $items = array();
 460          foreach ($raw_items as $count => $item) {
 461            $this->last_render = $this->render_item($count, $item);
 462            $this->original_value = $this->last_render;
 463  
 464            $alter = $item + $this->options['alter'];
 465            $items[] = $this->render_text($alter);
 466          }
 467  
 468          $value = $this->render_items($items);
 469        }
 470        else {
 471          $value = $this->render_text($this->options['alter']);
 472        }
 473  
 474        // This happens here so that render_as_link can get the unaltered value of
 475        // this field as a token rather than the altered value.
 476        $this->last_render = $value;
 477      }
 478  
 479      if (empty($this->last_render)) {
 480        if (($this->last_render !== 0 && $this->last_render !== '0') || !empty($this->options['empty_zero'])) {
 481          $this->last_render = $this->options['empty'];
 482        }
 483      }
 484  
 485      return $this->last_render;
 486    }
 487  
 488    /**
 489     * Perform an advanced text render for the item.
 490     *
 491     * This is separated out as some fields may render lists, and this allows
 492     * each item to be handled individually.
 493     */
 494    function render_text($alter) {
 495      $value = trim($this->last_render);
 496      if ($this->options['hide_empty'] && empty($value) && ($value !== 0 || $this->options['empty_zero'])) {
 497        return '';
 498      }
 499  
 500      if (!empty($alter['alter_text']) && $alter['text'] !== '') {
 501        $tokens = $this->get_render_tokens($alter);
 502        $value = $this->render_altered($alter, $tokens);
 503      }
 504   
 505      if (!empty($alter['strip_tags'])) {
 506        $value = strip_tags($value);
 507      }
 508  
 509      if (!empty($alter['trim']) && !empty($alter['max_length'])) {
 510        $value = $this->render_trim_text($alter, $value);
 511      }
 512  
 513      if (!empty($alter['make_link']) && !empty($alter['path'])) {
 514        if (!isset($tokens)) {
 515         $tokens = $this->get_render_tokens($alter);
 516        }
 517        $value = $this->render_as_link($alter, $value, $tokens);
 518      }
 519  
 520      return $value;
 521    }
 522  
 523    /**
 524     * Render this field as altered text, from a fieldset set by the user.
 525     */
 526    function render_altered($alter, $tokens) {
 527      // Filter this right away as our substitutions are already sanitized.
 528      $value = filter_xss_admin($alter['text']);
 529      $value = strtr($value, $tokens);
 530  
 531      return $value;
 532    }
 533  
 534    /**
 535     * Trim the field down to the specified length.
 536     */
 537    function render_trim_text($alter, $value) {
 538      if (!empty($alter['strip_tags'])) {
 539        // NOTE: It's possible that some external fields might override the
 540        // element type so if someone from, say, CCK runs into a bug here,
 541        // this may be why =)
 542        $this->definition['element type'] = 'span';
 543      }
 544      return views_trim_text($alter, $value);
 545    }
 546  
 547    /**
 548     * Render this field as a link, with the info from a fieldset set by
 549     * the user.
 550     */
 551    function render_as_link($alter, $text, $tokens) {
 552      $value = '';
 553  
 554      if (!empty($alter['prefix'])) {
 555        $value .= filter_xss_admin(strtr($alter['prefix'], $tokens));
 556      }
 557  
 558      $options = array(
 559        'html' => 'true',
 560      );
 561  
 562      // $path will be run through check_url() by l() so we do not need to
 563      // sanitize it ourselves.
 564      $path = $alter['path'];
 565  
 566      // html_entity_decode removes <front>, so check whether its different to front.
 567      if ($path != '<front>') {
 568        // Use strip tags as there should never be HTML in the path.
 569        // However, we need to preserve special characters like " that
 570        // were removed by check_plain().
 571        $path = strip_tags(html_entity_decode(strtr($path, $tokens)));
 572      }
 573  
 574      // If the path is empty do not build a link around the given text and return
 575      // it as is.
 576      if (empty($path)) {
 577        return $text;
 578      }
 579  
 580      // Parse the URL and move any query and fragment parameters out of the path.
 581      $url = parse_url($path);
 582      if (isset($url['query'])) {
 583        $path = strtr($path, array('?' . $url['query'] => ''));
 584        $options['query'] = $url['query'];
 585      }
 586      if (isset($url['fragment'])) {
 587        $path = strtr($path, array('#' . $url['fragment'] => ''));
 588        $options['fragment'] = $url['fragment'];
 589      }
 590  
 591      $alt = strtr($alter['alt'], $tokens);
 592      // Set the title attribute of the link only if it improves accessibility
 593      if ($alt && $alt != $text) {
 594        $options['attributes']['title'] = $alt;
 595      }
 596  
 597      $class = strtr($alter['link_class'], $tokens);
 598      if ($class) {
 599        $options['attributes']['class'] = $class;
 600      }
 601  
 602      $target = check_plain(trim(strtr($alter['target'],$tokens)));
 603      if (!empty($target)) {
 604        $options['attributes']['target'] = $target;
 605      }
 606  
 607      // If the query and fragment were programatically assigned overwrite any
 608      // parsed values.
 609      if (isset($alter['query'])) {
 610        $options['query'] = strtr($alter['query'], $tokens);
 611      }
 612      if (isset($alter['alias'])) {
 613        // Alias is a boolean field, so no token.
 614        $options['alias'] = $alter['alias'];
 615      }
 616      if (isset($alter['fragment'])) {
 617        $options['fragment'] = strtr($alter['fragment'], $tokens);
 618      }
 619      if (isset($this->options['alter']['language'])) {
 620        $options['language'] = $this->options['alter']['language'];
 621      }
 622  
 623      $value .= l($text, $path, $options);
 624  
 625      if (!empty($alter['suffix'])) {
 626        $value .= filter_xss_admin(strtr($alter['suffix'], $tokens));
 627      }
 628  
 629      return $value;
 630    }
 631  
 632    /**
 633     * Get the 'render' tokens to use for advanced rendering.
 634     *
 635     * This runs through all of the fields and arguments that
 636     * are available and gets their values. This will then be
 637     * used in one giant str_replace().
 638     */
 639    function get_render_tokens($item) {
 640      $tokens = array();
 641      if (!empty($this->view->build_info['substitutions'])) {
 642        $tokens = $this->view->build_info['substitutions'];
 643      }
 644      $count = 0;
 645      foreach ($this->view->display_handler->get_handlers('argument') as $arg => $handler) {
 646        $token = '%' . ++$count;
 647        if (!isset($tokens[$token])) {
 648          $tokens[$token] = '';
 649        }
 650  
 651        $tokens['!' . $count] = isset($this->view->args[$count - 1]) ? check_plain($this->view->args[$count - 1]) : '';
 652      }
 653  
 654      // Now add replacements for our fields.
 655      foreach ($this->view->display_handler->get_handlers('field') as $field => $handler) {
 656        if (isset($handler->last_render)) {
 657          $tokens["[$field]"] = $handler->last_render;
 658        }
 659        else {
 660          $tokens["[$field]"] = '';
 661        }
 662        $this->add_self_tokens($tokens, $item);
 663  
 664        // We only use fields up to (and including) this one.
 665        if ($field == $this->options['id']) {
 666          break;
 667        }
 668      }
 669  
 670      return $tokens;
 671    }
 672  
 673    /**
 674     * Add any special tokens this field might use for itself.
 675     *
 676     * This method is intended to be overridden by items that generate
 677     * fields as a list. For example, the field that displays all terms
 678     * on a node might have tokens for the tid and the term.
 679     *
 680     * By convention, tokens should follow the format of [token-subtoken]
 681     * where token is the field ID and subtoken is the field. If the
 682     * field ID is terms, then the tokens might be [terms-tid] and [terms-name].
 683     */
 684    function add_self_tokens(&$tokens, $item) { }
 685  
 686    /**
 687     * Document any special tokens this field might use for itself.
 688     *
 689     * @see add_self_tokens() for details.
 690     */
 691    function document_self_tokens(&$tokens) { }
 692  
 693    /**
 694     * Call out to the theme() function, which probably just calls render() but
 695     * allows sites to override output fairly easily.
 696     */
 697    function theme($values) {
 698      return theme($this->theme_functions(), $this->view, $this, $values);
 699    }
 700  
 701    function theme_functions() {
 702      $themes = array();
 703      $hook = 'views_view_field';
 704  
 705      $display = $this->view->display[$this->view->current_display];
 706  
 707      if (!empty($display)) {
 708        $themes[] = $hook . '__' . $this->view->name  . '__' . $display->id . '__' . $this->options['id'];
 709        $themes[] = $hook . '__' . $this->view->name  . '__' . $display->id;
 710        $themes[] = $hook . '__' . $display->id . '__' . $this->options['id'];
 711        $themes[] = $hook . '__' . $display->id;
 712        if ($display->id != $display->display_plugin) {
 713          $themes[] = $hook . '__' . $this->view->name  . '__' . $display->display_plugin . '__' . $this->options['id'];
 714          $themes[] = $hook . '__' . $this->view->name  . '__' . $display->display_plugin;
 715          $themes[] = $hook . '__' . $display->display_plugin . '__' . $this->options['id'];
 716          $themes[] = $hook . '__' . $display->display_plugin;
 717        }
 718      }
 719      $themes[] = $hook . '__' . $this->view->name . '__' . $this->options['id'];
 720      $themes[] = $hook . '__' . $this->view->name;
 721      $themes[] = $hook . '__' . $this->options['id'];
 722      $themes[] = $hook;
 723  
 724      return $themes;
 725    }
 726  }
 727  
 728  /**
 729   * A special handler to take the place of missing or broken handlers.
 730   */
 731  class views_handler_field_broken extends views_handler_field {
 732    function ui_name($short = FALSE) {
 733      return t('Broken/missing handler');
 734    }
 735  
 736    function ensure_my_table() { /* No table to ensure! */ }
 737    function query() { /* No query to run */ }
 738    function options_form(&$form, &$form_state) {
 739      $form['markup'] = array(
 740        '#prefix' => '<div class="form-item description">',
 741        '#value' => t('The handler for this item is broken or missing and cannot be used. If a module provided the handler and was disabled, re-enabling the module may restore it. Otherwise, you should probably delete this item.'),
 742      );
 743    }
 744  
 745    /**
 746     * Determine if the handler is considered 'broken'
 747     */
 748    function broken() { return TRUE; }
 749  }
 750  
 751  /**
 752   * Render a numeric value as a size.
 753   */
 754  class views_handler_field_file_size extends views_handler_field {
 755    function option_definition() {
 756      $options = parent::option_definition();
 757  
 758      $options['file_size_display'] = array('default' => 'formatted');
 759  
 760      return $options;
 761    }
 762  
 763    function options_form(&$form, &$form_state) {
 764      parent::options_form($form, $form_state);
 765      $form['file_size_display'] = array(
 766        '#title' => t('File size display'),
 767        '#type' => 'select',
 768        '#options' => array(
 769          'formatted' => t('Formatted (in KB or MB)'),
 770          'bytes' => t('Raw bytes'),
 771        ),
 772      );
 773    }
 774  
 775    function render($values) {
 776      if ($values->{$this->field_alias}) {
 777        switch ($this->options['file_size_display']) {
 778          case 'bytes':
 779            return $values->{$this->field_alias};
 780          case 'formatted':
 781          default:
 782            return format_size($values->{$this->field_alias});
 783        }
 784      }
 785      else {
 786        return '';
 787      }
 788    }
 789  }
 790  
 791  /**
 792   * A handler to run a field through simple XSS filtering
 793   */
 794  class views_handler_field_xss extends views_handler_field {
 795    function render($values) {
 796      $value = $values->{$this->field_alias};
 797      return filter_xss($value);
 798    }
 799  }
 800  
 801  /**
 802   * @}
 803   */
 804