Relationship handler that allows a groupwise maximum of the linked in table. More...

Inheritance diagram for views_handler_relationship_groupwise_max:

Public Member Functions
	option_definition ()
	Defines default values for options.
	options_form (&$form, &$form_state)
	Extends the relationship's basic options, allowing the user to pick a sort and an order for it.
	options_submit (&$form, &$form_state)
	Perform any necessary changes to the form values prior to storage.
	get_temporary_view ()
	Helper function to create a pseudo view.
	left_query ($options)
	Generate a subquery given the user options, as set in the options.
	alter_subquery_condition (QueryAlterableInterface $query, &$conditions)
	Recursive helper to add a namespace to conditions.
	condition_namespace ($string)
	Helper function to namespace query pieces.
	query ()
	Called to implement a relationship in a query.
	init (&$view, &$options)
	Init handler to let relationships live on tables other than the table they operate on.
	label ()
	Get this field's label.
	use_group_by ()
	You can't groupby a relationship.
	ui_name ($short=FALSE)
	Return a string representing this handler's name in the UI.
	get_field ($field=NULL)
	Shortcut to get a handler's raw field value.
	sanitize_value ($value, $type=NULL)
	Sanitize the value for output.
	case_transform ($string, $option)
	Transform a string by a certain method.
	options_validate (&$form, &$form_state)
	Validate the options form.
	groupby_form (&$form, &$form_state)
	Provide a form for aggregation settings.
	groupby_form_submit (&$form, &$form_state)
	Perform any necessary changes to the form values prior to storage.
	has_extra_options ()
	If a handler has 'extra options' it will get a little settings widget and another form called extra_options.
	extra_options (&$option)
	Provide defaults for the handler.
	extra_options_form (&$form, &$form_state)
	Provide a form for setting options.
	extra_options_validate ($form, &$form_state)
	Validate the options form.
	extra_options_submit ($form, &$form_state)
	Perform any necessary changes to the form values prior to storage.
	can_expose ()
	Determine if a handler can be exposed.
	expose_options ()
	Set new exposed option defaults when exposed setting is flipped on.
	exposed_info ()
	Get information about the exposed form for the form renderer.
	exposed_form (&$form, &$form_state)
	Render our chunk of the exposed handler form when selecting.
	exposed_validate (&$form, &$form_state)
	Validate the exposed handler form.
	exposed_submit (&$form, &$form_state)
	Submit the exposed handler form.
	expose_form (&$form, &$form_state)
	Form for exposed handler options.
	expose_validate ($form, &$form_state)
	Validate the options form.
	expose_submit ($form, &$form_state)
	Perform any necessary changes to the form exposes prior to storage.
	show_expose_button (&$form, &$form_state)
	Shortcut to display the expose/hide button.
	show_expose_form (&$form, &$form_state)
	Shortcut to display the exposed options form.
	access ()
	Check whether current user has access to this handler.
	pre_query ()
	Run before the view is built.
	post_execute (&$values)
	Run after the view is executed, before the result is cached.
	placeholder ()
	Provides a unique placeholders for handlers.
	set_relationship ()
	Called just prior to query(), this lets a handler set up any relationship it needs.
	ensure_my_table ()
	Ensure the main table for this handler is in the query.
	admin_summary ()
	Provide text for the administrative summary.
	needs_style_plugin ()
	Determine if the argument needs a style plugin.
	is_exposed ()
	Determine if this item is 'exposed', meaning it provides form elements to let users modify the view.
	accept_exposed_input ($input)
	Take input from exposed handlers and assign to this handler, if necessary.
	store_exposed_input ($input, $status)
	If set to remember exposed input in the session, store it there.
	get_join ()
	Get the join object that should be used for this handler.
	validate ()
	Validates the handler against the complete View.
	broken ()
	Determine if the handler is considered 'broken', meaning it's a a placeholder used when a handler can't be found.
	construct ()
	Views handlers use a special construct function so that we can more easily construct them with variable arguments.
	options (&$options)
	Set default options on this object.
	set_default_options ()
	Set default options.
	_set_option_defaults (&$storage, $options, $level=0)
	unpack_options (&$storage, $options, $definition=NULL, $all=TRUE, $check=TRUE, $localization_keys=array())
	Unpack options over our existing defaults, drilling down into arrays so that defaults don't get totally blown away.
	set_definition ($definition)
	Let the handler know what its full definition is.
	destroy ()
	export_options ($indent, $prefix)
	export_option ($indent, $prefix, $storage, $option, $definition, $parents)
	unpack_translatables (&$translatable, $parents=array())
	Unpacks each handler to store translatable texts.
	unpack_translatable (&$translatable, $storage, $option, $definition, $parents, $keys=array())
	Unpack a single option definition.
Public Attributes
	$view = NULL
	$query = NULL
	$handler_type = NULL
	The type of the handler, for example filter/footer/field.
	$table_alias
	The alias of the table of this handler which is used in the query.
	$real_field
	The actual field in the database table, maybe different on other kind of query plugins/special handlers.
	$relationship = NULL
	The relationship used for this field.
	$options = array()
	Except for displays, options for the object will be held here.
	$definition

Detailed Description

Relationship handler that allows a groupwise maximum of the linked in table.

For a definition, see: http://dev.mysql.com/doc/refman/5.0/en/example-maximum-column-group-row.html In lay terms, instead of joining to get all matching records in the linked table, we get only one record, a 'representative record' picked according to a given criteria.

Example: Suppose we have a term view that gives us the terms: Horse, Cat, Aardvark. We wish to show for each term the most recent node of that term. What we want is some kind of relationship from term to node. But a regular relationship will give us all the nodes for each term, giving the view multiple rows per term. What we want is just one representative node per term, the node that is the 'best' in some way: eg, the most recent, the most commented on, the first in alphabetical order.

This handler gives us that kind of relationship from term to node. The method of choosing the 'best' implemented with a sort that the user selects in the relationship settings.

