[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * @defgroup views_style_plugins Views' style plugins
   5   * @{
   6   * Style plugins control how a view is rendered. For example, they
   7   * can choose to display a collection of fields, node_view() output,
   8   * table output, or any kind of crazy output they want.
   9   *
  10   * Many style plugins can have an optional 'row' plugin, that displays
  11   * a single record. Not all style plugins can utilize this, so it is
  12   * up to the plugin to set this up and call through to the row plugin.
  13   *
  14   * @see hook_views_plugins
  15   */
  16  
  17  /**
  18   * Base class to define a style plugin handler.
  19   */
  20  class views_plugin_style extends views_plugin {
  21    /**
  22     * Initialize a style plugin.
  23     *
  24     * @param $view
  25     * @param $display
  26     * @param $options
  27     *   The style options might come externally as the style can be sourced
  28     *   from at least two locations. If it's not included, look on the display.
  29     */
  30    function init(&$view, &$display, $options = NULL) {
  31      $this->view = &$view;
  32      $this->display = &$display;
  33  
  34      // Overlay incoming options on top of defaults
  35      $this->unpack_options($this->options, isset($options) ? $options : $display->handler->get_option('style_options'));
  36  
  37      if ($this->uses_row_plugin() && $display->handler->get_option('row_plugin')) {
  38        $this->row_plugin = $display->handler->get_plugin('row');
  39      }
  40  
  41      $this->options += array(
  42        'grouping' => '',
  43      );
  44  
  45      $this->definition += array(
  46        'uses grouping' => TRUE,
  47      );
  48    }
  49  
  50    function destroy() {
  51      parent::destroy();
  52  
  53      if (isset($this->row_plugin)) {
  54        $this->row_plugin->destroy();
  55      }
  56    }
  57  
  58    /**
  59     * Return TRUE if this style also uses a row plugin.
  60     */
  61    function uses_row_plugin() {
  62      return !empty($this->definition['uses row plugin']);
  63    }
  64  
  65    /**
  66     * Return TRUE if this style also uses fields.
  67     */
  68    function uses_fields() {
  69      // If we use a row plugin, ask the row plugin. Chances are, we don't
  70      // care, it does.
  71      if ($this->uses_row_plugin() && !empty($this->row_plugin)) {
  72        return $this->row_plugin->uses_fields();
  73      }
  74      // Otherwise, maybe we do.
  75      return !empty($this->definition['uses fields']);
  76    }
  77  
  78    function option_definition() {
  79      $options = parent::option_definition();
  80      $options['grouping'] = array('default' => '');
  81      return $options;
  82    }
  83  
  84    function options_form(&$form, &$form_state) {
  85      // Only fields-based views can handle grouping.  Style plugins can also exclude
  86      // themselves from being groupable by setting their "use grouping" definiton
  87      // key to FALSE.
  88      // @TODO: Document "uses grouping" in docs.php when docs.php is written.
  89      if ($this->uses_fields() && $this->definition['uses grouping']) {
  90        $options = array('' => t('- None -'));
  91        $options += $this->display->handler->get_field_labels();
  92  
  93        // If there are no fields, we can't group on them.
  94        if (count($options) > 1) {
  95          $form['grouping'] = array(
  96            '#type' => 'select',
  97            '#title' => t('Grouping field'),
  98            '#options' => $options,
  99            '#default_value' => $this->options['grouping'],
 100            '#description' => t('You may optionally specify a field by which to group the records. Leave blank to not group.'),
 101          );
 102        }
 103      }
 104    }
 105  
 106    /**
 107     * Called by the view builder to see if this style handler wants to
 108     * interfere with the sorts. If so it should build; if it returns
 109     * any non-TRUE value, normal sorting will NOT be added to the query.
 110     */
 111    function build_sort() { return TRUE; }
 112  
 113    /**
 114     * Called by the view builder to let the style build a second set of
 115     * sorts that will come after any other sorts in the view.
 116     */
 117    function build_sort_post() { }
 118  
 119    /**
 120     * Allow the style to do stuff before each row is rendered.
 121     *
 122     * @param $result
 123     *   The full array of results from the query.
 124     */
 125    function pre_render($result) {
 126      if (!empty($this->row_plugin)) {
 127        $this->row_plugin->pre_render($result);
 128      }
 129    }
 130  
 131    /**
 132     * Render the display in this style.
 133     */
 134    function render() {
 135      if ($this->uses_row_plugin() && empty($this->row_plugin)) {
 136        vpr('views_plugin_style_default: Missing row plugin');
 137        return;
 138      }
 139  
 140      // Group the rows according to the grouping field, if specified.
 141      $sets = $this->render_grouping($this->view->result, $this->options['grouping']);
 142  
 143      // Render each group separately and concatenate.  Plugins may override this
 144      // method if they wish some other way of handling grouping.
 145      $output = '';
 146      foreach ($sets as $title => $records) {
 147        if ($this->uses_row_plugin()) {
 148          $rows = array();
 149          foreach ($records as $row_index => $row) {
 150            $this->view->row_index = $row_index;
 151            $rows[] = $this->row_plugin->render($row);
 152          }
 153        }
 154        else {
 155          $rows = $records;
 156        }
 157  
 158        $output .= theme($this->theme_functions(), $this->view, $this->options, $rows, $title);
 159      }
 160      unset($this->view->row_index);
 161      return $output;
 162    }
 163  
 164    /**
 165     * Group records as needed for rendering.
 166     *
 167     * @param $records
 168     *   An array of records from the view to group.
 169     * @param $grouping_field
 170     *   The field id on which to group.  If empty, the result set will be given
 171     *   a single group with an empty string as a label.
 172     * @return
 173     *   The grouped record set.
 174     */
 175    function render_grouping($records, $grouping_field = '') {
 176      // Make sure fields are rendered
 177      $this->render_fields($this->view->result);
 178      $sets = array();
 179      if ($grouping_field) {
 180        foreach ($records as $index => $row) {
 181          $grouping = '';
 182          // Group on the rendered version of the field, not the raw.  That way,
 183          // we can control any special formatting of the grouping field through
 184          // the admin or theme layer or anywhere else we'd like.
 185          if (isset($this->view->field[$grouping_field])) {
 186            $grouping = $this->get_field($index, $grouping_field);
 187            if ($this->view->field[$grouping_field]->options['label']) {
 188              $grouping = $this->view->field[$grouping_field]->options['label'] . ': ' . $grouping;
 189            }
 190          }
 191          $sets[$grouping][$index] = $row;
 192        }
 193      }
 194      else {
 195        // Create a single group with an empty grouping field.
 196        $sets[''] = $records;
 197      }
 198      return $sets;
 199    }
 200  
 201    /**
 202     * Render all of the fields for a given style and store them on the object.
 203     *
 204     * @param $result
 205     *   The result array from $view->result
 206     */
 207    function render_fields($result) {
 208      if (!$this->uses_fields()) {
 209        return;
 210      }
 211  
 212      if (isset($this->rendered_fields)) {
 213        return $this->rendered_fields;
 214      }
 215  
 216      $this->view->row_index = 0;
 217      $keys = array_keys($this->view->field);
 218      foreach ($result as $count => $row) {
 219        $this->view->row_index = $count;
 220        foreach ($keys as $id) {
 221          $this->rendered_fields[$count][$id] = $this->view->field[$id]->theme($row);
 222        }
 223      }
 224      unset($this->view->row_index);
 225    }
 226  
 227    /**
 228     * Get a rendered field.
 229     *
 230     * @param $index
 231     *   The index count of the row.
 232     * @param $field
 233     *    The id of the field.
 234     */
 235    function get_field($index, $field) {
 236      if (!isset($this->rendered_fields)) {
 237        $this->render_fields($this->view->result);
 238      }
 239  
 240      if (isset($this->rendered_fields[$index][$field])) {
 241        return $this->rendered_fields[$index][$field];
 242      }
 243    }
 244  
 245    function validate() {
 246      $errors = parent::validate();
 247  
 248      if ($this->uses_row_plugin()) {
 249        $plugin = $this->display->handler->get_plugin('row');
 250        if (empty($plugin)) {
 251          $errors[] = t('Style @style requires a row style but the row plugin is invalid.', array('@style' => $this->definition['title']));
 252        }
 253        else {
 254          $result = $plugin->validate();
 255          if (!empty($result) && is_array($result)) {
 256            $errors = array_merge($errors, $result);
 257          }
 258        }
 259      }
 260      return $errors;
 261    }
 262  
 263    function query() {
 264      parent::query();
 265      if (isset($this->row_plugin)) {
 266        $this->row_plugin->query();
 267      }
 268    }
 269  }
 270  
 271  /**
 272   * @}
 273   */
 274