So if we want our term view to show the most commented node for each term, add the relationship and in its options, pick the 'Comment count' sort.

Relationship definition

'outer field': The outer field to substitute into the correlated subquery. This must be the full field name, not the alias. Eg: 'term_data.tid'.
'argument table', 'argument field': These options define a views argument that the subquery must add to itself to filter by the main view. Example: the main view shows terms, this handler is being used to get to the nodes base table. Your argument must be 'term_node', 'tid', as this is the argument that should be added to a node view to filter on terms.

A note on performance: This relationship uses a correlated subquery, which is expensive. Subsequent versions of this handler could also implement the alternative way of doing this, with a join -- though this looks like it could be pretty messy to implement. This is also an expensive method, so providing both methods and allowing the user to choose which one works fastest for their data might be the best way. If your use of this relationship handler is likely to result in large data sets, you might want to consider storing statistics in a separate table, in the same way as node_comment_statistics.

Definition at line 56 of file views_handler_relationship_groupwise_max.inc.

Member Function Documentation

views_handler::accept_exposed_input ( $ input ) [inherited]

Take input from exposed handlers and assign to this handler, if necessary.

Reimplemented in views_handler_filter, views_handler_filter_date, views_handler_filter_in_operator, views_handler_filter_numeric, views_handler_filter_term_node_tid, and views_handler_filter_user_name.

Definition at line 669 of file handlers.inc.

{ return TRUE; }

views_handler::access ( ) [inherited]

Check whether current user has access to this handler.

Returns:: boolean

Reimplemented in views_handler_field_comment_link_approve, views_handler_field_comment_link_delete, views_handler_field_comment_link_reply, views_handler_field_contact_link, views_handler_field_field, views_handler_field_locale_link_edit, views_handler_field_node_revision_link_delete, views_handler_field_node_revision_link_revert, and views_handler_field_user_link.

Definition at line 564 of file handlers.inc.

                    {
    if (isset($this->definition['access callback']) && function_exists($this->definition['access callback'])) {
      if (isset($this->definition['access arguments']) && is_array($this->definition['access arguments'])) {
        return call_user_func_array($this->definition['access callback'], $this->definition['access arguments']);
      }
      return $this->definition['access callback']();
    }

    return TRUE;
  }

views_handler::admin_summary ( ) [inherited]

Provide text for the administrative summary.

Reimplemented in views_handler_area, views_handler_field, views_handler_filter, views_handler_filter_boolean_operator, views_handler_filter_in_operator, views_handler_filter_numeric, views_handler_filter_string, views_handler_sort, views_handler_filter_history_user_timestamp, views_handler_filter_node_access, views_handler_filter_node_status, views_handler_filter_term_node_tid, views_handler_filter_node_tnid, views_handler_filter_node_tnid_child, and views_handler_filter_user_name.

Definition at line 647 of file handlers.inc.

{ }

views_handler_relationship_groupwise_max::alter_subquery_condition	(	QueryAlterableInterface $	query,
		&$	conditions
	)

Recursive helper to add a namespace to conditions.

(Though why is the condition we get in a simple query 3 levels deep???)

Definition at line 311 of file views_handler_relationship_groupwise_max.inc.

References condition_namespace().

Referenced by left_query().

                                                                                  {
    foreach ($conditions as $condition_id => &$condition) {
      // Skip the #conjunction element.
      if (is_numeric($condition_id)) {
        if (is_string($condition['field'])) {
          $condition['field'] = $this->condition_namespace($condition['field']);
        }
        elseif (is_object($condition['field'])) {
          $sub_conditions =& $condition['field']->conditions();
          $this->alter_subquery_condition($query, $sub_conditions);
        }
      }
    }
  }

views_handler::broken ( ) [inherited]

Determine if the handler is considered 'broken', meaning it's a a placeholder used when a handler can't be found.

Reimplemented in views_handler_area_broken, views_handler_argument_broken, views_handler_field_broken, views_handler_filter_broken, views_handler_relationship_broken, and views_handler_sort_broken.

Definition at line 716 of file handlers.inc.

{ }

views_handler::can_expose ( ) [inherited]

Determine if a handler can be exposed.

Reimplemented in views_handler_filter, views_handler_sort, views_handler_filter_node_access, views_handler_filter_node_status, views_handler_filter_node_tnid, and views_handler_filter_node_tnid_child.

Definition at line 487 of file handlers.inc.

{ return FALSE; }

views_handler::case_transform	(	$	string,
		$	option
	)			`[inherited]`

Transform a string by a certain method.

Parameters:

$string

The input you want to transform.

$option

How do you want to transform it, possible values:

upper: Uppercase the string.
lower: lowercase the string.
ucfirst: Make the first char uppercase.
ucwords: Make each word in the string uppercase.

Returns:: string The transformed string.

Definition at line 347 of file handlers.inc.

Referenced by views_handler_argument_string::summary_argument().

                                            {
    global $multibyte;

    switch ($option) {
      default:
        return $string;
      case 'upper':
        return drupal_strtoupper($string);
      case 'lower':
        return drupal_strtolower($string);
      case 'ucfirst':
        return drupal_strtoupper(drupal_substr($string, 0, 1)) . drupal_substr($string, 1);
      case 'ucwords':
        if ($multibyte == UNICODE_MULTIBYTE) {
          return mb_convert_case($string, MB_CASE_TITLE);
        }
        else {
          return ucwords($string);
        }
    }
  }

views_handler_relationship_groupwise_max::condition_namespace ( $ string )

Helper function to namespace query pieces.

Turns 'foo.bar' into 'foo_NAMESPACE.bar'.

Definition at line 331 of file views_handler_relationship_groupwise_max.inc.

Referenced by alter_subquery_condition(), and left_query().

                                        {
    return str_replace('.', $this->subquery_namespace . '.', $string);
  }

views_object::construct ( ) [inherited]

Views handlers use a special construct function so that we can more easily construct them with variable arguments.

Definition at line 54 of file base.inc.

References views_object::set_default_options().

{ $this->set_default_options(); }

views_handler::ensure_my_table ( ) [inherited]

Ensure the main table for this handler is in the query.

This is used a lot.

Reimplemented in views_handler_area_broken, views_handler_argument_broken, views_handler_argument_many_to_one, views_handler_field_broken, views_handler_filter_broken, views_handler_filter_many_to_one, views_handler_relationship_broken, and views_handler_sort_broken.

Definition at line 633 of file handlers.inc.

References vpr().

                             {
    if (!isset($this->table_alias)) {
      if (!method_exists($this->query, 'ensure_table')) {
        vpr(t('Ensure my table called but query has no ensure_table method.'));
        return;
      }
      $this->table_alias = $this->query->ensure_table($this->table, $this->relationship);
    }
    return $this->table_alias;
  }

views_handler::expose_form	(	&$	form,
		&$	form_state
	)			`[inherited]`

Form for exposed handler options.

Reimplemented in views_handler_filter, views_handler_filter_in_operator, views_handler_sort, views_handler_filter_history_user_timestamp, and views_handler_filter_term_node_tid.

Definition at line 518 of file handlers.inc.

Referenced by views_handler::show_expose_form().

{ }

views_handler::expose_options ( ) [inherited]

Set new exposed option defaults when exposed setting is flipped on.

Reimplemented in views_handler_filter, views_handler_filter_boolean_operator, views_handler_filter_in_operator, and views_handler_sort.

Definition at line 493 of file handlers.inc.

{ }

views_handler::expose_submit	(	$	form,
		&$	form_state
	)			`[inherited]`

Perform any necessary changes to the form exposes prior to storage.

There is no need for this function to actually store the data.

Definition at line 529 of file handlers.inc.

Referenced by views_handler_sort::options_submit(), and views_handler_filter::options_submit().

{ }

views_handler::expose_validate	(	$	form,
		&$	form_state
	)			`[inherited]`

Validate the options form.

Reimplemented in views_handler_filter.

Definition at line 523 of file handlers.inc.

Referenced by views_handler_sort::options_validate().

{ }

views_handler::exposed_form	(	&$	form,
		&$	form_state
	)			`[inherited]`

Render our chunk of the exposed handler form when selecting.

Reimplemented in views_handler_filter.

Definition at line 503 of file handlers.inc.

{ }

views_handler::exposed_info ( ) [inherited]

Get information about the exposed form for the form renderer.

Reimplemented in views_handler_filter.

Definition at line 498 of file handlers.inc.

{ }

views_handler::exposed_submit	(	&$	form,
		&$	form_state
	)			`[inherited]`

Submit the exposed handler form.

Definition at line 513 of file handlers.inc.

{ }

views_handler::exposed_validate	(	&$	form,
		&$	form_state
	)			`[inherited]`

Validate the exposed handler form.

Reimplemented in views_handler_filter_date, views_handler_filter_search, views_handler_filter_term_node_tid, and views_handler_filter_user_name.

Definition at line 508 of file handlers.inc.

{ }

views_handler::extra_options ( &$ option ) [inherited]

Provide defaults for the handler.

Definition at line 466 of file handlers.inc.

{ }

views_handler::extra_options_form	(	&$	form,
		&$	form_state
	)			`[inherited]`

Provide a form for setting options.

Reimplemented in views_handler_filter_term_node_tid, and views_handler_filter_term_node_tid_depth.

Definition at line 471 of file handlers.inc.

{ }

views_handler::extra_options_submit	(	$	form,
		&$	form_state
	)			`[inherited]`

Perform any necessary changes to the form values prior to storage.

There is no need for this function to actually store the data.

Definition at line 482 of file handlers.inc.

{ }

views_handler::extra_options_validate	(	$	form,
		&$	form_state
	)			`[inherited]`

Validate the options form.

Definition at line 476 of file handlers.inc.

{ }

views_handler::get_field ( $ field = NULL ) [inherited]

Shortcut to get a handler's raw field value.

This should be overridden for handlers with formulae or other non-standard fields. Because this takes an argument, fields overriding this can just call return parent::get_field($formula)

Definition at line 285 of file handlers.inc.

References views_object::options().

Referenced by views_handler_filter_group_by_numeric::query(), views_handler_argument_group_by_numeric::query(), views_handler_sort_group_by_numeric::ui_name(), views_handler_filter_group_by_numeric::ui_name(), and views_handler_argument_group_by_numeric::ui_name().

                                    {
    if (!isset($field)) {
      if (!empty($this->formula)) {
        $field = $this->get_formula();
      }
      else {
        $field = $this->table_alias . '.' . $this->real_field;
      }
    }

    // If grouping, check to see if the aggregation method needs to modify the field.
    if ($this->view->display_handler->use_group_by()) {
      $this->view->init_query();
      if ($this->query) {
        $info = $this->query->get_aggregation_info();
        if (!empty($info[$this->options['group_type']]['method']) && function_exists($info[$this->options['group_type']]['method'])) {
          return $info[$this->options['group_type']]['method']($this->options['group_type'], $field);
        }
      }
    }

    return $field;
  }

views_handler::get_join ( ) [inherited]

Get the join object that should be used for this handler.

This method isn't used a great deal, but it's very handy for easily getting the join if it is necessary to make some changes to it, such as adding an 'extra'.

Definition at line 683 of file handlers.inc.

References views_get_table_join().

Referenced by views_handler_argument_many_to_one::summary_query().

                      {
    // get the join from this table that links back to the base table.
    // Determine the primary table to seek
    if (empty($this->query->relationships[$this->relationship])) {
      $base_table = $this->query->base_table;
    }
    else {
      $base_table = $this->query->relationships[$this->relationship]['base'];
    }

    $join = views_get_table_join($this->table, $base_table);
    if ($join) {
      return clone $join;
    }
  }

views_handler_relationship_groupwise_max::get_temporary_view ( )

Helper function to create a pseudo view.

We use this to obtain our subquery SQL.

Definition at line 170 of file views_handler_relationship_groupwise_max.inc.

References views_include().

Referenced by left_query().

                                {
    views_include('view');
    $view = new view();
    $view->vid = 'new'; // @todo: what's this?
    $view->base_table = $this->definition['base'];
    $view->add_display('default');
    return $view;
  }

views_handler::groupby_form	(	&$	form,
		&$	form_state
	)			`[inherited]`

Provide a form for aggregation settings.

Reimplemented in views_handler_field_field.

Definition at line 420 of file handlers.inc.

References views_object::options(), views_handler::ui_name(), and views_object_types().

                                              {
    $view = &$form_state['view'];
    $display_id = $form_state['display_id'];
    $types = views_object_types();
    $type = $form_state['type'];
    $id = $form_state['id'];

    $form['#title'] = check_plain($view->display[$display_id]->display_title) . ': ';
    $form['#title'] .= t('Configure aggregation settings for @type %item', array('@type' => $types[$type]['lstitle'], '%item' => $this->ui_name()));

    $form['#section'] = $display_id . '-' . $type . '-' . $id;

    $view->init_query();
    $info = $view->query->get_aggregation_info();
    foreach ($info as $id => $aggregate) {
      $group_types[$id] = $aggregate['title'];
    }

    $form['group_type'] = array(
      '#type' => 'select',
      '#title' => t('Aggregation type'),
      '#default_value' => $this->options['group_type'],
      '#description' => t('Select the aggregation function to use on this field.'),
      '#options' => $group_types,
    );
  }

views_handler::groupby_form_submit	(	&$	form,
		&$	form_state
	)			`[inherited]`

Perform any necessary changes to the form values prior to storage.

There is no need for this function to actually store the data.

Reimplemented in views_handler_field_field.

Definition at line 451 of file handlers.inc.

                                                     {
    $item =& $form_state['handler']->options;

    $item['group_type'] = $form_state['values']['options']['group_type'];
  }

views_handler::has_extra_options ( ) [inherited]

If a handler has 'extra options' it will get a little settings widget and another form called extra_options.

Reimplemented in views_handler_filter_term_node_tid.

Definition at line 461 of file handlers.inc.

{ return FALSE; }

views_handler_relationship::init	(	&$	view,
		&$	options
	)			`[inherited]`

Init handler to let relationships live on tables other than the table they operate on.

Reimplemented from views_handler.

Reimplemented in views_handler_relationship_entity_reverse, and views_handler_relationship_node_term_data.

Definition at line 40 of file views_handler_relationship.inc.

References views_object::$options.

                                   {
    parent::init($view, $options);
    if (isset($this->definition['relationship table'])) {
      $this->table = $this->definition['relationship table'];
    }
    if (isset($this->definition['relationship field'])) {
      // Set both real_field and field so custom handler
      // can rely on the old field value.
      $this->real_field = $this->field = $this->definition['relationship field'];
    }
  }

views_handler::is_exposed ( ) [inherited]

Determine if this item is 'exposed', meaning it provides form elements to let users modify the view.

Returns:: TRUE/FALSE

Definition at line 662 of file handlers.inc.

References views_object::options().

                        {
    return !empty($this->options['exposed']);
  }

views_handler_relationship::label ( ) [inherited]

Get this field's label.

Definition at line 55 of file views_handler_relationship.inc.

References views_object::options(), and views_handler::ui_name().

                   {
    if (!isset($this->options['label'])) {
      return $this->ui_name();
    }
    return $this->options['label'];
  }

views_handler_relationship_groupwise_max::left_query ( $ options )

Generate a subquery given the user options, as set in the options.

These are passed in rather than picked up from the object because we generate the subquery when the options are saved, rather than when the view is run. This saves considerable time.

Parameters:

$options

An array of options:

subquery_sort: the id of a views sort.
subquery_order: either ASC or DESC.

Returns:: The subquery SQL string, ready for use in the main query.

Definition at line 192 of file views_handler_relationship_groupwise_max.inc.

References views_object::$options, alter_subquery_condition(), condition_namespace(), get_temporary_view(), views_fetch_data(), and views_get_view().

Referenced by options_submit(), and query().

                                {
    // Either load another view, or create one on the fly.
    if ($options['subquery_view']) {
      $temp_view = views_get_view($options['subquery_view']);
      // Remove all fields from default display
      unset($temp_view->display['default']->display_options['fields']);
    }
    else {
      // Create a new view object on the fly, which we use to generate a query
      // object and then get the SQL we need for the subquery.
      $temp_view = $this->get_temporary_view();

      // Add the sort from the options to the default display.
      // This is broken, in that the sort order field also gets added as a
      // select field. See http://drupal.org/node/844910.
      // We work around this further down.
      $sort = $options['subquery_sort'];
      list($sort_table, $sort_field) = explode('.', $sort);
      $sort_options = array('order' => $options['subquery_order']);
      $temp_view->add_item('default', 'sort', $sort_table, $sort_field, $sort_options);
    }

    // Get the namespace string.
    $temp_view->namespace = (!empty($options['subquery_namespace'])) ? '_'. $options['subquery_namespace'] : '_INNER';
    $this->subquery_namespace = (!empty($options['subquery_namespace'])) ? '_'. $options['subquery_namespace'] : 'INNER';

    // The value we add here does nothing, but doing this adds the right tables
    // and puts in a WHERE clause with a placeholder we can grab later.
    $temp_view->args[] = '**CORRELATED**';

    // Add the base table ID field.
    $views_data = views_fetch_data($this->definition['base']);
    $base_field = $views_data['table']['base']['field'];
    $temp_view->add_item('default', 'field', $this->definition['base'], $this->definition['field']);

    // Add the correct argument for our relationship's base
    // ie the 'how to get back to base' argument.
    // The relationship definition tells us which one to use.
    $temp_view->add_item(
      'default',
      'argument',
      $this->definition['argument table'], // eg 'term_node',
      $this->definition['argument field'] //  eg 'tid'
    );

    // Build the view. The creates the query object and produces the query
    // string but does not run any queries.
    $temp_view->build();

    // Now take the SelectQuery object the View has built and massage it
    // somewhat so we can get the SQL query from it.
    $subquery = $temp_view->build_info['query'];

    // Workaround until http://drupal.org/node/844910 is fixed:
    // Remove all fields from the SELECT except the base id.
    $fields =& $subquery->getFields();
    foreach (array_keys($fields) as $field_name) {
      // The base id for this subquery is stored in our definition.
      if ($field_name != $this->definition['field']) {
        unset($fields[$field_name]);
      }
    }

    // Make every alias in the subquery safe within the outer query by
    // appending a namespace to it, '_inner' by default.
    $tables =& $subquery->getTables();
    foreach (array_keys($tables) as $table_name) {
      $tables[$table_name]['alias'] .= $this->subquery_namespace;
      // Namespace the join on every table.
      if (isset($tables[$table_name]['condition'])) {
        $tables[$table_name]['condition'] = $this->condition_namespace($tables[$table_name]['condition']);
      }
    }
    // Namespace fields.
    foreach (array_keys($fields) as $field_name) {
      $fields[$field_name]['table'] .= $this->subquery_namespace;
      $fields[$field_name]['alias'] .= $this->subquery_namespace;
    }
    // Namespace conditions.
    $where =& $subquery->conditions();
    $this->alter_subquery_condition($subquery, $where);
    // Not sure why, but our sort order clause doesn't have a table.
    // TODO: the call to add_item() above to add the sort handler is probably
    // wrong -- needs attention from someone who understands it.
    // In the meantime, this works, but with a leap of faith...
    $orders =& $subquery->getOrderBy();
    foreach ($orders as $order_key => $order) {
      // But if we're using a whole view, we don't know what we have!
      if ($options['subquery_view']) {
        list($sort_table, $sort_field) = explode('.', $order_key);
      }
      $orders[$sort_table . $this->subquery_namespace . '.' . $sort_field] = $order;
      unset($orders[$order_key]);
    }

    // The query we get doesn't include the LIMIT, so add it here.
    $subquery->range(0, 1);

    // Extract the SQL the temporary view built.
    $subquery_sql = $subquery->__toString();

    // Replace the placeholder with the outer, correlated field.
    // Eg, change the placeholder ':users_uid' into the outer field 'users.uid'.
    // We have to work directly with the SQL, because putting a name of a field
    // into a SelectQuery that it does not recognize (because it's outer) just
    // makes it treat it as a string.
    $outer_placeholder = ':' . str_replace('.', '_', $this->definition['outer field']);
    $subquery_sql = str_replace($outer_placeholder, $this->definition['outer field'], $subquery_sql);

    return $subquery_sql;
  }

views_handler::needs_style_plugin ( ) [inherited]

Determine if the argument needs a style plugin.

Returns:: TRUE/FALSE

Reimplemented in views_handler_argument.

Definition at line 654 of file handlers.inc.

{ return FALSE; }

views_handler_relationship_groupwise_max::option_definition ( )

Defines default values for options.

Reimplemented from views_handler_relationship.

Definition at line 61 of file views_handler_relationship_groupwise_max.inc.

References views_object::$options.

                               {
    $options = parent::option_definition();

    $options['subquery_sort'] = array('default' => NULL);
    // Descending more useful.
    $options['subquery_order'] = array('default' => 'DESC');
    $options['subquery_regenerate'] = array('default' => FALSE);
    $options['subquery_view'] = array('default' => FALSE);
    $options['subquery_namespace'] = array('default' => FALSE);

    return $options;
  }

views_object::options ( &$ options ) [inherited]

Set default options on this object.

Called by the constructor in a complex chain to deal with backward compatibility.

Reimplemented in views_plugin_style_default.

Definition at line 60 of file base.inc.

{ }

views_handler_relationship_groupwise_max::options_form	(	&$	form,
		&$	form_state
	)

Extends the relationship's basic options, allowing the user to pick a sort and an order for it.

Reimplemented from views_handler_relationship.

Definition at line 78 of file views_handler_relationship_groupwise_max.inc.

References views_object::options(), views_fetch_data(), views_fetch_fields(), and views_get_all_views().

                                              {
    parent::options_form($form, $form_state);

    // Get the sorts that apply to our base.
    $sorts = views_fetch_fields($this->definition['base'], 'sort');
    foreach ($sorts as $sort_id => $sort) {
      $sort_options[$sort_id] = "$sort[group]: $sort[title]";
    }
    $base_table_data = views_fetch_data($this->definition['base']);

    $form['subquery_sort'] = array(
      '#type' => 'select',
      '#title' => t('Representative sort criteria'),
      // Provide the base field as sane default sort option.
      '#default_value' => !empty($this->options['subquery_sort']) ? $this->options['subquery_sort'] : $this->definition['base'] . '.' . $base_table_data['table']['base']['field'],
      '#options' => $sort_options,
      '#description' => theme('advanced_help_topic', array('module' => 'views', 'topic' => 'relationship-representative')) .
        t("The sort criteria is applied to the data brought in by the relationship to determine how a representative item is obtained for each row. For example, to show the most recent node for each user, pick 'Content: Updated date'."),
    );

    $form['subquery_order'] = array(
      '#type' => 'radios',
      '#title' => t('Representative sort order'),
      '#description' => t("The ordering to use for the sort criteria selected above."),
      '#options' => array('ASC' => t('Ascending'), 'DESC' => t('Descending')),
      '#default_value' => $this->options['subquery_order'],
    );

    $form['subquery_namespace'] = array(
      '#type' => 'textfield',
      '#title' => t('Subquery namespace'),
      '#description' => t('Advanced. Enter a namespace for the subquery used by this relationship.'),
      '#default_value' => $this->options['subquery_namespace'],
    );


    // WIP: This stuff doens't work yet: namespacing issues.
    // A list of suitable views to pick one as the subview.
    $views = array('' => '<none>');
    $all_views = views_get_all_views();
    foreach ($all_views as $view) {
      // Only get views that are suitable:
      // - base must the base that our relationship joins towards
      // - must have fields.
      if ($view->base_table == $this->definition['base'] && !empty($view->display['default']->display_options['fields'])) {
        // TODO: check the field is the correct sort?
        // or let users hang themselves at this stage and check later?
        if ($view->type == 'Default') {
          $views[t('Default Views')][$view->name] = $view->name;
        }
        else {
          $views[t('Existing Views')][$view->name] = $view->name;
        }
      }
    }

    $form['subquery_view'] = array(
      '#type' => 'select',
      '#title' => t('Representative view'),
      '#default_value' => $this->options['subquery_view'],
      '#options' => $views,
      '#description' => t('Advanced. Use another view to generate the relationship subquery. This allows you to use filtering and more than one sort. If you pick a view here, the sort options above are ignored. Your view must have the ID of its base as its only field, and should have some kind of sorting.'),
    );

    $form['subquery_regenerate'] = array(
      '#type' => 'checkbox',
      '#title' => t('Generate subquery each time view is run.'),
      '#default_value' => $this->options['subquery_regenerate'],
      '#description' => t('Will re-generate the subquery for this relationship every time the view is run, instead of only when these options are saved. Use for testing if you are making changes elsewhere. WARNING: seriously impairs performance.'),
    );
  }

views_handler_relationship_groupwise_max::options_submit	(	&$	form,
		&$	form_state
	)

Perform any necessary changes to the form values prior to storage.

There is no need for this function to actually store the data.

Generate the subquery string when the user submits the options, and store it. This saves the expense of generating it when the view is run.

Reimplemented from views_handler.

Definition at line 157 of file views_handler_relationship_groupwise_max.inc.

References left_query(), and views_object::options().

                                                {
    // Get the new user options from the form values.
    $new_options = $form_state['values']['options'];
    $subquery = $this->left_query($new_options);
    // Add the subquery string to the options we're about to store.
    $this->options['subquery_string'] = $subquery;
  }

views_handler::options_validate	(	&$	form,
		&$	form_state
	)			`[inherited]`

Validate the options form.

Reimplemented in views_handler_argument, views_handler_field_serialized, views_handler_filter, views_handler_filter_date, and views_handler_sort.

Definition at line 372 of file handlers.inc.

{ }

views_handler::placeholder ( ) [inherited]

Provides a unique placeholders for handlers.

Definition at line 595 of file handlers.inc.

References views_object::options().

Referenced by views_handler_filter_search::query(), views_handler_argument_search::query(), views_handler_argument_node_uid_revision::query(), views_handler_field_field::query(), views_handler_filter_string::query(), views_handler_filter_group_by_numeric::query(), views_handler_argument_string::query(), views_handler_argument_numeric::query(), views_handler_argument_group_by_numeric::query(), views_handler_argument_formula::query(), and views_handler_argument_string::summary_query().

                         {
    return $this->query->placeholder($this->options['table'] . '_' . $this->options['field']);
  }

views_handler::post_execute ( &$ values ) [inherited]

Run after the view is executed, before the result is cached.

This gives all the handlers some time to modify values. This is primarily used so that handlers that pull up secondary data can put it in the $values so that the raw data can be utilized externally.

Reimplemented in views_handler_field_field.

Definition at line 590 of file handlers.inc.

{ }

views_handler::pre_query ( ) [inherited]

Run before the view is built.

This gives all the handlers some time to set up before any handler has been fully run.

Reimplemented in views_handler_argument_term_node_tid_depth_modifier.

Definition at line 581 of file handlers.inc.

{ }

views_handler_relationship_groupwise_max::query ( )

Called to implement a relationship in a query.

This is mostly a copy of our parent's query() except for this bit with the join class.

Reimplemented from views_handler_relationship.

Definition at line 340 of file views_handler_relationship_groupwise_max.inc.

References views_handler::ensure_my_table(), left_query(), views_object::options(), and views_fetch_data().

                   {
    // Figure out what base table this relationship brings to the party.
    $table_data = views_fetch_data($this->definition['base']);
    $base_field = empty($this->definition['base field']) ? $table_data['table']['base']['field'] : $this->definition['base field'];

    $this->ensure_my_table();

    $def = $this->definition;
    $def['table'] = $this->definition['base'];
    $def['field'] = $base_field;
    $def['left_table'] = $this->table_alias;
    $def['left_field'] = $this->field;
    if (!empty($this->options['required'])) {
      $def['type'] = 'INNER';
    }

    if ($this->options['subquery_regenerate']) {
      // For testing only, regenerate the subquery each time.
      $def['left_query'] = $this->left_query($this->options);
    }
    else {
      // Get the stored subquery SQL string.
      $def['left_query'] = $this->options['subquery_string'];
    }

    if (!empty($def['join_handler']) && class_exists($def['join_handler'])) {
      $join = new $def['join_handler'];
    }
    else {
      $join = new views_join_subquery();
    }

    $join->definition = $def;
    $join->construct();
    $join->adjusted = TRUE;

    // use a short alias for this:
    $alias = $def['table'] . '_' . $this->table;

    $this->alias = $this->query->add_relationship($alias, $join, $this->definition['base'], $this->relationship);
  }

views_handler::sanitize_value	(	$	value,
		$	type = `NULL`
	)			`[inherited]`

Sanitize the value for output.

Parameters:

	$value	The value being rendered.
	$type	The type of sanitization needed. If not provided, check_plain() is used.

Definition at line 317 of file handlers.inc.

                                                {
    switch ($type) {
      case 'xss':
        $value = filter_xss($value);
        break;
      case 'url':
        $value = check_url($value);
        break;
      default:
        $value = check_plain($value);
        break;
    }
    return $value;
  }

views_object::set_default_options ( ) [inherited]

Set default options.

For backward compatibility, it sends the options array; this is a feature that will likely disappear at some point.

Definition at line 67 of file base.inc.

References views_object::option_definition(), and views_object::options().

Referenced by views_object::construct().

                                 {
    $this->_set_option_defaults($this->options, $this->option_definition());

    // Retained for complex defaults plus backward compatibility.
    $this->options($this->options);
  }

views_object::set_definition ( $ definition ) [inherited]

Let the handler know what its full definition is.

Definition at line 173 of file base.inc.

                                       {
    $this->definition = $definition;
    if (isset($definition['field'])) {
      $this->real_field = $definition['field'];
    }
  }

views_handler::set_relationship ( ) [inherited]

Called just prior to query(), this lets a handler set up any relationship it needs.

Definition at line 603 of file handlers.inc.

References views_handler::$relationship, and views_object::options().

                              {
    // Ensure this gets set to something.
    $this->relationship = NULL;

    // Don't process non-existant relationships.
    if (empty($this->options['relationship']) || $this->options['relationship'] == 'none') {
      return;
    }

    $relationship = $this->options['relationship'];

    // Ignore missing/broken relationships.
    if (empty($this->view->relationship[$relationship])) {
      return;
    }

    // Check to see if the relationship has already processed. If not, then we
    // cannot process it.
    if (empty($this->view->relationship[$relationship]->alias)) {
      return;
    }

    // Finally!
    $this->relationship = $this->view->relationship[$relationship]->alias;
  }

views_handler::show_expose_button	(	&$	form,
		&$	form_state
	)			`[inherited]`

Shortcut to display the expose/hide button.

Reimplemented in views_handler_filter, and views_handler_sort.

Definition at line 534 of file handlers.inc.

{ }

views_handler::show_expose_form	(	&$	form,
		&$	form_state
	)			`[inherited]`

Shortcut to display the exposed options form.

Definition at line 539 of file handlers.inc.

References views_handler::expose_form(), and views_object::options().

Referenced by views_handler_sort::options_form(), and views_handler_filter::options_form().

                                                  {
    if (empty($this->options['exposed'])) {
      return;
    }

    $this->expose_form($form, $form_state);

    // When we click the expose button, we add new gadgets to the form but they
    // have no data in $_POST so their defaults get wiped out. This prevents
    // these defaults from getting wiped out. This setting will only be TRUE
    // during a 2nd pass rerender.
    if (!empty($form_state['force_expose_options'])) {
      foreach (element_children($form['expose']) as $id) {
        if (isset($form['expose'][$id]['#default_value']) && !isset($form['expose'][$id]['#value'])) {
          $form['expose'][$id]['#value'] = $form['expose'][$id]['#default_value'];
        }
      }
    }
  }

views_handler::store_exposed_input	(	$	input,
		$	status
	)			`[inherited]`

If set to remember exposed input in the session, store it there.

Reimplemented in views_handler_filter.

Definition at line 674 of file handlers.inc.

{ return TRUE; }

views_handler::ui_name ( $ short = FALSE ) [inherited]

Return a string representing this handler's name in the UI.

Reimplemented in views_handler_area_broken, views_handler_argument_broken, views_handler_argument_group_by_numeric, views_handler_field, views_handler_field_broken, views_handler_filter_broken, views_handler_filter_group_by_numeric, views_handler_relationship_broken, views_handler_sort_broken, and views_handler_sort_group_by_numeric.

Definition at line 269 of file handlers.inc.

References views_object::options().

Referenced by views_handler::groupby_form(), views_handler_relationship::label(), views_handler_area::label(), and views_handler_filter_in_operator::validate().

                                   {
    if (!empty($this->options['ui_name'])) {
      $title = check_plain($this->options['ui_name']);
      return $title;
    }
    $title = ($short && isset($this->definition['title short'])) ? $this->definition['title short'] : $this->definition['title'];
    return t('!group: !title', array('!group' => $this->definition['group'], '!title' => $title));
  }

views_object::unpack_options	(	&$	storage,
		$	options,
		$	definition = `NULL`,
		$	all = `TRUE`,
		$	check = `TRUE`,
		$	localization_keys = `array()`
	)			`[inherited]`

Unpack options over our existing defaults, drilling down into arrays so that defaults don't get totally blown away.

Definition at line 93 of file base.inc.

References views_object::$options, and views_object::option_definition().

Referenced by views_plugin_style::init(), views_plugin_row::init(), views_plugin_query::init(), views_plugin_pager::init(), views_plugin_exposed_form::init(), views_plugin_cache::init(), views_plugin_argument_validate::init(), views_plugin_argument_default::init(), views_plugin_access::init(), and views_handler::init().

                                                                                                                             {
    if ($check && !is_array($options)) {
      return;
    }

    if (!isset($definition)) {
      $definition = $this->option_definition();
    }

    if (!empty($this->view)) {
      // Ensure we have a localization plugin.
      $this->view->init_localization();

      // Set up default localization keys. Handlers and such set this for us
      if (empty($localization_keys) && isset($this->localization_keys)) {
        $localization_keys = $this->localization_keys;
      }
      // but plugins don't because there isn't a common init() these days.
      else if (!empty($this->is_plugin)) {
        if ($this->plugin_type != 'display') {
          $localization_keys = array($this->view->current_display);
          $localization_keys[] = $this->plugin_type;
        }
      }
    }

    foreach ($options as $key => $value) {
      if (is_array($value)) {
        // Ignore arrays with no definition.
        if (!$all && empty($definition[$key])) {
          continue;
        }

        if (!isset($storage[$key]) || !is_array($storage[$key])) {
          $storage[$key] = array();
        }

        // If we're just unpacking our known options, and we're dropping an
        // unknown array (as might happen for a dependent plugin fields) go
        // ahead and drop that in.
        if (!$all && isset($definition[$key]) && !isset($definition[$key]['contains'])) {
          $storage[$key] = $value;
          continue;
        }

        $this->unpack_options($storage[$key], $value, isset($definition[$key]['contains']) ? $definition[$key]['contains'] : array(), $all, FALSE, array_merge($localization_keys, array($key)));
      }
      // Don't localize strings during editing. When editing, we need to work with
      // the original data, not the translated version.
      else if (empty($this->view->editing) && !empty($definition[$key]['translatable']) && !empty($value) || !empty($definition['contains'][$key]['translatable']) && !empty($value)) {
        if (!empty($this->view) && $this->view->is_translatable()) {
          // Allow other modules to make changes to the string before it's
          // sent for translation.
          // The $keys array is built from the view name, any localization keys
          // sent in, and the name of the property being processed.
          $format = NULL;
          if (isset($definition[$key]['format_key']) && isset($options[$definition[$key]['format_key']])) {
            $format = $options[$definition[$key]['format_key']];
          }
          $translation_data = array(
            'value' => $value,
            'format' => $format,
            'keys' => array_merge(array($this->view->name), $localization_keys, array($key)),
          );
          $storage[$key] = $this->view->localization_plugin->translate($translation_data);
        }
        // Otherwise, this is a code-based string, so we can use t().
        else {
          $storage[$key] = t($value);
        }
      }
      else if ($all || !empty($definition[$key])) {
        $storage[$key] = $value;
      }
    }
  }

views_object::unpack_translatable	(	&$	translatable,
		$	storage,
		$	option,
		$	definition,
		$	parents,
		$	keys = `array()`
	)			`[inherited]`

Unpack a single option definition.

This function run's through all suboptions recursive.

Parameters:

	$translatable	Stores all available translatable items.
	$storage
	$option
	$definition
	$parents
	$keys

Definition at line 275 of file base.inc.

References views_object::$options.

Referenced by views_object::unpack_translatables().

                                                                                                          {
    // Do not export options for which we have no settings.
    if (!isset($storage[$option])) {
      return;
    }

    // Special handling for some items
    if (isset($definition['unpack_translatable']) && method_exists($this, $definition['unpack_translatable'])) {
      return $this->{$definition['unpack_translatable']}($translatable, $storage, $option, $definition, $parents, $keys);
    }

    if (isset($definition['translatable'])) {
      if ($definition['translatable'] === FALSE) {
        return;
      }
    }

    // Add the current option to the parents tree.
    $parents[] = $option;

    // If it has child items, unpack those separately.
    if (isset($definition['contains'])) {
      foreach ($definition['contains'] as $sub_option => $sub_definition) {
        $translation_keys = array_merge($keys, array($sub_option));
        $this->unpack_translatable($translatable, $storage[$option], $sub_option, $sub_definition, $parents, $translation_keys);
      }
    }

    // @todo Figure out this double definition stuff.
    $options = $storage[$option];
    if (is_array($options)) {
      foreach ($options as $key => $value) {
        $translation_keys = array_merge($keys, array($key));
        if (is_array($value)) {
          $this->unpack_translatable($translatable, $options, $key, $definition, $parents, $translation_keys);
        }
        else if (!empty($definition[$key]['translatable']) && !empty($value)) {
          // Build source data and add to the array
          $format = NULL;
          if (isset($definition['format_key']) && isset($options[$definition['format_key']])) {
            $format = $options[$definition['format_key']];
          }
          $translatable[] = array(
            'value' => $value,
            'keys' => $translation_keys,
            'format' => $format,
          );
        }
      }
    }
    else if (!empty($definition['translatable']) && !empty($options)) {
      $value = $options;
      // Build source data and add to the array
      $format = NULL;
      if (isset($definition['format_key']) && isset($storage[$definition['format_key']])) {
        $format = $options[$definition['format_key']];
      }
      $translatable[] = array(
        'value' => $value,
        'keys' => isset($translation_keys) ? $translation_keys : $parents,
        'format' => $format,
      );
    }
  }

views_object::unpack_translatables	(	&$	translatable,
		$	parents = `array()`
	)			`[inherited]`

Unpacks each handler to store translatable texts.

Definition at line 256 of file base.inc.

References views_object::option_definition(), views_object::options(), and views_object::unpack_translatable().

                                                                    {
    foreach ($this->option_definition() as $option => $definition) {
      $this->unpack_translatable($translatable, $this->options, $option, $definition, $parents, array());
    }
  }

views_handler_relationship::use_group_by ( ) [inherited]

You can't groupby a relationship.

Reimplemented from views_handler.

Definition at line 152 of file views_handler_relationship.inc.

                          {
    return FALSE;
  }

views_handler::validate ( ) [inherited]

Validates the handler against the complete View.

This is called when the complete View is being validated. For validating the handler options form use options_validate().

See also:: views_handler::options_validate()

Returns:: Empty array if the handler is valid; an array of error strings if it is not.

Reimplemented in views_handler_filter_in_operator.

Definition at line 710 of file handlers.inc.

{ return array(); }

Member Data Documentation

views_handler::$handler_type = NULL [inherited]

The type of the handler, for example filter/footer/field.

Definition at line 170 of file handlers.inc.

views_object::$options = array() [inherited]

Except for displays, options for the object will be held here.

Definition at line 15 of file base.inc.

views_handler::$real_field [inherited]

The actual field in the database table, maybe different on other kind of query plugins/special handlers.

Definition at line 181 of file handlers.inc.

views_handler::$relationship = NULL [inherited]

The relationship used for this field.

Definition at line 186 of file handlers.inc.

Referenced by views_handler_field_entity::query(), and views_handler::set_relationship().

views_handler::$table_alias [inherited]

The alias of the table of this handler which is used in the query.

Definition at line 175 of file handlers.inc.

Referenced by views_handler_field::add_additional_fields().

The documentation for this class was generated from the following file:

handlers/views_handler_relationship_groupwise_max.inc

views_handler_relationship_groupwise_max Class Reference [Views' relationship handlers]

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

Member Data Documentation

views_handler_relationship_groupwise_max Class Reference
[Views' relationship handlers]